Semantic tool search with embeddings for scalable tool discovery. Enables on-demand tool loading to reduce context usage by 90%+ for large tool libraries.
Semantic tool search with embeddings for scalable tool discovery. Enables on-demand tool loading to reduce context usage by 90%+ for large tool libraries.
version
1.0.0
model
sonnet
invoked_by
both
user_invocable
true
tools
["Read","Write","Grep","Glob"]
best_practices
["Use for tool libraries with 10+ tools","Keep 3-5 most-used tools always loaded","Use clear, descriptive tool names","Add system prompt guidance"]
error_handling
graceful
streaming
supported
verified
false
lastVerifiedAt
"2026-02-19T05:29:09.098Z"
source
builtin
trust_score
100
provenance_sha
068a55cd5b5bb7c0
References (archive):SCAFFOLD_SKILLS_ARCHIVE_MAP.md — embedding/semantic tool discovery from everything-claude-code backend-patterns, tdd-workflow.
Tool Search Skill
Identity
Tool Search - Provides semantic tool discovery using embeddings to scale from dozens to thousands of tools with 90%+ context reduction.
Capabilities
Semantic Tool Search: Find relevant tools based on task context
Embedding-Based Matching: Use embeddings for accurate tool discovery
On-Demand Loading: Load tools only when needed
Context Efficiency: 90%+ reduction in tool definition tokens
The Problem
Traditional tool loading:
All tools loaded upfront
58 tools = ~55K tokens
Context fills quickly
Hard to scale beyond ~100 tools
The Solution
Tool Search with Embeddings:
Only Tool Search Tool loaded initially (~500 tokens)
Tools discovered on-demand via semantic search
3-5 relevant tools loaded per search (~3K tokens)
Total: ~8.7K tokens vs. ~77K traditional (85% reduction)
How It Works
Initial State: Only Tool Search Tool + critical tools loaded
Tool Discovery: Agent searches for tools based on task
Semantic Matching: Embeddings match tools to task context
Tool Expansion: Matching tools expanded into full definitions
Building MCP-powered systems with multiple servers
Less Beneficial When:
Small tool library (<10 tools)
All tools used frequently in every session
Tool definitions are compact
Tool Discovery
Agent Workflow:
Agent needs capability (e.g., "create a pull request")
Agent searches: "github pull request creation"
Tool Search returns: create_pull_request tool
Tool expanded into full definition
Agent uses tool
Example:
User: "Create a pull request for my changes"
Agent searches: "github pull request creation"
Tool Search finds: create_pull_request tool
Tool loaded and used
Best Practices
1. Clear Tool Names and Descriptions
Good:
{"name":"search_customer_orders","description":"Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info."}
Bad:
{"name":"query_db_orders","description":"Execute order query"}
2. System Prompt Guidance
Add guidance in agent prompts:
You have access to tools for Slack messaging, Google Drive file management,
Jira ticket tracking, and GitHub repository operations. Use the tool search
to find specific capabilities when needed.
3. Keep Critical Tools Always Loaded
Don't defer loading for:
Core file operations
Essential integrations
Frequently used tools
4. Monitor Tool Usage
Track which tools are discovered:
Most searched tools
Tool discovery patterns
Context savings achieved
Implementation
Embedding-Based Tool Search
The tool search uses embeddings to match tools to queries:
Tool Indexing: Create embeddings for all tool definitions
Query Embedding: Create embedding for user query
Similarity Search: Find tools with similar embeddings
Result: Optimal tool usage with minimal token consumption
Example Workflow:
# Tool Search finds tools
tools = search_tools("github issue management")
# PTC orchestrates multiple tool calls
team = await get_team_members("engineering")
issues = await asyncio.gather(*[
get_issue(member["github_username"]) for member in team
])
# Only final results in context, not all intermediate data
