Toolbox icon with mismatched labeled tools causing confusion

The Tool-Design Mistakes That Make AI Agents Unreliable

A lot of "the model is unreliable" complaints are actually tool-design problems. The model is doing exactly what an ambiguous or overloaded tool definition told it to do.

🧰 One Tool Doing Too Many Things

A single tool with a dozen optional parameters covering unrelated use cases forces the model to guess which combination applies. Splitting it into several narrow, clearly-named tools removes the guesswork entirely.

📝 Descriptions That Don't Say When to Use It

A tool description that only explains what a tool does, not when to use it versus a similar tool, leaves the model to infer the boundary — and it infers wrong often enough to matter at scale.

🔇 Tools That Fail Without Saying Why

A tool that returns an empty result on failure instead of a clear error message gets treated by the model as a valid empty result, not a problem to recover from. Explicit, distinguishable error responses are what let an agent actually self-correct.