7 Principles for AI Agent Tool Design (From Claude Code + Real-World Systems)

The Claude Code engineering team recently shared their year-long journey building tool interfaces for AI agents. As someone who builds and runs multi-agent systems daily, I found deep resonance—and a few disagreements. Here's a systematic breakdown. Principle 1: Match Tools to Your Model's Actual Capabilities This is the most overlooked rule. Many teams design one set of tool interfaces and apply them to every model—that's wrong. The Claude Code team learned this the hard way: after upgrading to Claude Opus, a "todo reminder tool" that originally helped the model stay focused became a constraint. The model started rigidly following the list instead of thinking flexibly. Actionable rule: Every time you upgrade your model version, immediately re-audit all existing tools. Last version's scaffolding may be this version's shackle. Principle 2: Use Tools for Structured Output, Not Prompts Asking a model to "output in a specific format" is the least reliable approach. Models add extra sentenc