通过 Programmatic Tool Calling (PTC)、Dynamic Filtering、Tool Search 和 Tool Use Examples 这四种 API 级特性，开发者可以显著优化代理工作流的令牌消耗与工具调用精度。这些特性于 2026 年 2 月 18 日全面可用（GA），是构建高效、低成本 Agentic 系统的关键。

Claude Code 高级工具使用：Programmatic Tool Calling 与 Dynamic Filtering

在构建复杂的 Claude 代理（Agent）工作流时，工具调用的效率和准确性直接影响系统的成本与可靠性。传统的逐次调用模式会导致大量的中间结果占用上下文窗口，而工具定义的冗余信息也会造成不必要的令牌消耗。针对这些问题，Claude API 引入了四种高级工具使用模式，它们共同构成了优化代理性能的底层能力。理解这些特性，是设计高效 Agentic 工作流的基础。

核心特性概览与策略选择

这四种特性针对不同的瓶颈，其核心价值与节流效果如下表所示。开发者可以根据当前工作流的主要痛点，选择合适的优化层开始。

特性	解决的核心问题	令牌节省/效率提升	可用性
Programmatic Tool Calling (PTC)	多步代理循环因轮次过多消耗令牌	~37% 令牌减少	API, Foundry (GA)
Dynamic Filtering	网页搜索/抓取结果中无关内容充斥上下文	~24% 更少的输入令牌	API, Foundry (GA)
Tool Search Tool	过多的工具定义预先加载导致上下文臃肿	~85% 令牌减少	API, Foundry (GA)
Tool Use Examples	仅凭 JSON 模式无法清晰表达工具的使用模式	72% → 90% 准确率	API, Foundry (GA)

战略性分层 可以这样理解：如果你的工作流被工具定义的上下文所困扰，应优先考虑 Tool Search；如果大量中间结果是瓶颈，PTC 是首选；如果处理网络信息时噪声过大，Dynamic Filtering 能发挥作用；而如果工具调用经常因参数错误失败，则应引入 Tool Use Examples。

Programmatic Tool Calling (PTC)：用代码替代多轮推理

PTC 代表了一种范式转变。传统的工具调用模式是“用户提示 → 模型思考 → 调用工具 → 拿到结果 → 再次思考…”的循环，每一步工具调用都需要一次完整的模型推理。而 PTC 允许模型生成一段 Python 代码，在沙箱中一次性编排并执行多次工具调用，最终只将代码的 stdout 输出返回给模型进行最终回答。

工作原理与配置

启用 PTC 需要在工具定义中加入 allowed_callers 字段，并指定一个 code_execution_20250825 类型的工具。下面是一个配置示例，展示了一个被允许由代码沙箱调用的数据库查询工具：

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "query_database",
      "description": "Execute a SQL query. Returns rows as JSON objects with fields: id (str), name (str), revenue (float).",
      "input_schema": {
        "type": "object",
        "properties": {
          "sql": { "type": "string", "description": "SQL query to execute" }
        },
        "required": ["sql"]
      },
      "allowed_callers": ["code_execution_20250825"]
    }
  ]
}

allowed_callers 字段决定了工具的调用方式：

["direct"]：仅支持传统直接调用（如果省略此字段，默认行为）。
["code_execution_20250825"]：仅允许从 Python 沙箱中调用。
["direct", "code_execution_20250825"]：两种模式均可。

实践建议是为每个工具明确选择一种主要模式，这能给模型更清晰的指引。当工具通过 PTC 被调用时，响应中的 caller 字段会标识其调用来源，便于调试和日志记录。

PTC 的应用场景与代码模式

PTC 非常适合处理批量任务、条件逻辑或需要过滤大量中间数据的场景。以下是几种典型的代码模式：

批量处理：用单次推理处理 N 个数据项。

regions = ["West", "East", "Central", "North", "South"]
results = {}
for region in regions:
    data = await query_database(f"SELECT SUM(revenue) FROM sales WHERE region='{region}'")
    results[region] = data[0]["revenue"]

top = max(results.items(), key=lambda x: x[1])
print(f"Top region: {top[0]} with ${top[1]:,}")

早期终止：一旦满足条件立即停止，避免不必要的后续调用。

endpoints = ["us-east", "eu-west", "apac"]
for endpoint in endpoints:
    status = await check_health(endpoint)
    if status == "healthy":
        print(f"Found healthy endpoint: {endpoint}")
        break

数据过滤：在将结果送入上下文前，用代码进行清洗和提炼。

logs = await fetch_logs(server_id)
errors = [log for log in logs if "ERROR" in log]
print(f"Found {len(errors)} errors")
for error in errors[-10:]:
    print(error)

PTC 的核心效率在于，工具调用的结果在沙箱内部处理，不会进入 Claude 的上下文，最终只有 stdout 被送入模型。这意味着 10 次程序化调用消耗的令牌，大致相当于 1 次直接调用。但它也存在约束，例如不适用于 Bedrock/Vertex 平台，不能调用 MCP 工具，且沙箱容器有约 4.5 分钟的生存时限。

Dynamic Filtering：为网络信息降噪

Dynamic Filtering 专门解决由 web_search 和 web_fetch 工具带来的上下文膨胀问题。传统模式下，这些工具会将完整的 HTML 页面内容塞入上下文，其中包含大量导航栏、广告等无关信息。Dynamic Filtering 让模型先生成 Python 过滤代码，在沙箱中执行，只提取相关内容进入上下文。

启用与效果

要使用此特性，需要采用更新的工具类型版本（如 web_search_20260209）并设置特定的 Beta 头：anthropic-beta: code-execution-web-tools-2026-02-09。在 Sonnet 4.6 和 Opus 4.6 模型上，使用新版工具类型时此特性会默认启用。

其效果体现在两个方面：

准确率提升：在基准测试中，Opus 4.6 使用 Dynamic Filtering 后，BrowseComp 任务的准确率从 45.3% 提升至 61.6%，DeepsearchQA 的 F1 分数从 69.8% 提升至 77.3%。
令牌节省：平均可减少 24% 的输入令牌。对于 Sonnet 4.6，通常能带来成本降低；对于 Opus 4.6，由于可能生成更复杂的过滤代码，成本可能略有上升。

此特性非常适合技术文档检索、多源信息交叉验证、深度研究查询等任务。

Tool Search Tool：按需发现工具定义

当你在 MCP 服务器中配置了大量工具时（例如，每个工具定义消耗约 1.5K 令牌，50 个就是 75K），即使用户未提问，这些定义也会预先加载并占满上下文。Tool Search Tool 通过延迟加载和按需发现机制解决这个问题。

工作原理

将不常用的工具标记为 defer_loading: true，它们将被排除在初始上下文之外。当模型需要使用某个延迟加载的工具时，它会通过内置的 MCPSearch 工具来发现并获取其定义。

{
  "tools": [
    {
      "type": "mcp_toolset",
      "mcp_server_name": "google-drive",
      "default_config": { "defer_loading": true },
      "configs": {
        "search_files": { "defer_loading": false }
      }
    }
  ]
}

最佳实践是始终保持 3-5 个最常用的工具为即时加载状态，其余则延迟加载。同时，应为工具编写清晰、描述性强的名称和说明，因为工具搜索依赖这些信息进行匹配。

Claude Code 中的等效实现

值得注意的是，Tool Search 是一个 API 级特性。在 Claude Code CLI 中，自 v2.1.7 版本起，默认启用了 MCP tool search auto mode。当所有 MCP 工具的描述超过当前上下文的 10% 时，它们会被自动延迟，并通过 MCPSearch 发现。你可以通过环境变量 ENABLE_TOOL_SEARCH=auto:N（N 为 0-100 的上下文百分比）来调整这个阈值。

Tool Use Examples：用示例明确使用模式

JSON Schema 定义了工具的输入结构，但无法表达诸如“何时使用可选参数”、“哪些参数组合是合理的”、“格式惯例（如日期格式）”等使用模式。input_examples 字段通过提供具体的输入示例来补充这些信息，能显著提升模型使用工具的准确性。

{
  "name": "create_ticket",
  "description": "Create a support ticket",
  "input_schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
      "assignee": { "type": "string" },
      "labels": { "type": "array", "items": { "type": "string" } }
    },
    "required": ["title"]
  },
  "input_examples": [
    {
      "title": "Login page returns 500 error",
      "priority": "critical",
      "assignee": "oncall-team",
      "labels": ["bug", "auth", "production"]
    },
    {
      "title": "Add dark mode support",
      "priority": "low",
      "labels": ["feature-request", "ui"]
    }
  ]
}

编写示例时，应使用真实数据而非占位符，并展示多样性（最小化、部分指定、完全指定）。保持简洁，每个工具 1-5 个示例即可。重点是解决歧义，展示参数之间的关联性（例如，priority: "critical" 通常伴随 assignee）。

在 Claude Code 生态中的应用与 FAQ

这些高级特性主要面向直接使用 Claude API 或 Agent SDK 构建自定义代理的开发者。对于 Claude Code CLI 用户而言，其直接影响有限，但理解其背后的设计思想对于优化工作流至关重要。

FAQ

Q: 这些高级工具特性在 Claude Code 命令行界面中能直接使用吗？ A: 大部分不能。Dynamic Filtering、PTC 和 Tool Use Examples 是 API 级特性，在 CLI 中不可配置。但 Tool Search 在 CLI 中有内置等效实现（MCP tool search auto mode），当 MCP 工具描述过多时会自动启用，可通过 ENABLE_TOOL_SEARCH 环境变量调整。

Q: 我正在使用 Agent SDK 开发自定义代理，如何开始使用 PTC？ A: 首先，在你的工具数组中加入 code_execution_20250825 类型的工具。然后，为那些受益于批量处理或中间结果过滤的工具设置 allowed_callers: ["code_execution_20250825"]。接着，实现处理工具调用循环的逻辑（暂停 → 提供结果 → 恢复）。最后，建议让工具返回结构化数据（如 JSON），以便于代码解析。

Q: 如何优化我在自定义 MCP 服务器中定义的工具，以提高 Claude 的使用准确率？ A: 除了提供清晰的描述和结构良好的 JSON Schema 外，你应该在工具定义中添加 input_examples 字段。提供几个真实的、典型的输入示例，能够极大地帮助模型理解何时使用可选参数以及正确的输入格式。这对于构建健壮的代理工作流非常重要。

Claude Code 高级工具使用：Programmatic Tool Calling 与 Dynamic Filtering #

核心特性概览与策略选择 #

Programmatic Tool Calling (PTC)：用代码替代多轮推理 #

工作原理与配置 #

PTC 的应用场景与代码模式 #

Dynamic Filtering：为网络信息降噪 #

启用与效果 #

Tool Search Tool：按需发现工具定义 #

工作原理 #

Claude Code 中的等效实现 #

Tool Use Examples：用示例明确使用模式 #

在 Claude Code 生态中的应用与 FAQ #

FAQ #