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

The quality of an AI agent depends not only on the power of its language model but also on how well its tools are designed. Machine Learning Mastery broke down what makes agent tools effective, and which mistakes turn a smart agent into a chaotic one.

Names and descriptions decide everything

The language model never sees a tool's source code. It sees only the name, the description, and the parameter schema, and it uses them to decide when to call the tool and with which arguments.

A weak tool looks like this: `get_data()` with the description "gets data." A strong one looks like this: `get_user_purchase_history(user_id)` with the description "returns a list of purchases from the last 90 days, sorted by date. Use it when you need to analyze spending or build personalization." The second version explains not only what the tool does but also when to call it, and for an agent those are fundamentally different levels of usefulness.

The name carries meaning. `process_file` is too broad. With `extract_invoice_line_items`, the model immediately understands the context and where the tool applies. A good formula: verb + object + qualifier.

"A tool's description is the 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 the "Swiss Army knife": a function with a dozen parameters that does five different things depending on which combination of flags you pass.

Signs of a poorly designed tool:

• A `mode` or `action` parameter that takes a set of string values
• More than 5–6 parameters in a single function
• The word "or" in the description: "finds a contact or creates a new one"
• Different return data types depending on the input arguments
• Optional parameters that radically change the tool's behavior

If a tool does several things, split it into separate tools. An agent has an easier time choosing between `search_contact` and `create_contact` than guessing the right flag combination for `manage_contact`. Once more than 20 tools sit in the context, models get noticeably worse at picking the right one, so keep the set compact.

Parameters and return values

Parameter types affect generation quality. A `string` with no description invites hallucinations. An `enum` with an explicit list of allowed values does not. For numeric parameters, specify the range and units: not `timeout`, but `timeout_seconds: integer, 1–30`.

Return values should be predictable and compact, because the agent adds the tool's entire output to its context. If a tool returns thousands of tokens of raw HTML, it becomes a bottleneck for the whole call chain.

Principles of a good return value:

• JSON with a fixed structure: models parse predictable formats better
• Errors as structured data, not uncaught exceptions
• Meta fields: `total_results`, `truncated: true`, `next_cursor`
• Only what the agent needs for the next step, nothing more
• On failure, a clear message with instructions on what to do next

What this means

Agent tools are not just wrappers around an API. They are the interface between a language model and the real world, and they deserve the same care as a public API: documentation, well-thought-out types, and tests in isolation. An agent won't fix a badly designed tool; it will keep calling it wrong, again and again.