Back to Details

agent-tool-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Tool Design

Agent工具设计

The Agent Tool Contract — 5 principles for designing tools that agents call reliably.
Agent工具契约——设计可被Agent可靠调用的工具的5条原则。

The 5 Principles

5条原则

Principle 1: Predictable Signature

原则1：可预测的签名

Tools must have typed, named parameters with clear required/optional distinction. No positional ambiguity.
Good:
javascript
// Clear, named, typed
function searchCode({ query, limit = 20, type = 'semantic' }) { ... }
Bad:
javascript
// Positional, ambiguous
function searchCode(q, n, t) { ... }
工具必须具备带类型的命名参数，明确区分必填/可选，不存在位置歧义。
正面示例：
javascript
// Clear, named, typed
function searchCode({ query, limit = 20, type = 'semantic' }) { ... }
反面示例：
javascript
// Positional, ambiguous
function searchCode(q, n, t) { ... }

Principle 2: Rich Errors

原则2：丰富的错误信息

Errors must include: error code (machine-readable), message (human-readable), context (debugging data).
Good:
javascript
throw {
  code: 'FILE_NOT_FOUND',
  message: `File not found: ${path}`,
  context: { path, cwd: process.cwd() },
};
Bad:
javascript
throw new Error('not found'); // No context for agent to act on
错误必须包含：错误码（机器可读）、消息（人类可读）、上下文（调试数据）。
正面示例：
javascript
throw {
  code: 'FILE_NOT_FOUND',
  message: `File not found: ${path}`,
  context: { path, cwd: process.cwd() },
};
反面示例：
javascript
throw new Error('not found'); // No context for agent to act on

Principle 3: Token-Efficient Output

原则3：Token高效的输出

Tools return structured minimal data. No prose explanations, no redundant wrapping, no verbose status messages. Agents format output themselves.
Good:
javascript
return { files: ['a.js', 'b.js'], total: 2 };
Bad:
javascript
return { status: 'success', message: 'Found 2 files successfully', data: { files: [...], metadata: {...} } };
Rule of thumb: If the output contains prose an agent would re-read to extract facts, it's too verbose.
工具返回结构化的最小数据，不要散文式解释、冗余封装、冗长的状态消息，Agent会自行格式化输出。
正面示例：
javascript
return { files: ['a.js', 'b.js'], total: 2 };
反面示例：
javascript
return { status: 'success', message: 'Found 2 files successfully', data: { files: [...], metadata: {...} } };
经验法则： 如果输出中包含Agent需要反复读取才能提取事实的散文式内容，说明输出过于冗长。

Principle 4: Idempotency

原则4：幂等性

Tools must be safe to retry. Running a tool twice should produce the same result as running it once.
Good:
javascript
// Upsert instead of insert
db.upsert({ id, ...data });
// mkdir -p instead of mkdir
fs.mkdirSync(path, { recursive: true });
Bad:
javascript
// Fails on retry
db.insert({ id, ...data }); // duplicate key error
fs.mkdirSync(path); // EEXIST error
工具必须可安全重试，运行两次产生的结果应该和运行一次完全一致。
正面示例：
javascript
// Upsert instead of insert
db.upsert({ id, ...data });
// mkdir -p instead of mkdir
fs.mkdirSync(path, { recursive: true });
反面示例：
javascript
// Fails on retry
db.insert({ id, ...data }); // duplicate key error
fs.mkdirSync(path); // EEXIST error

Principle 5: Graceful Degradation

原则5：优雅降级

Partial success > hard failure. Return what succeeded with a clear indication of what didn't.
Good:
javascript
return {
  succeeded: ['file1.js', 'file2.js'],
  failed: [{ file: 'file3.js', reason: 'PERMISSION_DENIED' }],
  partial: true,
};
Bad:
javascript
// One file fails -> entire batch throws
throw new Error('Failed to process file3.js');
部分成功优于完全失败，返回已成功执行的内容，同时清晰标记未成功的部分。
正面示例：
javascript
return {
  succeeded: ['file1.js', 'file2.js'],
  failed: [{ file: 'file3.js', reason: 'PERMISSION_DENIED' }],
  partial: true,
};
反面示例：
javascript
// One file fails -> entire batch throws
throw new Error('Failed to process file3.js');

Anti-Pattern Table

反模式表格

Anti-PatternProblemFix
Verbose status wrappingWastes tokens; agent re-parses to extract dataReturn data directly
Positional argsAmbiguous; breaks on refactorNamed params with types
Swallowed exceptionsAgent thinks success; work is lostAlways surface errors explicitly
Non-idempotent mutationsRetry causes duplicate data or errorsUpsert semantics; check-then-set
Hard failures on partial inputOne bad item breaks entire batchReturn partial results
Side-effect-heavy readsRead tools that trigger writes confuse agentsSeparate reads from writes
String error messages onlyAgent can't programmatically handle errorsInclude machine-readable error codes
Untyped return shapeAgent can't reliably destructure outputDocument and enforce return schema
反模式问题修复方案
冗长的状态封装浪费Token；Agent需要重新解析才能提取数据直接返回数据
位置参数歧义性高；重构时容易失效使用带类型的命名参数
吞掉异常Agent会误以为操作成功，工作成果丢失始终显式抛出错误
非幂等的变更操作重试会导致重复数据或错误使用Upsert语义；先检查再设置
部分输入错误直接完全失败一个错误项导致整个批次处理失败返回部分结果
带副作用的读操作会触发写入的读工具会让Agent产生混淆读写逻辑分离
仅返回字符串错误消息Agent无法通过程序逻辑处理错误包含机器可读的错误码
无类型的返回结构Agent无法可靠地解构输出文档化并强制要求返回schema

Review Checklist

审核检查清单

Before shipping any tool:
[ ] Parameters are named (not positional)
[ ] Required vs optional params are explicit
[ ] All error paths return { code, message, context }
[ ] Output contains no prose — only structured data
[ ] Tool is idempotent (safe to retry)
[ ] Partial failure returns partial results, not throws
[ ] Return shape is documented in JSDoc or TypeScript types
[ ] Token budget for output estimated (< 500 tokens for standard tools)
发布任何工具前，请确认：
[ ] 参数为命名形式（非位置参数）
[ ] 明确区分必填和可选参数
[ ] 所有错误路径都返回 { code, message, context }
[ ] 输出仅包含结构化数据，无散文式内容
[ ] 工具具备幂等性（可安全重试）
[ ] 部分失败时返回部分结果，而非抛出异常
[ ] 返回结构已在JSDoc或TypeScript类型中说明
[ ] 预估输出的Token预算（标准工具输出低于500 Token）

Iron Laws

铁律

  1. ALWAYS use named parameters — never positional arguments in tool signatures; positional args break on refactor and create ambiguity for agents.
  2. ALWAYS include machine-readable error codes — never surface plain string errors only; agents need 
    { code, message, context }
    to handle errors programmatically.
  3. NEVER mix reads and writes in the same tool — read tools that trigger side effects confuse agents and prevent safe retries.
  4. ALWAYS design for idempotency — retry must produce the same result as the first call; use upsert semantics and 
    mkdir -p
    patterns.
  5. ALWAYS return partial results on partial failure — never let one failing item abort the entire batch; return 
    { succeeded, failed, partial: true }
    .
  1. 始终使用命名参数 —— 工具签名中绝对不要使用位置参数；位置参数在重构时会失效，还会给Agent带来歧义。
  2. 始终包含机器可读的错误码 —— 绝对不要仅返回纯字符串错误；Agent需要 
    { code, message, context }
    结构才能通过程序逻辑处理错误。
  3. 绝对不要在同一个工具中混合读写逻辑 —— 会触发副作用的读工具会让Agent产生混淆，还会导致无法安全重试。
  4. 始终按照幂等性设计 —— 重试产生的结果必须和首次调用完全一致；使用Upsert语义和 
    mkdir -p
    这类模式。
  5. 部分失败时始终返回部分结果 —— 绝对不要让一个失败项终止整个批次的处理；返回 
    { succeeded, failed, partial: true }
    结构。

Integration

集成

  • Used by: 
    tool-creator
    skill when designing new tools
  • Reviewed by: 
    code-reviewer
    agent during tool PRs
  • Pairs with: 
    dynamic-api-integration
    skill (consuming external tools)
  • Complements: 
    agent-evaluation
    skill (evaluating tool output quality)
  • 使用者：设计新工具时的 
    tool-creator
    skill
  • 审核者：工具PR审核阶段的 
    code-reviewer
    agent
  • 搭配使用：
    dynamic-api-integration
    skill（消费外部工具）
  • 互补：
    agent-evaluation
    skill（评估工具输出质量）

Memory Protocol (MANDATORY)

内存协议（强制要求）

Before starting: Read 
.claude/context/memory/learnings.md
After completing:
  • New pattern -> 
    .claude/context/memory/learnings.md
  • Issue found -> 
    .claude/context/memory/issues.md
  • Decision made -> 
    .claude/context/memory/decisions.md
ASSUME INTERRUPTION: If it's not in memory, it didn't happen.
开始前： 阅读 
.claude/context/memory/learnings.md
完成后：
  • 新模式 -> 写入 
    .claude/context/memory/learnings.md
  • 发现问题 -> 写入 
    .claude/context/memory/issues.md
  • 做出决策 -> 写入 
    .claude/context/memory/decisions.md
假设会发生中断：如果内容没有记录在内存中，就等于没有发生过。