Writing effective tools for AI agents—using AI agents

Source: Anthropic Engineering Date: 2025-09-11 URL: https://www.anthropic.com/engineering/writing-tools-for-agents

Summary

Anthropic describes using Claude itself to iteratively optimize tool definitions against evaluation sets, with tools outperforming human-written baselines in Slack and Asana internal evals. Key design decisions: fewer high-impact tools over granular API wrappers, consistent namespacing (e.g., asana_projects_search), and a ResponseFormat enum that let tools return "concise" or "detailed" responses — reducing token consumption by roughly two-thirds in the Slack example. Claude Code caps tool responses at 25,000 tokens by default.

Implications

The ACI design thread. This post operationalizes the “ACI over prompting” principle from building-effective-agents: namespacing, response format control, and semantic return values are the concrete implementation moves. The ResponseFormat enum is a particularly portable pattern — any MCP tool serving a Claude Code harness should consider agent-requested verbosity control.

Claude-optimized tools outperform human-written ones. Using Claude to write and iterate tool descriptions against evals is now a published Anthropic workflow, not just a community hack. This is an argument for AI-in-the-loop tool development pipelines.

Claude Code’s 25k token response cap. The explicit mention of Claude Code’s 25,000-token tool response limit is practical operator information — tool authors targeting Claude Code need to design pagination and truncation to stay under this ceiling, or responses will be cut off without warning.