Seeing like an agent: how we design tools in Claude Code

2026-04-10 · Source: Claude Blog · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering, Robotics & Autonomous Systems · Depth: Intermediate, medium

Summary

The Claude Code team details its iterative approach to designing, testing, and evolving tools for AI agents, emphasizing the importance of "seeing like an agent." The article highlights three key development areas: improving user elicitation, updating tools with evolving model capabilities, and designing effective search interfaces. For elicitation, the team moved from modifying existing tools and output formats to creating a dedicated AskUserQuestion tool, which improved structured output and user interaction. Regarding model capabilities, the initial TodoWrite tool was replaced by the more flexible Task tool as models like Opus 4.5 improved, allowing for better coordination among subagents. Finally, the team transitioned from RAG-based context provision to a Grep tool and Agent Skills for self-directed context building, culminating in the Claude Code Guide subagent for efficient documentation search via progressive disclosure.

Key takeaway

For AI Engineers building agent harnesses, your tool design must evolve with model capabilities. Avoid static toolsets; instead, continuously experiment and observe agent outputs to determine when to add, remove, or refine tools. Consider implementing dedicated tools for structured interactions and leveraging progressive disclosure via subagents to manage complexity and keep the main agent's context clean, ensuring your agents remain effective and adaptable.

Key insights

Effective agent tool design requires understanding the model's perspective and adapting tools as its capabilities evolve.

Principles

• Tools must align with agent abilities.
• Iterate and experiment frequently.
• Prioritize progressive disclosure.

Method

Design tools by considering the agent's skill set, observing its outputs, and iteratively refining or replacing tools based on performance and evolving model capabilities, often using progressive disclosure.

In practice

• Implement a dedicated AskUserQuestion tool for structured elicitation.
• Replace limiting todo lists with flexible task management for advanced agents.
• Utilize subagents for specialized context retrieval like documentation search.

Topics

• Agent Tool Design
• Claude Code
• Elicitation Tools
• Progressive Disclosure
• Task Management

Best for: AI Engineer, Machine Learning Engineer, AI Architect

Related on AIssential

• Harnessing Claude’s intelligence — Building with evolving AI requires adapting agent harnesses to leverage new model capabilities and optimize performance.
• Applying an Agentic Coding Tool for Improving Published Algorithm Implementations — Agentic coding tools can significantly improve published algorithm implementations across diverse domains within a single workday.
• Claude Code and What Comes Next — New AI coding tools combine enhanced autonomy with agentic harnesses to perform complex, sustained tasks.
• v2.1.56 — Claude Code updates focus on performance, security, and extensibility, enhancing developer workflows and multi-agent capabilities.
• Lessons from building Claude Code: How we use skills — Skills are structured folders of instructions, scripts, and resources that enhance agent accuracy and efficiency.
• Claude Agent SDK: The Beginner-Friendly Roadmap to Building Production-Ready AI Agents — AI agents represent a paradigm shift from simple chat to autonomous systems capable of planning, tool use, and task execution.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Claude Blog.