# 通过工具搜索按需加载工具

工具搜索仅当任务需要外部工具时才允许 Copilot CLI 加载外部工具，从而保持上下文较小。

## Introduction

将 MCP 服务器和其他外部工具连接到 Copilot CLI 虽然功能强大，但你添加的每个工具都会带来代价：它的定义会占用模型上下文窗口的空间，而过长的工具菜单也会让智能体更难选出正确的工具。 按需工具加载（或“工具搜索”）可防止上下文窗口被代理不使用的工具的定义所混乱。 代理起初只有其内置工具，以及一种查找其余工具的方法；然后只有在完成任务需要时，才会加载额外工具。

工具搜索解决了与越来越多的工具相关的两个问题：

* **浪费的上下文。** 几十个工具定义就可能在智能体还没开始任何工作之前消耗 1 万到 2 万个 token。
* **工具选择准确性下降。** 一旦几十个工具同时出现在眼前，模型就更有可能选错工具。

## 会话期间发生的情况

每次输入提示时，CLI 都会检查当前工具清单，并确定是否使用工具搜索。 当工具数量少于约 30 个时，使用工具搜索带来的节省并不划算，因此 Copilot CLI 会完全跳过工具搜索，直接加载所有内容。

最初，使用工具搜索时，仅加载 CLI 的内置工具。 其他一切（MCP 工具和其他外部工具）都被阻碍了。 代理可以看到这些工具存在，大致了解这些工具的用途，但它们的完整定义尚未加载。

当代理达到需要它未加载的工具的步骤时，它会对可用工具运行快速搜索，并将最接近的匹配项拉取到上下文中。 然后，这些工具会在该次对话的后续过程中一直保留，因此只有在各自第一次被需要时才会进行查找。

第一次查找需要与模型额外进行一次交互，但由于后续每一轮都能将上下文保持在较小规模，这个成本很快就能成倍省回来。

### 始终加载的工具

一些工具跳过工具搜索并立即准备就绪：

* Copilot CLI的内置工具（grep、glob、bash、edit 等）。
* 来自你使用 `deferTools: "never"` 配置的 MCP 服务器的工具。 请参阅本文后面的 [让 MCP 服务器的工具始终保持加载状态](#keeping-an-mcp-servers-tools-always-loaded) 部分。
* 由自定义代理加载的工具。 请参阅本文后面的[在自定义代理中配置工具延后](#configuring-tool-deferral-in-custom-agents)。

## 关闭工具搜索

默认情况下，工具搜索功能处于启用状态；当你使用受支持的模型且连接了足够多的工具、足以让该功能发挥作用时，它会自动启用。 若要禁用工具搜索并返回到加载每个工具，请在个人设置中设置 `toolSearch: false` 。 请参阅“[GitHub Copilot CLI 配置目录](/zh/copilot/reference/copilot-cli-reference/cli-config-dir-reference#user-settings-copilotsettingsjson)”。

### 支持的模型

| 家庭              | 支持的版本                                          |
| --------------- | ---------------------------------------------- |
| 克劳德 (Anthropic) | 神话预览， Fable， Sonnet 4.0+， Opus 4.0+ （不是 Haiku） |
| GPT （OpenAI）    | GPT-5.4 及更高版本                                  |

在任何其他模型中，所有工具都会提前加载。

### 让 MCP 服务器的工具始终保持加载状态

有时，你可能希望特定的 MCP 服务器的工具始终位于代理的前面，例如，一个经常使用其工具的服务器，或者一个额外的搜索步骤不值得的服务器。 每个 MCP 服务器都有一个用于控制此项的 `deferTools` 设置：

* `"auto"`（默认）——服务器工具的行为与其他工具无异，超过阈值后，其处理可能会被延后。
* `"never"`- 服务器的工具始终包含在代理的工具列表中，即使工具搜索对其他所有内容都处于活动状态。

设置它的最简单方法是使用 `/mcp edit` 斜杠命令。 在编辑 MCP 服务器的表单中，将 **延后工具** 切换为 **永不**。 还可以直接在 `~/.copilot/mcp-config.json` 中设置。

```json
{
    "mcpServers": {
        "my-server": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "@example/mcp-server"],
            "deferTools": "never",
            "tools": ["*"]
        }
    }
}
```

### 在自定义代理中配置工具延后

自定义代理按名称列出其工具时，始终加载这些工具，以便代理可以立即使用这些工具。 这通常是你想要的，但如果代理声明了一组大型工具，并且只在给定的运行中触及其中一些工具，则可以将该列表交回工具搜索，以便根据需要发现工具，而不是同时加载所有工具。

对于 Markdown 代理（`.github/agents/*.md`），请将 `deferred-tool-loading: true` 添加到前置元数据中：

```markdown
---
name: my-agent
description: Works with a large catalog of tools
tools:
    - some_mcp_tool
    - another_mcp_tool
    # ...many more
deferred-tool-loading: true
---

Agent instructions here.
```

关于 `deferred-tool-loading` 设置，请注意以下事项：

* 它仅在工具搜索已启用时才会生效（也就是说，在受支持的模型上，且工具数量足以达到阈值时）。
* 这只对会为其工具命名的代理有影响。 使用通配符的 `*` 代理已使用工具搜索。

## 优化用于工具搜索的工具

工具搜索会将代理尝试执行的操作与每个工具的 **名称**、其 **描述**以及其 **参数名称和描述**进行匹配。 清晰、具体的措辞能让工具在合适的请求中显示出来：

* 根据工具的用途为其命名，以便更容易找到它们。
* 用人们实际搜索的单词来写描述，而不是模糊的。