tool-search

SKILL.md preview

---
name: tool-search
description: 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
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
---

**References (archive):** [SCAFFOLD_SKILLS_ARCHIVE_MAP.md](../../docs/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

1. **Initial State**: Only Tool Search Tool + critical tools loaded
2. **Tool Discovery**: Agent searches for tools based on task
3. **Semantic Matching**: Embeddings match tools to task context
4. **Tool Expansion**: Matching tools expanded into full definitions
5. **Tool Use**: Agent uses discovered tools

## Configuration

### MCP Configuration (`.claude/.mcp.json`)

```json
{
  "betaFeatures": ["advanced-tool-use-2025-11-20"],
  "toolSearch": {
    "enabled": true,
    "autoEnableThreshold": 20,
    "defaultDeferLoading": true
  },
  "mcpServers": {
    "repo": {
      "deferLoading": true,
      "alwaysLoadTools": ["search_code", "read_file"]
    },
    "github": {
      "deferLoading": true,
      "alwaysLoadTools": ["create_pull_request", "get_issue"]
    }
  }
}
```

### Always Load Critical Tools

Keep 3-5 most-used tools always loaded:

- Core file operations: `read_file`, `write_file`, `search_code`
- Essential integrations: `create_pull_request`, `get_issue`
- Frequently used: `take_screenshot`, `navigate_page`

## Usage Patterns

### When to Use Tool Search

**Most Beneficial When**:

- Tool definitions consuming >10K tokens
- Tool library has 10+ tools
- Experiencing tool selection accuracy issues
- 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**:

1. Agent needs capability (e.g., "create a pull request")
2. Agent searches: "github pull request creation"
3. Tool Search returns: `create_pull_request` tool
4. Tool expanded into full definition
5. 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**:

```json
{
  "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**:

```json
{
  "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 G

…