claude-advanced-tool-use

Claude Advanced Tool Use（Claude 高级工具使用）围绕生产系统中工具编排的常见瓶颈，提供三项互补能力，可单独使用，也可组合以获得叠加的效率提升。

用途与定位

该技能面向需要在生产环境中扩展工具规模、优化 token 消耗并提高工具调用准确性的开发者。资料建议从当前最大的瓶颈入手，再按需叠加其他能力，并非必须一次性全部启用。

三项核心能力

1. 工具搜索（Tool Search）

动态、按需发现并加载工具，可在不造成上下文膨胀的前提下扩展到一万以上工具。提供两种变体：正则模式匹配与 BM25 自然语言查询。通过延迟加载（deferred loading），工具定义在需要前不进入上下文，资料称可带来 85%–95% 的上下文节省。

2. 程序化工具调用（Programmatic Tool Calling）

Claude 在沙箱容器中编写 Python 代码来调用工具，中间结果保留在上下文窗口之外。资料称可减少约 37% 的 token，并在复杂工作流中消除 19 次以上不必要的推理过程。适用于数据聚合、过滤与多步骤编排。

3. 工具使用示例（Tool Use Examples）

用具体的调用示例澄清含糊的 JSON Schema，提升参数处理准确性，表达 Schema 无法承载的 API 约定，并减少对可选参数的幻觉。资料称准确率从 72% 提升至 90%。

功能对比

工具搜索：节省 85%–95% token，适合大型工具集（10 个以上工具），复杂度低，Beta 头为 advanced-tool-use-2025-11-20。
程序化调用：节省 37% token，适合多步骤工作流（3 个以上有依赖的调用），复杂度中等，Beta 头为 advanced-tool-use-2025-11-20。
工具示例：提升准确率（72%→90%），适合复杂参数与可选字段，复杂度低，无 Beta 头。

适用场景

工具搜索：系统中工具超过 10 个；工具定义合计超过 1 万 token；工具集过大导致选择准确性下降；使用 MCP 服务器（跨服务器 200 个以上工具）；工具库随时间增长。

程序化调用：含 3 个以上有依赖工具调用的工作流；处理大型数据集且仅需摘要；跨多个项目的批量操作；基于中间结果的条件逻辑；组合多数据源的聚合任务。

工具示例：JSON Schema 无法表达何时使用可选参数；需要澄清 API 约定；参数处理准确率低于 80%；减少复杂工具输入上的幻觉。

生产模式：构建可扩展的智能体系统；实现安全优先的工具编排；优化生产环境的 token 成本；高效协调多个工具。

使用方式

资料提供了“工具搜索 + 延迟加载”的 Python 快速入门示例：

import anthropic

client = anthropic.Anthropic()

tools = [
    # Always-loaded: tool search itself
    {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
    },
    # Always-loaded: frequently used tools (3-5 total)
    {
        "name": "get_user_info",
        "description": "Get user information by ID",
        "input_schema": {
            "type": "object",
            "properties": {
                "user_id": {"type": "string"}
            }
        }
    },
    # Deferred: specialized tools loaded on-demand
    {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            }
        },
        "defer_loading": True
    },
    {
        "name": "get_forecast",
        "description": "Get weather forecast for a location and days ahead",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {"type": "string"},
                "days": {"type": "integer"}
            }
        },
        "defer_loading": True
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": "What's the weather in San Francisco?"
    }],
    tools=tools
)

print(response.content[0].text)

该示例的执行流程为：Claude 分析请求并判断需要天气工具；使用 tool_search_tool_regex 以模式 "weather" 检索；API 返回指向匹配工具的 tool_reference 块；工具定义自动展开；Claude 以合适参数调用 get_weather；只有被发现的工具加载进上下文（约 85% 节省）。

叠加效应

资料给出一个大型 MCP 系统的示例：通过 MCP 服务器提供 200 个以上工具；工具搜索将上下文减少 85%（1 万 token → 1500 token）；程序化调用减少 37% 工作流 token；工具示例将准确率从 72% 提升至 90%。综合效果为约 90% 的 token 减少加 18% 的准确率提升。

实施策略建议：当定义超过 1 万 token 时先启用工具搜索；为多步骤工作流加入程序化调用；为参数复杂的工具添加示例；在每一步测量效率提升；基于瓶颈分析迭代。

生产架构模式

资料基于对生产代码库的分析列出以下模式：

规划器 + 执行器：将规划对话与执行分离，规划器决定做什么，执行器以聚焦的上下文执行，减少重复规划开销。
先预览后获取：先返回 ID 或摘要，再按需获取完整文档，保持上下文精简。
守卫 + 执行：执行前校验参数，服务端校验并返回可操作的错误，采取安全优先策略。
摘要化输出：在继续前压缩工具结果，与程序化调用配合良好，仅摘要进入上下文窗口。

资料提到可参阅 references/production-patterns.md 获取完整实现模板。

性能优化

识别瓶颈的方法：工具定义超过 1 万 token 时启用工具搜索；中间数据集庞大时使用程序化调用；参数混淆时提供工具示例；工具调用较多时考虑程序化编排。

优化清单包括：工具描述不超过 200 字符；描述中包含语义关键词；始终加载 3–5 个最常用工具；工具命名清晰（例如 search_customer_orders 而非 query_db）；在会话内缓存工具索引；返回排序结果；启用服务端校验；在适当处对工具结果做记忆化；实施安全最佳实践；使用 trace ID 进行可观测性日志记录。

与上下文管理的集成

工具搜索与程序化调用可与上下文编辑无缝协作。工具结果清理（来自 claude-context-management）是服务端策略，按时间顺序移除较早的工具结果，保留最近 N 次工具使用，可排除特定工具（例如 web_search），并与延迟加载配合。程序化调用则让工具结果不进入上下文窗口，只有最终输出返回给 Claude。两者天然协同：更少结果加更高效的编排。

资料给出的组合示例如下：

response = client.beta.messages.create(
    model="claude-opus-4-5-20251101",
    betas=["advanced-tool-use-2025-11-20", "context-management-2025-06-27"],
    tools=tools_with_deferred_loading,
    context_management={
        "edits": [{
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 100000},
            "keep": {"type": "tool_uses", "value": 3}
        }]
    },
    messages=messages
)

限制

资料未提供定价、许可、支持平台或具体版本可用性等信息，暂未提供。实际效果数据来自资料自身陈述，需以官方文档为准。

技能介绍