Design effective tool interfaces with clear descriptions and boundaries

Keep descriptions short — the tool name already says what it does.

The description is the primary evidence the model selects on. With two plausible candidates and nothing to separate them, selection becomes a coin flip that looks fine in testing and drifts in production.

Write the description for a reader deciding between this tool and the one next to it.

Fix a misrouting problem by telling the model in the system prompt which tool to prefer.

It patches the symptom for one phrasing and leaves the ambiguity in place, so the next similar request misroutes again — and keyword-sensitive prompt wording can create new unintended associations of its own.

Remove the overlap at the source: rename, re-scope the description, or split the tool.

Ship one flexible tool that handles the whole job, so there is less for the model to choose between.

A general tool has no contract worth stating, so its description cannot say what it returns, and the model cannot tell when it is the right call.

Purpose-specific tools with defined contracts are easier to select correctly than one tool with a vague one.

Assume good descriptions settle selection on their own.

A keyword in the system prompt can bind a concept to the wrong tool and silently outrank the description in every request that uses that word.

Review the system prompt as part of the tool interface, not separately from it.

Describe what the tool does and stop there.

Without input formats, example queries and boundaries, the model guesses argument shapes and calls the tool outside the range it actually handles.

State inputs, outputs, edge cases and the boundary — where this tool stops being the right one.