Designing Tools for LLM Agents

A tool definition has four parts the model depends on: a name, a natural-language description, an input schema (usually JSON Schema), and the text the tool sends back. Each works like a prompt. The model decides whether to call a tool by matching the user's goal to descriptions, and it fills in arguments using parameter names, types, enums and examples. Good names are specific and grouped. Prefixes such as github_create_issue and jira_create_issue keep tools apart when an agent connects to many services. Good descriptions say what the tool does, when to use it, when not to, and what it returns, the way you would brief a new colleague. Parameters should say what they mean: user_id is better than id, and an enum of allowed values beats a free-text string the model has to guess at. Outputs matter as much as inputs. Returning thousands of rows or raw internal IDs fills the context window and hides the information that matters. Better tools return readable fields, paginate or truncate by default, and sometimes offer a concise or detailed mode. Error messages should tell the model what went wrong and what to try next, because the model will read them and act on them. One common misconception is that more tools means a more capable agent. Every definition takes up context on every turn, and overlapping tools make selection harder. Accuracy tends to drop as the tool list grows long, especially when tools look alike. No universal cutoff applies. Many practitioners start to see trouble somewhere in the tens of tools, and the usual fixes are consolidating tools, loading them on demand, or splitting work across specialized agents. Another misconception is that tools should mirror an existing API one-to-one. Agents usually do better with fewer, higher-level tools shaped around the tasks people actually do.