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

Introduction

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

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

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

会话期间发生的情况

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

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

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

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

始终加载的工具

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

Copilot 命令行界面（CLI）的内置工具（grep、glob、bash、edit 等）。
来自你使用 deferTools: "never" 配置的 MCP 服务器的工具。请参阅本文后面的让 MCP 服务器的工具始终保持加载状态部分。
由自定义代理加载的工具。请参阅本文后面的在自定义代理中配置工具延后。

关闭工具搜索

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

支持的模型

家庭	支持的版本
克劳德 (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 中设置。

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

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

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

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

---
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 设置，请注意以下事项：

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

优化用于工具搜索的工具

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

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

在本文中