Tool Search

Tool Search loads MCP tools on demand instead of sending every tool definition with each request. This keeps your context window clear when you have many MCP servers configured, and lets the agent discover the right tools automatically.

Enable Tool Search if:

• You have 5+ MCP servers configured
• You see context window overflow errors during long conversations
• The /tools command shows MCP tools consuming more than 50,000 tokens total

If you only use a few MCP tools, the overhead of Tool Search may not be worth it.

Tool Search is disabled by default. Enable it via settings:

kiro-cli settings toolSearch.enabled true

Once enabled, Tool Search activates automatically when MCP tool specs are large enough to benefit from deferral. The default thresholds (5% of context window or 50,000 tokens) cover most cases. To force activation whenever any MCP tools are present, set the thresholds to 0:

kiro-cli settings toolSearch.minPct 0
kiro-cli settings toolSearch.minTokens 0

Configure Tool Search behavior with these settings:

When both thresholds are set, Tool Search activates if either is exceeded (OR logic). When both thresholds are set to 0, Tool Search is always active regardless of MCP tool count.

When Tool Search is active:

• The /tools command shows reduced token counts for MCP tools compared to when it's disabled
• You'll see tool_search calls in the agent's tool usage when it discovers tools on demand

1. Indexing: When MCP servers connect, all tool specs are indexed for keyword search. Each tool's name, server name, description, and parameter descriptions are tokenized.

2. Deferred tool list: Instead of full JSON schemas, the model receives a compact list of server_name::tool_name: description entries. Descriptions are truncated to 1KB.

3. On-demand loading: When the model needs a tool, it calls tool_search with either an exact tool_id (e.g., builder-mcp::InternalSearch) or a keyword query (e.g., "search documents").

4. Activation: Matched tools are loaded and their full schemas are included in subsequent requests.

Tool name: tool_search

Finds and loads MCP tools on demand. Automatically allowed without user permission prompts (read-only).

The tool_search tool accepts the following parameters:

Provide exactly one of tool_id or query, not both. Matched tools are immediately activated and available for invocation.

Keyword search uses BM25 relevance scoring. Tool names are split on casing boundaries (e.g., ReadFile → read file, read_file → read file) to improve matching. Only results above the matching threshold are returned.

The default threshold is 1.5, configurable via the KIRO_CLI_TOOL_SEARCH_MATCHING_THRESHOLD environment variable.

• Built-in tools: All built-in tools including tool_search
• Settings reference: toolSearch.* settings
• MCP configuration: Configuring MCP servers
• Terminal UI: Real-time shell output and tool display