Seeing Like an Agent: How We Design Tools in Claude Code

The world of AI agents is rapidly evolving, and at the heart of their intelligence lies their ability to use tools effectively. A recent insightful article, "Seeing like an agent: how we design tools in Claude Code," delves into the meticulous process the Claude Code team undertakes to design, test, and refine AI agent tools. The core philosophy? To think from the AI model's perspective, ensuring tools are intuitive and powerful for the agent itself. This approach is critical for advancing agent capabilities within the Claude Code product.

What It Does: Empowering Agents Through Tool Calling

At its fundamental level, Claude operates entirely through a sophisticated system of tool calling. This means that instead of direct commands, Claude interacts with its environment and performs tasks by invoking specific tools. These tools are highly flexible and can be constructed within the Claude API using powerful primitives. Developers can leverage tools like bash for command-line operations or the code execution tool for running complex code snippets. You can explore more about this programmatic approach to agents and tools in the Claude API Tool Use Overview, and delve into specifics with the Claude API Bash Tool and the Claude API Code Execution Tool.

Why It Matters: Enhancing User-AI Communication

One of the significant challenges in AI interaction is effective elicitation—the AI's ability to ask precise and helpful questions to clarify user intent or gather necessary information. The Claude Code team developed the AskUserQuestion tool specifically to address this. While Claude could always ask questions in plain text, this new dedicated tool was designed to reduce communication friction and significantly increase the bandwidth of interaction between the user and Claude, making the overall experience smoother and more efficient.

The Journey to Better Elicitation

The path to the AskUserQuestion tool wasn't straightforward. Initial attempts to improve Claude's elicitation capabilities faced hurdles. One early approach involved adding a question array directly to the ExitPlanTool. However, this confused Claude by mixing the agent's plan with a set of questions about it, leading to ambiguities. Another attempt focused on modifying Claude’s output instructions to use a special markdown format for questions. While sometimes successful, Claude couldn't reliably produce this structured output, often adding extraneous text or abandoning the format entirely. These iterations highlighted the importance of designing tools that genuinely align with how the AI "thinks" and processes information, ultimately leading to the more robust and reliable AskUserQuestion tool.

Read more: Seeing like an agent: how we design tools in Claude Code and discover how you can leverage these advanced agent capabilities in your own projects.