Tool Design for LLM Agents: Names, Inputs and Errors

The most common mistake is to expose an existing API one endpoint at a time. Anthropic warns against tools "that merely wrap existing software functionality or API endpoints," because agents read results token by token and have limited context, while traditional programs can loop over thousands of records cheaply (Anthropic). Its examples are worth copying:

A tool can run several API calls behind the scenes. The agent sees one decision instead of three, and intermediate results never fill its context.

The opposite failure exists too. Machine Learning Mastery argues that a single tool with an action parameter, such as manage_customer(action="create" | "get" | "suspend"), forces the model to pick a mode before it can solve the task, and recommends single-responsibility tools as the default. It also notes exceptions, such as shell or filesystem tools, where the action set is part of the abstraction (Machine Learning Mastery).

The test for both is the same. Each tool should have a purpose you can describe without mentioning another tool. If a description needs "unlike search_documents, this one..." to make sense, the two tools overlap and one should go.

Keep the set small. OpenAI's function calling guide, read on 2026-10-17, suggests aiming for fewer than 20 functions available at the start of a turn as a soft target, and recommends deferring rarely used tools so they load only when needed (OpenAI function calling guide).

A tool name is the first thing the model reads when it decides what to call. AI/TLDR recommends a verb_noun pattern, such as search_contacts, create_event or delete_file, because two words tell the model what action happens and what it acts on. Vague names like process, handle or data force the model to infer meaning from the description alone (AI/TLDR, Designing tools for LLM agents).

When an agent has many tools, group them with prefixes. Anthropic describes namespacing by service, such as asana_search and jira_search, and by resource, such as asana_projects_search and asana_users_search. It found that choosing prefix or suffix naming had measurable effects in its evaluations, and that the effect varies by model, so it recommends picking a scheme based on your own tests (Anthropic).

Parameter names matter as much as tool names. Anthropic's example is simple: instead of a parameter named user, name it user_id. The model then knows it needs an identifier, not a name or an email.

The description is the tool's documentation, and it is loaded into the model's context on every call. OpenAI recommends describing the purpose of the function and each parameter, including its format and what the output represents. It also suggests an "intern test": could an intern use the function correctly given only what you gave the model? If not, add the answers to the questions they would ask (OpenAI function calling guide).

A strong description answers four questions: what the tool does, what it needs, what it returns and when not to use it. Most descriptions skip the last one. Compare:

{
  "name": "search_knowledge_base",
  "description": "Search internal policies, product specs and documented workflows. Use when the user asks how something is done at the company. Do not use for live data such as prices, stock or order status; use get_order_status for orders. Returns up to 5 passages ranked by relevance. An empty result means the answer is not documented.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Plain-language question or keywords, e.g. 'refund policy for annual plans'" },
      "area": { "type": "string", "enum": ["billing", "shipping", "accounts", "product"], "description": "Optional filter by policy area" }
    },
    "required": ["query"],
    "additionalProperties": false
  }
}

The schema does as much work as the prose. Machine Learning Mastery puts it this way: a loose schema means the model guesses at constraints, while a tight one encodes them so no guessing is needed. Enums remove a whole class of plausible but invalid values (Machine Learning Mastery). OpenAI adds a related rule: use enums and object structure so invalid states cannot be expressed. Its example is toggle_light(on: bool, off: bool), which allows a call that is both on and off (OpenAI function calling guide).

Two more rules from OpenAI's guide save a lot of errors:

• Do not make the model fill arguments you already know. If your code already holds the order ID, define submit_refund() with no parameters and pass the ID yourself.
• Combine functions that are always called in sequence. If one call always follows another, merge them.

Constraints that remove guesswork pay off quickly. AI/TLDR reports that Anthropic eliminated a class of file errors by requiring absolute paths instead of relative ones, because the model stopped guessing the working directory (AI/TLDR).

What a tool returns lands in the agent's context and shapes its next step. Anthropic recommends returning "only high signal information," preferring fields like name, image_url and file_type over low-level identifiers like uuid or mime_type. It found that replacing arbitrary alphanumeric IDs with meaningful names, or even simple numbered IDs, significantly improved precision in retrieval tasks by reducing hallucinations (Anthropic).

Sometimes the agent needs an ID for the next call. Anthropic's answer is a response_format parameter with concise and detailed options, so the agent asks for IDs only when it needs them. For any tool that can return a lot of data, it recommends pagination, filtering, range selection or truncation with sensible defaults, and a message that tells the agent how to narrow its request when results are cut off.

One rule is easy to break by accident: never hide a partial failure. Machine Learning Mastery shows a bulk-create tool that swallows exceptions and returns only the records it created. The agent sees success and carries on with a wrong picture of the system. The fix is to return both lists plus an explicit flag:

{
  "created_ids": ["t_101", "t_102"],
  "failed_items": [{ "input": "Quarterly review", "reason": "due_date is in the past" }],
  "success": false,
  "partial_success": true
}

The agent can then retry the failed item, tell the user or stop (Machine Learning Mastery).

A human developer who hits 400 Bad Request can read the docs. An agent cannot leave its loop. Szymon Pacholski describes the result: with a bare error, the agent learns only that something went wrong, and in the worst case "retries indefinitely with the same broken input, burning tokens and time" (Pacholski, Error handling for AI agents). His rule is that every error must tell the agent what to do next, in three parts: what failed, why it failed and how to fix it.

{
  "error": "Invalid value for field 'status'",
  "received": "done",
  "allowed_values": ["pending", "in_progress", "completed", "cancelled"],
  "hint": "Did you mean 'completed'?"
}

Not every error is fixable by the agent. A missing field is. A rate limit or an outage is not. Both Pacholski and Machine Learning Mastery recommend an explicit flag, called retryable or recoverable, plus a suggested next action, because without it models retry errors that cannot succeed and abandon ones that could (Machine Learning Mastery).

AI/TLDR sums up the pattern: state what went wrong, why, and what the correct form looks like, ideally with an example inside the error string (AI/TLDR).

Tools that change state need more care than tools that read. Agents retry, networks drop responses and a loop can issue the same call twice. Machine Learning Mastery recommends making every write idempotent, for example with an idempotency key, so a repeated call returns the original result instead of sending a second email or a second payment (Machine Learning Mastery).

Irreversible actions need a structural confirmation step, not a polite "are you sure?" in the prompt. The pattern is two tools: stage_deletion returns a short-lived token and a summary of what will happen, and confirm_deletion acts only on a valid token after the user approves. The model cannot complete the destructive action in a single step.

Permissions belong in code. MLflow's guidance is direct: prompt-based restrictions "can be bypassed through prompt injection or model drift," while identity checks, least privilege and isolation in the surrounding code cannot be overridden by crafted input. It recommends separate permission tiers for read, write and destructive operations, and warns that broad permissions granted "for testing" tend to survive into production (MLflow).

A short checklist for any tool that writes:

• It accepts an idempotency key or is naturally idempotent.
• It checks the caller's permissions itself, using the identity your code supplies.
• Destructive actions use a stage and confirm pair.
• Limits such as amounts and rate caps are enforced in the tool, whatever the arguments say.

You cannot know which tools an agent finds easy to use without watching it use them. Anthropic recommends building a quick prototype, then running an evaluation of realistic tasks that may need many tool calls, and tracking more than accuracy: runtime per call, number of calls, tokens used and tool errors (Anthropic). Patterns in those numbers point to fixes. Many redundant calls suggest pagination or limits need adjusting. Many invalid-parameter errors suggest the description or examples need work.

Read the transcripts, not only the scores. Anthropic gives an example from its own web search tool: the model kept adding a year to search queries, which biased the results, and a change to the tool description fixed it. Small description edits can have large effects, and only an evaluation tells you which ones help.

If you build agents on Quanta Intelligence, the same discipline applies to the skills and tools you give them: a short, distinct set of task-shaped tools, each with a description that says when not to use it.