메뉴
The Agent Tool Contract — 5 principles for designing tools agents call reliably: predictable signature, rich errors, token-efficient output, idempotency, graceful degradation. Includes anti-pattern table with 8 common mistakes.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/oimiragieo/agent-studio --skill agent-tool-design명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Agent frontmatter enhancements — disallowedTools, mcpServers scoping, fork_eligible field
Context management — pre-compact persistence, threshold alignment, microcompact/circuit breaker detection
Hook enhancements — updatedInput for bash safety prefixes, suppressOutput for verbose blocks, denial-based routing feedback
SKILL.md 표시 중
SOC 직업 분류 기준
| name | agent-tool-design |
| description | The Agent Tool Contract — 5 principles for designing tools agents call reliably: predictable signature, rich errors, token-efficient output, idempotency, graceful degradation. Includes anti-pattern table with 8 common mistakes. |
| version | 1.2.0 |
| category | Development |
| agents | ["developer","architect","tool-creator"] |
| user_invocable | true |
| invoked_by | both |
| tools | ["Read","Write","Bash"] |
| verified | true |
| lastVerifiedAt | "2026-03-01T00:00:00.000Z" |
| tags | ["tools","design","api","contract","idempotency","errors","agent-tools"] |
| best_practices | ["Parameters are named not positional","Errors include machine-readable code plus human message plus context","Output is structured data only — no prose","Tools are idempotent (safe to retry)","Partial failure returns partial results rather than throws"] |
| error_handling | graceful |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 4e11dcf3976f7b80 |
The Agent Tool Contract — 5 principles for designing tools that agents call reliably.
Tools must have typed, named parameters with clear required/optional distinction. No positional ambiguity.
Good:
// Clear, named, typed
function searchCode({ query, limit = 20, type = 'semantic' }) { ... }
Bad:
// Positional, ambiguous
function searchCode(q, n, t) { ... }
Errors must include: error code (machine-readable), message (human-readable), context (debugging data).
Good:
throw {
code: 'FILE_NOT_FOUND',
message: `File not found: ${path}`,
context: { path, cwd: process.cwd() },
};
Bad:
throw new Error('not found'); // No context for agent to act on
Tools return structured minimal data. No prose explanations, no redundant wrapping, no verbose status messages. Agents format output themselves.
Good:
return { files: ['a.js', 'b.js'], total: 2 };
Bad:
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.
Tools must be safe to retry. Running a tool twice should produce the same result as running it once.
Good:
// Upsert instead of insert
db.upsert({ id, ...data });
// mkdir -p instead of mkdir
fs.mkdirSync(path, { recursive: true });
Bad:
// Fails on retry
db.insert({ id, ...data }); // duplicate key error
fs.mkdirSync(path); // EEXIST error
Partial success > hard failure. Return what succeeded with a clear indication of what didn't.
Good:
return {
succeeded: ['file1.js', 'file2.js'],
failed: [{ file: 'file3.js', reason: 'PERMISSION_DENIED' }],
partial: true,
};
Bad:
// One file fails -> entire batch throws
throw new Error('Failed to process file3.js');
| Anti-Pattern | Problem | Fix |
|---|---|---|
| Verbose status wrapping | Wastes tokens; agent re-parses to extract data | Return data directly |
| Positional args | Ambiguous; breaks on refactor | Named params with types |
| Swallowed exceptions | Agent thinks success; work is lost | Always surface errors explicitly |
| Non-idempotent mutations | Retry causes duplicate data or errors | Upsert semantics; check-then-set |
| Hard failures on partial input | One bad item breaks entire batch | Return partial results |
| Side-effect-heavy reads | Read tools that trigger writes confuse agents | Separate reads from writes |
| String error messages only | Agent can't programmatically handle errors | Include machine-readable error codes |
| Untyped return shape | Agent can't reliably destructure output | Document and enforce return schema |
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 } to handle errors programmatically.mkdir -p patterns.{ succeeded, failed, partial: true }.tool-creator skill when designing new toolscode-reviewer agent during tool PRsdynamic-api-integration skill (consuming external tools)agent-evaluation skill (evaluating tool output quality)Before starting:
Read .claude/context/memory/learnings.md
After completing:
.claude/context/memory/learnings.md.claude/context/memory/issues.md.claude/context/memory/decisions.mdASSUME INTERRUPTION: If it's not in memory, it didn't happen.