Tool design is continuous observation — see like an agent

“Experiment often, read your outputs, try new things. See like an agent.” — Thariq

Three lessons from building Claude Code’s tool system:

1. Dedicated tools beat bolted-on extensions. AskUserQuestion went through multiple failed iterations — adding questions to exit plans confused the model, markdown formatting wasn’t reliable. Only when they created a standalone tool with a structured modal did it work. The lesson: when the model struggles with a capability, the tool shape is wrong, not the model.

2. Tools that help weaker models constrain stronger ones. TodoWrite was essential for earlier Claude versions but became limiting as the model improved. They replaced it with a Task tool supporting dependencies and agent coordination. The tool itself was scaffolding that needed shedding as the model improved.

3. Progressive disclosure beats prompt stuffing. Instead of embedding all context in system prompts, Claude Code lets the agent build context itself through Grep, web search, skills files, and subagents. This is Skill graphs enable progressive disclosure for complex domains applied to tool design — let the agent navigate to what it needs rather than front-loading everything into the The context window is the fundamental constraint — everything else follows.

The meta-lesson: tool design is not a spec you write once. It’s a continuous loop of observing what the agent actually does, identifying where it struggles, and reshaping the tool to match how the model thinks. This extends Tools are a new kind of software — contracts between deterministic systems and non-deterministic agents — the contract evolves as the non-deterministic side improves. Boris Cherny’s broader principle takes this even further: Scaffolding is tech debt against the next model — the bitter lesson applied to product building — all non-model code has a shelf life, and the Claude Code team actively unships tools every couple weeks as the model makes them unnecessary. AutoAgent operationalizes “seeing like an agent” at a new level: Same-model meta-task pairings outperform cross-model — agents understand their own architecture better than humans or other models do shows that a meta-agent sharing weights with the task agent understands its failure modes better than any human observer could — because the empathy is intrinsic, not projected.