agent-tool-design

# Tool Design Principles for AI Agents Practical guide to designing tool systems for LLM-powered agents, distilled from building a PAC1 benchmark agent (Rust, 16 tools reduced to 12, tested across 7 models, 40+ tasks) and studying Codex CLI and Claude Code architectures. See `references/` for code patterns, comparison tables, and a quick checklist. --- ## 1. Tool Count Sweet Spot Every tool in the schema is a token cost and a new failure mode. Models degrade on long tool lists. **Industry reference points:** | Agent | Core | Extended/Deferred | Total in Schema | |-------|------|--------------------|-----------------| | Claude Code | 7 | 33 (deferred via ToolSearch) | 7-40 | | Codex CLI | 7 | 0 | 7 | | mini-SWE-agent | 1 (bash) | 0 | 1 | | PAC1 agent | 14 | 8 deferred | 14 active + 8 deferred | | SGR Python | 3-6 + reasoning | 0 | Union schema (structured output) | See `references/comparison.md` for full architecture comparison. **Rules:** - Start with 7 core tools. Add only when you can measure round-trip savings. - Track tool usage rate per task. Remove tools with <5% usage across benchmark. - Every tool added must justify itself: "saves N round-trips per task" or "prevents failure mode X." - Test with your weakest target model first -- if it can't handle the tool count, the design is wrong. **Anti-pattern:** Adding a tool "just in case." We added `mkdir`, `move_file`, `find` -- usage was <3%. Disabled them. Zero regression. --- ## 2. Three-Tier Organization ##...