Tool Design for Agents

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

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

• Tools 是 contracts，不是普通 API。
• Consolidation 能减少歧义。
• 好的 description 要回答 what/when/inputs/returns。
• Error messages 必须可恢复。
• 优先考虑 minimal, general-purpose tools。

你将学到什么

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

When to Activate

Activate this skill when:

• Creating new tools for agent systems
• Debugging tool-related failures or misuse
• Optimizing existing tool sets for better agent performance
• Designing tool APIs from scratch
• Evaluating third-party tools for agent integration
• Standardizing tool conventions across a codebase

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 快速定位。

The Consolidation Principle

Single Comprehensive Tools Consolidation 原则：如果人类都无法决定使用哪个 tool，模型不可能做得更好。优先提供一个能完成完整 workflow 的工具，而不是多个碎片化工具。

Why Consolidation Works 工具越多，description 越占 Context，歧义越高。Consolidation 能减少 token 消耗并降低选择复杂度。

When Not to Consolidate 如果行为差异大、使用场景不同、工具可独立调用，则不应强行合并。

Architectural Reduction

Consolidation 进一步推向极致，会得到 architectural reduction：减少专用工具，转向通用 primitive tools。

The File System Agent Pattern 与其构建复杂工具，不如提供 filesystem access + command execution，让模型使用 grep/cat/find/ls 等通用工具。

When Reduction Outperforms Complexity Reduction 在以下条件下更有效：

• Data layer 文档清晰
• 模型推理能力足够
• 现有 tools 在限制而非增强模型

Reduction 会失败于：数据混乱、领域知识不足、安全约束强、流程高度复杂。

Stop Constraining Reasoning 很多 guardrails 本意是“保护模型”，结果却限制了模型的推理空间。需要不断问：工具是在增强，还是在束缚？

Build for Future Models 模型迭代速度快于工具，过度复杂的工具架构会锁死未来改进空间。更小的 architecture 往往更有韧性。

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

工具数量多并不一定更好。建议控制在 10-20 个，并用 namespacing 做分组。

MCP Tool Naming Requirements

使用 MCP tools 时必须使用 fully qualified tool names：

Format: ServerName:tool_name

# Correct
"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
"Use the GitHub:create_issue tool to create issues."

# Incorrect
"Use the bigquery_schema tool..."

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

Internal references:

• Best Practices Reference
• Architectural Reduction Case Study

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