Designing Tools for Agents (ACI)

No matter which pattern you build, tools will be part of it. And here's the insight most teams miss: tool definitions deserve as much prompt-engineering attention as your prompts. (source — Anthropic, Appendix 2)

Anthropic puts it bluntly: when building their SWE-bench agent, they spent more time optimizing the tools than the overall prompt.

Formats are not interchangeable

There are usually several ways to specify the same action — and to a software engineer they look equivalent:

• Specify a file edit as a diff, or by rewriting the whole file.
• Return structured output as code in markdown, or code in JSON.

These are cosmetically similar and losslessly convertible. But some formats are much harder for an LLM to write than others:

• A diff requires knowing how many lines are changing in the chunk header before writing the new code.
• Code inside JSON requires escaping every newline and quote.

Anthropic's three rules for tool formats:

1. Give the model enough tokens to "think" before it writes itself into a corner.
2. Keep the format close to what the model has seen naturally in internet text.
3. Avoid formatting overhead — don't make it count thousands of lines, or string-escape code.

The ACI principle

"Think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good agent-computer interfaces (ACI)."

Put yourself in the model's shoes:

• Is it obvious how to use this tool from the description and parameters, or would you have to think carefully? If you would, the model will too.
• A good tool definition includes example usage, edge cases, input format requirements, and clear boundaries from other tools.
• Write parameter names and descriptions like a great docstring for a junior developer.
• Test how the model uses your tools — run many example inputs, watch what mistakes it makes, iterate.

Poka-yoke your tools

Poka-yoke means designing things so they're hard to use wrong. Change the arguments so mistakes are difficult.

The canonical example from Anthropic's SWE-bench work: the model made mistakes with tools using relative filepaths, because after the agent moved out of the root directory the relative paths pointed at the wrong files. The fix was simple — change the tool to always require absolute filepaths.

# Hard to use wrong:
@mcp.tool()
def edit_file(absolute_path: str, new_content: str) -> str:
    """Rewrite the file at absolute_path with new_content.
    Example: edit_file('/repo/src/auth/login.ts', '...')
    Use absolute paths only — relative paths break after cd.
    """

# After this change, the model used the tool flawlessly.

Why this matters for everything that follows

Every pattern in this course — and every loop in the next one — eventually calls a tool. Workflows chain tool calls. Agents loop over tool calls. Loop engineering automates tool calls on a schedule. The quality of your tools is the ceiling on the quality of all of it.

Get ACI right early. It's the highest-leverage hour you'll spend.

---

You've finished Agent Fundamentals. You now know the augmented LLM, when to escalate to workflows or agents, four workflow patterns, and how to design tools that don't fight the model. Next: build your first autonomous loop in Agent Loop Foundations.