Best Practices for Building AI Agents

Chapter 2 · Practice 3 of 4

Change arguments so mistakes are hard to make

From Designing tools an agent can use well

Why it matters

Anthropic's agents article borrows poka-yoke, mistake-proofing, from manufacturing: change the arguments so it is harder to make mistakes.

Its example comes from a coding agent on SWE-bench. The model made errors with relative file paths after moving out of the root directory. The team changed the tool to always require absolute paths, and the model then used it without error.

Look for the same pattern in your tools:

  • require ids instead of free-text names that can be ambiguous;
  • use enums instead of open strings for categories;
  • accept one unit of time or currency, stated in the schema;
  • reject calls that are missing context the tool needs, with a clear error.

Then test the tool with many varied inputs and watch for repeated mistakes; each one points to an argument worth redesigning.