Tool Design Principles

Tools 是 agent 与外部世界交互的主要机制，它定义了 deterministic systems 与 non-deterministic agents 的契约。与传统 API 不同，tool APIs 必须为 language model 设计：模型需要从自然语言理解意图、推断参数并生成调用。Tool design 出错会产生无法通过 prompt 修复的失败模式。

工具设计的本质是“减少模型猜测”。越清晰，越稳定。

• Tools 是 contracts，不是 Prompt 的延伸。
• 合并或拆分工具必须由权限、副作用和选择歧义共同决定。
• 好的 description 要回答 what/when/inputs/returns。
• Error messages 必须可恢复。
• 优先考虑 minimal, general-purpose tools。

你将学到什么

• 如何写出模型能正确调用的 tool description
• 何时该合并 tools，何时该拆分
• 如何设计 response format 与 error handling

什么时候需要重新设计 Tool

• 两个工具名字或 description 太相似，模型经常选错。
• JSON 参数合法，但业务状态或权限不允许执行。
• 工具超时后无法确认是否已经产生副作用。
• 返回内容太大、包含敏感字段，或把不可信文本重新送入模型。
• Provider 切换后，tool call/result message 无法稳定适配。

Core Concepts

Tools are contracts between deterministic systems and non-deterministic agents. The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. Effective tool descriptions are prompt engineering that shapes agent behavior.

Key principles: clear descriptions (what/when/returns), response formats for token efficiency, error messages for recovery, and consistent conventions that reduce cognitive load.

Detailed Topics

The Tool-Agent Interface

Tools as Contracts Tools 是 contracts。人类调用 API 时理解契约，模型则需要从 description 推断契约，因此 description 必须明确、无歧义，并用例子传达正确用法。

Tool Description as Prompt Tool descriptions 本质是 prompt engineering，它决定 agent 如何选择与使用工具。差的描述会迫使模型猜测；好的描述包含 usage context、examples 和 defaults。

Namespacing and Organization 当 tool 集合变大时，namespacing 能降低选择成本。不同命名空间对应不同功能域，帮助 agent 快速定位。

合并与拆分的决策

什么时候合并 如果多个只读工具共享相同权限、数据源和返回结构，而且人类也难以根据任务明确区分，可以合并并用明确参数表达模式，减少 selection ambiguity。

什么时候必须拆分 读取、更新、删除具有不同权限和副作用时必须拆开。不要为了减少工具数量，把查询客户、修改资料和删除记录塞进同一个 manage_customer。

用 Evaluation 决定 对合并前后运行同一组 tool-selection、argument、permission 和 side-effect cases。没有实际错误率与可维护性证据时，不规定固定的工具数量。

Primitive Tools 与领域工具

Filesystem、shell 或 browser primitives 灵活，但权限面和误操作半径更大；只适合受控开发环境、明确 sandbox 和可审计任务。涉及生产数据、付款、身份或合规流程时，优先使用窄权限、强校验、可幂等的领域工具。

选择依据包括调用者权限、数据敏感度、副作用、可恢复性、审计要求和模型的选择准确率，而不是“通用工具一定更先进”。

Tool Description Engineering

Description Structure 一个好的 description 需要回答四个问题：

• What does the tool do?
• When should it be used?
• What inputs does it accept?
• What does it return?

Default Parameter Selection Defaults 应该覆盖常见场景，降低调用成本。

Response Format Optimization

返回格式直接影响 Context token。建议提供 concise 与 detailed 两种格式，并指明使用时机。

Error Message Design

Error messages 必须可行动：告诉模型“哪里错了、如何修”。

Tool Definition Schema

统一 schema（verb-noun naming、参数命名、返回字段）可以显著降低模型误用率。

Tool Collection Design

工具数量多会增加 selection ambiguity 与 Context 占用，但不存在适用于所有模型和任务的固定上限。使用 representative eval cases 测量选错、漏调、参数失败和延迟，再决定合并、拆分或按任务动态暴露。

Tool Identity 与 Namespacing

内部 registry 应保存稳定的 server/tool identity，避免两个 server 提供同名工具。展示给模型的命名格式取决于实际 client 和 SDK；不要把某一种 ServerName:tool_name 字符串写成所有 MCP client 的协议要求。

Using Agents to Optimize Tools

可以让 agent 反向优化工具描述：基于 failure examples 改进 descriptions，并形成反馈闭环。

Testing Tool Design

用代表性任务测试 tool calls，评估 unambiguity、completeness、recoverability 与 consistency。

Practical Guidance

Anti-Patterns to Avoid

• Vague descriptions
• Cryptic parameter names
• Missing error handling
• Inconsistent naming

Tool Selection Framework

1. Identify workflows
2. Group actions into comprehensive tools
3. Ensure clear purpose
4. Document error cases
5. Test with agent interactions

Minimal Tool Spec Template

Tool Name: <verb_noun>
When to use: <trigger + context>
Inputs:

-   param_a: type, constraints, example
-   param_b: type, default
    Returns:
-   format: concise | detailed
    Errors:
-   ERROR_CODE: recovery hint

Examples

Example 1: Well-Designed Tool

def get_customer(customer_id: str, format: str = "concise"):
    """
    Retrieve customer information by ID.

    Use when:
    - User asks about specific customer details
    - Need customer context for decision-making
    - Verifying customer identity

    Args:
        customer_id: Format "CUST-######" (e.g., "CUST-000001")
        format: "concise" for key fields, "detailed" for complete record

    Returns:
        Customer object with requested fields

    Errors:
        NOT_FOUND: Customer ID not found
        INVALID_FORMAT: ID must match CUST-###### pattern
    """

Example 2: Poor Tool Design

def search(query):
    """Search the database."""
    pass

Problems with this design:

1. Vague name: "search" is ambiguous
2. Missing parameters
3. No return description
4. No usage context
5. No error handling

Guidelines

1. Write descriptions that answer what/when/returns
2. Use consolidation to reduce ambiguity
3. Implement response formats
4. Design actionable error messages
5. Enforce naming conventions
6. Limit tool count and use namespacing
7. Test tool designs with real agent interactions
8. Iterate based on observed failures
9. Prefer minimal architectures when possible

Practice Task

• 用你的业务场景写一个 tool spec（按模板）
• 找到 2 个可能误用的点，并补充到 description 和 errors 中

Related Pages

• Claude Code Examples
• Context Engineering Fundamentals
• Multi-Agent Architecture Patterns
• Advanced Evaluation

Integration

This skill connects to:

• context-fundamentals
• multi-agent-patterns
• evaluation

References

External resources:

• MCP (Model Context Protocol) documentation
• Framework tool conventions
• API design best practices for agents
• Vercel d0 agent architecture case study

---

Skill Metadata

Created: 2025-12-20 Last Updated: 2025-12-23 Author: Agent Skills for Context Engineering Contributors Version: 1.1.0