What We Learned After a Year of Building Claude Code: Thinking Like an Agent

Matching Tools to Model Capabilities

Thariq begins with a simple analogy: just as a person solving a hard math problem needs tools that match their skill level—paper, calculator, or a programmable computer—AI agents need tools that fit their own ability limits. Giving a powerful tool to a model that cannot invoke it is less useful than providing a well‑matched, simpler tool.

To discover a model’s boundaries, Thariq advises reading its output, running experiments, and continuously observing rather than assuming what the model can or cannot do.

AskUserQuestion Tool: Three Iterations

The most illustrative part of the post describes three failed redesigns before arriving at a successful AskUserQuestion tool.

First attempt: Add a parameter to ExitPlanTool so Claude asks a question while outputting a plan. This failed because the tool tried to serve two conflicting intents—producing a plan and asking a question—leaving Claude unsure how to proceed if the user’s answer invalidated the plan.

Second attempt: Embed a specially‑formatted question in Claude’s free‑form text output for the front‑end to parse. In practice the model’s creative output broke the format (extra sentences, missing options, different syntax), causing parsing failures.

Third attempt: Create an independent AskUserQuestion tool invoked during the plan‑mode phase. It blocks the agent loop until the user answers. Success came from a strict schema that forces Claude to present selectable options, the tool’s availability to the Agent SDK and Skills, and the model’s natural tendency to call it without forced prompts.

The key lesson is that a well‑designed tool is useless if the model does not know when to use it.

Tools Must Evolve with the Model

When Claude Code launched, it shipped a TodoWrite tool that listed tasks and let Claude tick them off. This was necessary because early models tended to drift on long tasks and needed a reminder.

As the underlying model grew stronger, the same tool became a constraint. The system’s automatic reminder every five turns made Claude think it could not modify the list, limiting its ability to spawn sub‑agents. Moreover, TodoWrite did not support multi‑agent collaboration.

Consequently the team replaced it with a Task tool that focuses on inter‑agent communication. Task supports dependencies, shared progress across sub‑agents, and allows the model to create, modify, or delete tasks, turning a reminder into a coordination mechanism.

Model upgrades can turn previously optimal tool designs into shackles; tool design must therefore be revisited continuously.

Progressive Disclosure: Adding Capability Without New Tools

Claude Code now offers about 20 tools. Adding another tool incurs decision‑making overhead and can hurt performance and stability. To balance capability and cost, the team uses “progressive disclosure.”

Example: a user asks Claude how to add an MCP, a piece of knowledge not present in the system prompt. Instead of stuffing the entire documentation into the prompt (which creates “context pollution”), the team gives Claude a link to fetch the document on demand. However, naïve fetching returns noisy search results.

The final solution is a dedicated “Claude Code Guide” sub‑agent that answers questions about Claude Code itself using a tuned search command that returns precise answers. This expands capability without adding a new tool.

The same principle applies to a Grep tool: rather than pre‑loading a vector store, Claude can issue a grep against the codebase, building the needed context only when required.

Design Is Both Art and Science

If you were hoping for a set of rigid rules on how to build your tools, unfortunately that is not this guide. Designing the tools for your models is as much an art as it is a science.

Thariq emphasizes that tool design depends on three variables: the specific model, the agent’s goal, and the execution environment. Changes in any of these variables shift the optimal solution, and rapid model evolution means today’s best design can become tomorrow’s constraint.

The reliable path is continuous experimentation, observation, and learning to “think like an agent”—inferring the model’s true ability boundaries from its actual outputs rather than assumptions.

Tools must match model ability —more or more generic is not better.

One tool, one semantic —mixed intents confuse the model.

Tool design must evolve with model capability —what constrains today may free tomorrow.

Progressive disclosure —extend ability without adding tools via “Context on Demand.”

Model must “like” the tool —low invocation rates render a tool ineffective.