tutorialintermediate

Tool search with embeddings Scale Claude applications to thousands of tools using semantic embeddings for dynamic tool discovery.

March 8, 2026cookbook

This cookbook demonstrates how to scale Claude applications from dozens to thousands of tools using semantic embeddings for dynamic tool discovery. Instead of front-loading all tool definitions (which consumes context and increases latency), the approach provides Claude with a single tool_search tool that returns relevant capabilities on demand, reducing context usage by 90%+. The guide walks through implementing client-side semantic search using SentenceTransformer embeddings to match user queries with appropriate tools from large libraries, making it practical for production applications managing extensive tool ecosystems.

Key Points

•Scale beyond ~100 tools by replacing upfront tool definitions with dynamic semantic search via a single tool_search tool
•Reduce context window consumption by 90%+ by only providing relevant tool definitions on demand rather than all tools upfront
•Convert tool definitions to human-readable text representations, then generate embedding vectors using SentenceTransformer's all-MiniLM-L6-v2 model (384-dimensional embeddings)
•Use semantic similarity matching to find relevant tools based on task context, not keyword matching, enabling better tool discovery
•Implement client-side tool search that works seamlessly with Claude's tool use API for production applications with hundreds or thousands of tools
•Structure tool library with name, description, and input_schema for each tool to enable comprehensive semantic indexing
•Apply this pattern to domain-specific tool libraries including internal APIs, database operations, and third-party integrations
•Maintain efficiency by embedding tools once and reusing embeddings across multiple queries without regenerating them

Found this useful? Add it to a playbook for a step-by-step implementation guide.

Workflow Diagram

Start Process

Step A

Step B

Step C

Complete

Quality★★★★★

Concepts

MCP Servers Context Management Skills & Tools Tool Use

Artifacts (4)

environment_setupconfig

ANTHROPIC_API_KEY=your_key_here

dependencies_installationbashcommand

pip install --only-binary :all: -q anthropic sentence-transformers numpy python-dotenv

client_initializationpythonscript

import json
import random
from datetime import datetime, timedelta
from typing import Any
import anthropic
import numpy as np
from dotenv import load_dotenv
from sentence_transformers import SentenceTransformer

# Load environment variables from .env file
load_dotenv()

# Define model constant for easy updates
MODEL = "claude-sonnet-4-6"

# Initialize Claude client (API key loaded from environment)
claude_client = anthropic.Anthropic()

# Load the SentenceTransformer model
# all-MiniLM-L6-v2 is a lightweight model with 384 dimensional embeddings
print("Loading SentenceTransformer model...")
embedding_model = SentenceTransformer("sentence-transformers/all-MiniLM-L6-v2")
print("✓ Clients initialized successfully")

tool_library_definitionpythontemplate

TOOL_LIBRARY = [
  # Weather Tools
  {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"},
        "unit": {"type": "string", "enum": ["celsius", "fahrenheit"], "description": "The unit of temperature"}
      },
      "required": ["location"]
    }
  },
  {
    "name": "get_forecast",
    "description": "Get the weather forecast for multiple days ahead",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {"type": "string", "description": "The city and state"},
        "days": {"type": "number", "description": "Number of days to forecast (1-10)"}
      },
      "required": ["location", "days"]
    }
  },
  # Finance Tools
  {
    "name": "get_stock_price",
    "description": "Get the current stock price and market data for a given ticker symbol",
    "input_schema": {
      "type": "object",
      "properties": {
        "ticker": {"type": "string", "description": "Stock ticker symbol (e.g., AAPL, GOOGL)"},
        "include_history": {"type": "boolean", "description": "Include historical data"}
      },
      "required": ["ticker"]
    }
  },
  {
    "name": "convert_currency",
    "description": "Convert an amount from one currency to another using current exchange rates",
    "input_schema": {
      "type": "object",
      "properties": {
        "amount": {"type": "number", "description": "Amount to convert"},
        "from_currency": {"type": "string", "description": "Source currency code (e.g., USD)"},
        "to_currency": {"type": "string", "description": "Target currency code (e.g., EUR)"}
      },
      "required": ["amount", "from_currency", "to_currency"]
    }
  }
]