agent-tool-design

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

Agent Tool Design

The Agent Tool Contract — 5 principles for designing tools that agents call reliably.

The 5 Principles

Principle 1: Predictable Signature

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) { ... }

Principle 2: Rich Errors

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

Principle 3: Token-Efficient Output

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: