Poka-Yoke Tool Design

Definition

Designing the agent-computer interface (ACI) so that mistakes are hard to make — shaping tool contracts, names, and parameters to guide the agent toward correct use rather than relying on it to avoid errors.

Key points

• Tools are a distinct contract between deterministic systems and non-deterministic agents; the goal is tools agents can use effectively, not just tools that expose functionality.
• Describe the tool as you would to a new hire on your team — make explicit the context you'd implicitly bring: query formats, niche terminology, relationships between resources.
• Avoid ambiguity: clearly describe (and enforce with strict data models) expected inputs/outputs. Use unambiguous parameter names — user_id instead of user.
• Prefer consolidated tools that solve tasks "in much the same way that a human would," so the agent has fewer chances to mis-sequence primitive calls.
• Actionable error messages steer the agent back on track — suggest the next tool call (e.g. Try searching for specific thread with search_threads(query='keyword')) rather than dumping a stack trace.
• Empirically: precise refinements that reduce error rates yield dramatic gains — Claude Sonnet 3.5 reached state-of-the-art on SWE-bench after tool-description refinements.

Why it matters for the exam

• Captures the "make mistakes hard, guide the agent" ACI principle from the Building Effective Agents appendix.
• Points to unambiguous parameter names and strict data models as the fix for invalid-input errors.

Common gotchas

• Ambiguous names like user (vs user_id) invite invalid-parameter errors.
• Relying on the agent to remember correct call ordering instead of consolidating the workflow into one tool.

See also

• Effective Tool Descriptions
• Tool Definition Schema
• Structured Tool Errors

Sources

• blog-writing-tools