Back to Details

tool-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tool Design for Agents

Agent工具设计

Tools define the contract between deterministic systems and non-deterministic agents. Poor tool design creates failure modes that no amount of prompt engineering can fix.
工具定义了确定性系统与非确定性Agent之间的契约。糟糕的工具设计会引发故障模式，无论做多少提示词工程都无法修复。

The Consolidation Principle

整合原则

If a human engineer cannot definitively say which tool should be used, an agent cannot do better.
Instead of: 
list_users
, 
list_events
, 
create_event
Use: 
schedule_event
(finds availability and schedules)
如果人类工程师都无法明确判断应该使用哪个工具，Agent也做不到更好。
反例：
list_users
, 
list_events
, 
create_event
推荐：
schedule_event
（查找可用时间并完成日程安排）

Tool Description Structure

工具描述结构

Answer four questions:
  1. What does the tool do?
  2. When should it be used?
  3. What inputs does it accept?
  4. What does it return?
回答四个问题：
  1. 功能：该工具能做什么？
  2. 场景：何时应该使用该工具？
  3. 输入：该工具接受哪些输入？
  4. 输出：该工具会返回什么？

Well-Designed Tool Example

优秀工具设计示例

python
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
    """
python
def get_customer(customer_id: str, format: str = "concise"):
    """
    根据ID获取客户信息。

    使用场景：
    - 用户询问特定客户的详细信息
    - 决策时需要客户上下文信息
    - 验证客户身份

    参数：
        customer_id：格式为"CUST-######"（例如："CUST-000001"）
        format："concise"表示仅返回关键字段，"detailed"表示返回完整记录

    返回：
        包含请求字段的客户对象

    错误：
        NOT_FOUND：未找到客户ID
        INVALID_FORMAT：ID格式不符合CUST-######规范
    """

Poor Tool Design (Anti-pattern)

糟糕的工具设计（反模式）

python
def search(query):
    """Search the database."""
    pass
Problems: Vague name, missing parameters, no return description, no usage context, no error handling.
python
def search(query):
    """搜索数据库。"""
    pass
问题：名称模糊、缺少参数说明、无返回描述、无使用上下文、无错误处理。

Architectural Reduction

架构简化

Production evidence shows: fewer, primitive tools can outperform sophisticated multi-tool architectures.
File System Agent Pattern: Provide direct file system access instead of custom tools. Agent uses grep, cat, find to explore. Works because file systems are well-understood abstractions.
When reduction works:
  • Data layer well-documented
  • Model has sufficient reasoning
  • Specialized tools were constraining
  • Spending more time maintaining scaffolding than improving
生产实践表明：数量更少、更基础的工具，性能可能优于复杂的多工具架构。
文件系统Agent模式：提供直接的文件系统访问权限，而非自定义工具。Agent使用grep、cat、find等命令进行探索。这种模式之所以有效，是因为文件系统是广为人知的抽象概念。
架构简化适用场景：
  • 数据层文档完善
  • 模型具备足够的推理能力
  • 专用工具存在局限性
  • 维护脚手架的时间多于优化模型的时间

MCP Tool Naming

MCP工具命名规则

Always use fully qualified names:
python
undefined
始终使用完全限定名称：
python
undefined

Correct

正确

"Use the BigQuery:bigquery_schema tool..."
"Use the BigQuery:bigquery_schema tool..."

Incorrect (may fail)

错误（可能失效）

"Use the bigquery_schema tool..."
undefined
"Use the bigquery_schema tool..."
undefined

Response Format Optimization

响应格式优化

python
format: str = "concise"  # "concise" | "detailed"
Let agents control verbosity. Concise for confirmations, detailed when full context needed.
python
format: str = "concise"  # "concise" | "detailed"
让Agent控制输出详细程度。确认场景使用简洁格式，需要完整上下文时使用详细格式。

Error Message Design

错误消息设计

Design for agent recovery:
python
{
    "error": "NOT_FOUND",
    "message": "Customer CUST-000001 not found",
    "suggestion": "Verify customer ID format (CUST-######)"
}
为Agent的故障恢复设计错误消息：
python
{
    "error": "NOT_FOUND",
    "message": "Customer CUST-000001 not found",
    "suggestion": "Verify customer ID format (CUST-######)"
}

Tool Collection Guidelines

工具集合指南

  • 10-20 tools for most applications
  • Use namespacing for larger collections
  • Ensure each tool has unambiguous purpose
  • Test with actual agent interactions
  • 大多数应用程序配备10-20个工具即可
  • 工具数量较多时使用命名空间
  • 确保每个工具的用途明确无歧义
  • 结合实际Agent交互进行测试

Anti-Patterns

反模式

  • Vague descriptions: "Search the database"
  • Cryptic parameters: 
    x
    , 
    val
    , 
    param1
  • Missing error handling: Generic errors
  • Inconsistent naming: 
    id
    vs 
    identifier
    vs 
    customer_id
  • 模糊描述：例如“搜索数据库”
  • 晦涩参数：如
    x
    、
    val
    、
    param1
  • 缺少错误处理：仅返回通用错误信息
  • 命名不一致：如
    id
    、
    identifier
    、
    customer_id
    混用

Best Practices

最佳实践

  1. Write descriptions answering what, when, returns
  2. Use consolidation to reduce ambiguity
  3. Implement response format options
  4. Design error messages for recovery
  5. Establish consistent naming conventions
  6. Test with actual agent interactions
  7. Question if tools enable or constrain reasoning
  8. Build minimal architectures for model improvements
  1. 编写描述时需涵盖功能、使用场景、返回结果
  2. 通过整合工具减少歧义
  3. 实现响应格式选项
  4. 为故障恢复设计错误消息
  5. 建立统一的命名规范
  6. 结合实际Agent交互进行测试
  7. 思考工具是增强还是限制了推理能力
  8. 构建极简架构以适配模型优化