Appearance
Kiro CLI Tool Search 适合 MCP server 较多、工具 schema 占用大量上下文的团队。它不会把所有 MCP tool 定义一次性塞进请求，而是先建立索引，再让 agent 按需检索和加载工具，从而降低 token 压力并保持工具可发现性。
Kiro CLI Tool Search：按需加载 MCP 工具，释放上下文窗口
当你给 Kiro CLI 配置多个 MCP server 后，真正的问题往往不是“工具不够”，而是“工具太多”。每个 MCP tool 都带有名称、描述、参数 schema，如果每轮对话都完整发送，长会话很容易被工具定义占满上下文窗口。
Tool Search 的作用是把这些 MCP tool 改成“按需加载”：Kiro CLI 先索引工具信息，只向模型提供精简后的工具列表；当 agent 判断需要某个工具时，再通过 tool_search 找到并激活完整 schema。
什么时候应该开启 Tool Search
建议在以下情况开启：
- 已配置 5 个或更多 MCP servers。
- 长对话中经常遇到 context window overflow。
- 运行
/tools后发现 MCP tools 总计占用超过 50,000 tokens。 - 团队把搜索、知识库、项目管理、云资源等多类 MCP server 都接入了 Kiro CLI。
如果你只使用少量 MCP tools，Tool Search 反而会增加一次检索步骤，收益不明显。它更适合“工具很多，但每个任务只会用到其中一小部分”的环境。
启用 Tool Search
Tool Search 默认关闭。可以通过 Kiro CLI settings 开启：
bash
kiro-cli settings toolSearch.enabled true开启后，Kiro CLI 会在 MCP tool specs 足够大时自动启用延迟加载。默认阈值是：
- MCP tool specs 超过 context window 的 5%。
- 或 MCP tool specs 超过 50,000 tokens。
这两个条件是 OR 关系，满足任意一个就会触发 Tool Search。
如果你希望只要存在 MCP tools 就强制启用，可以把两个阈值都设为 0：
bash
kiro-cli settings toolSearch.minPct 0
kiro-cli settings toolSearch.minTokens 0配置项说明
| Setting | Default | 作用 |
|---|---|---|
toolSearch.enabled | false | Tool Search 总开关 |
toolSearch.minPct | 5 | MCP tool specs 超过 context window 百分比时启用 |
toolSearch.minTokens | 50000 | MCP tool specs 超过指定 token 数时启用 |
企业管理员可以把这些配置写入团队推荐配置中，但不要盲目把所有环境都设成强制开启。更稳妥的做法是先让工具密集型项目开启，再根据 /tools 输出观察 token 变化。
如何确认 Tool Search 已生效
可以用两个信号判断：
- 运行
/tools，对比开启前后 MCP tools 的 token 占用。生效后，展示的工具上下文应该明显减少。 - 查看 agent 工具调用记录。如果 agent 在任务中发现工具，会出现
tool_search调用。
注意：Tool Search 不等于禁用 MCP tools。它只是把“全量预加载”改成“先索引、后加载”，因此工具仍然可以被 agent 使用。
Tool Search 的工作机制
Tool Search 的流程可以理解为四步：
- Indexing：MCP servers 连接后，Kiro CLI 会索引所有 tool specs，包括 tool name、server name、description 和参数说明。
- Deferred tool list：模型不会收到完整 JSON schema，而是收到类似
server_name::tool_name: description的紧凑列表，描述会截断到 1KB。 - On-demand loading：模型需要工具时，调用
tool_search，可以用精确tool_id，也可以用关键词query。 - Activation：匹配到的工具会被加载，完整 schema 会出现在后续请求中，agent 才能真正调用它。
这套机制适合 MCP 生态逐渐扩大的场景：工具目录可以很大，但每轮任务只加载必要工具。
tool_search 内置工具
tool_search 是 Kiro CLI 的内置只读工具，用来查找并加载 MCP tools。它不会触发额外的用户授权提示。
| Parameter | Type | Required | 说明 |
|---|---|---|---|
tool_id | string | tool_id 或 query 二选一 | 精确工具 ID，格式为 server_name::tool_name |
query | string | tool_id 或 query 二选一 | 用关键词搜索匹配的工具 |
max_results | integer | 否 | 返回结果数量，默认 5 |
调用时必须只提供 tool_id 或 query 其中一个，不能同时提供。匹配到的工具会立即激活，后续即可被 agent 调用。
关键词匹配规则
Tool Search 使用 BM25 relevance scoring 做关键词匹配。为了提高命中率，工具名会按大小写边界和下划线拆词，例如：
ReadFile会拆成read file。read_file也会拆成read file。
默认匹配阈值是 1.5，可以通过环境变量调整：
bash
KIRO_CLI_TOOL_SEARCH_MATCHING_THRESHOLD=1.5一般不建议先改阈值。只有当你明确发现“相关工具搜不到”或“无关工具太多”时，再做小幅调整。
下一步
- 查看 Built-in tools 了解包括
tool_search在内的内置工具。 - 查看 Settings reference 了解
toolSearch.*配置。 - 查看 MCP configuration 学习如何配置 MCP servers。
- 查看 Terminal UI 观察实时 shell output 和工具显示。
常见问题
Tool Search 会让 MCP tools 变慢吗？
首次发现工具时会多一次 tool_search 检索，但换来的是更小的上下文负担。MCP server 很多时，这个取舍通常是值得的。
Tool Search 会影响权限审批吗？
tool_search 本身是只读内置工具，默认自动允许。但被激活后的 MCP tool 是否需要审批，仍取决于该工具自身的能力和 Kiro CLI 的权限策略。
只有一个 MCP server 需要开启吗？
通常不需要。除非这个 MCP server 暴露了大量 tools，导致 /tools 显示 token 占用很高，否则默认关闭即可。