How to Design Tools for AI Agents: Working Practices and Common Mistakes

The quality of an AI agent is determined not only by the power of the language model, but also by how well its tools are designed. Machine Learning Mastery analyzed what exactly makes agent tools effective — and what mistakes turn a smart agent into a chaotic one.

Name and description decide everything

The language model doesn't see the tool's source code. It only sees its name, description, and parameter schema — and based on these, it decides when and with what arguments to call it. Example of a weak tool: `get_data()` with description "gets data". Example of a strong tool: `get_user_purchase_history(user_id)` — "returns a list of purchases over the last 90 days, sorted by date. Use when you need to analyze spending or build personalization". The second option explains not just what the tool does, but when to call it — these are fundamentally different levels of usefulness for the agent.

A name carries semantics: `process_file` — too broad. `extract_invoice_line_items` — the model immediately understands the context and applicability. Good formula: verb + object + clarification.

"Tool description is a prompt for the tool itself.

If it's vague, the agent will hallucinate arguments or call the wrong tool."

One tool — one responsibility

The most common mistake is a "Swiss Army knife": a function with a dozen parameters that does five different things depending on a combination of flags. Signs of a poorly designed tool:

• Parameter `mode` or `action` with a set of string values
• More than 5–6 parameters in a single function
• Description contains "or" — "searches for contact or creates a new one"
• Returns different data types depending on input arguments
• Optional parameters that drastically change behavior

If a tool does several things — split it into separate ones. An agent will more easily choose between `search_contact` and `create_contact` than guess the right combination of flags in `manage_contact`. With more than 20 tools in context, the accuracy of models in choosing the right one noticeably drops — keep the set compact.

Parameters and return values

Parameter type affects generation quality. `string` without description — a source of hallucinations. `enum` with an explicit list of allowed values — no. For numeric parameters, specify the range and units of measurement: not `timeout`, but `timeout_seconds: integer, 1–30`. The return value should be predictable and compact: the agent adds the entire tool output to the context. If a tool returns thousands of tokens of raw HTML — this is a bottleneck for the entire call chain. Principles of a good return value:

• JSON with fixed structure — the model better parses predictable formats
• Errors — structured data, not uncaught exceptions
• Meta-fields: `total_results`, `truncated: true`, `next_cursor`
• Only what the agent needs for the next step — no more
• On error — a clear message with instructions for further action

What does this mean

Tools for agents are not just wrappers around APIs. This is an interface between the language model and the real world, requiring the same attention as a public API: documentation, thoughtful types, tests in isolation. An agent won't fix a poorly designed tool — it will call it incorrectly again and again.