What makes a tool definition good or bad for an agent?

Answer

The tool definition is a prompt. The model chooses based on the name, the description, and the parameter schema, and nothing else.

Name it for the action. search_issues beats issue_handler. The model matches intent to name.

The description must say when to use it, not only what it does. "Searches GitHub issues. Use when the user asks about existing bugs, feature requests, or issue status." The trigger conditions are what drive correct selection.

Keep parameters few and typed. Every optional parameter is a chance to guess wrong. Use enums rather than free strings where the set is known. Mark required fields accurately.

Return errors the model can act on. "Error: repository foo/bar not found. Check the owner and name." lets it recover. "Error: request failed" does not.

Keep results small. Tool output enters the context window. A tool returning an entire file or a full log consumes budget for every subsequent turn. Paginate, truncate, or summarise, and say that you did.

Make destructive tools obvious. If a tool deletes something, the name and description should say so, so the model treats it with more care and so permission systems can key on it.

On count: every tool definition occupies context on every request. Twenty well chosen tools generally beat sixty, because selection accuracy falls as the list grows.

Common wrong answer

Writing tool descriptions for human developers rather than for the model. Documentation style prose describing implementation detail does not help the model choose. It needs the decision criteria.

Also common is exposing an entire API surface one to one. An MCP server wrapping fifty REST endpoints as fifty tools produces worse agent behaviour than five task shaped tools.