Tool Design for AI Agents: Descriptions, Errors and Retries

The agent picks the wrong tool, fills in an input wrongly or repeats an action that should run once. The model is not being careless. It can only choose from the text you wrote about each tool.

Picture a common setup. A produce wholesaler sells jeera (cumin), groundnut and onions in bulk to hotels, caterers and shops. Its team built an ordering agent: a chat program that answers buyers and can also take actions, such as booking an order. The setup is made up, but the problems are real.

In its first month, three things went wrong:

• Wrong tool. A caterer asks for today's jeera rate and says to book 40 kg if it is under Rs 300 a kg. Today's price is Rs 285, but the agent calls a tool named search, finds an old list showing Rs 310 and books nothing.
• Wrong input. A buyer asks for 4 quintal of onions, and a quintal is 100 kg, so she wants 400 kg. The order tool's input was called quantity with no unit, so the model sent 4 and the system booked 4 kg.
• Repeated action. An order for 40 kg of groundnut times out, meaning the agent stops waiting for a reply. The model tries again through a second tool, order_v2. Both calls had worked, so the buyer gets two deliveries and two bills.

The logs, the saved records of every chat and tool call, showed the cause. The agent had nine tools with names like search, get_data, rates and price_lookup. Several did the same job, and none said when to use it.

Think of a kitchen with nine spice jars, where three are labelled masala. A new cook grabs one at random. The cook is not the problem; the labels are. Where the picture breaks: a cook can open a jar and smell it, but the model cannot open your code. It has only the labels.

The rest of this guide fixes the labels first, then the inputs, the errors and the retries, one failure at a time.

You need five words: agent, tool, tool definition, schema and idempotent. Each one gets a plain meaning and an example from the ordering agent.

Agent. An AI agent is a program where a language model decides the next step. A language model is a program trained on large amounts of text to write the next words. Your code, called the agent loop, sends the chat to the model, runs the action it asks for and repeats until the job is done.

Tool. A tool is an action the model can ask for, which your code runs. Example: get_today_price looks up today's rate for one crop. The model only asks. Your code runs the tool and sends back the answer, called the tool result.

Tool definition. A tool definition is the short text the model reads about each tool: a name, a description and a list of inputs, called parameters. Unless your prompt adds more, it is all the model knows about the tool. Example: get_today_price, described as: Get today's price for one crop, in rupees per kg.

Schema. A schema is a set of rules for what shape the inputs must have. MCP and many model services describe tool inputs with JSON Schema, an open standard for describing data in JSON, a plain-text format for data. Example: crop must be one of onion, groundnut, jeera or cotton_seed.

Idempotent. A tool is idempotent when calling it twice with the same input has the same effect as calling it once. Reading a price is idempotent. Placing an order is not, unless you design it to be.

Tool design for AI agents is the work of naming, describing and shaping the actions a model can ask your program to run. It covers four parts: the tool list, the inputs, the errors and the retries.

It matters because the model cannot see your code. It chooses only from the names, descriptions and input rules you wrote, so those few lines of text are the whole interface between the model and your system.

The model reads your tool definitions as text, together with the chat so far, and writes back a tool name plus values for its inputs. In the basic setup, none of your code matches the message to a tool; the model does.

So every tool definition is part of the prompt, the text sent to the model on each request. Two definitions that sound alike force the model to guess, and it may guess differently on two similar messages.

Definitions also cost money. Tool definitions are usually sent to the model as part of the prompt, so each one adds tokens, the small pieces of text a model reads and writes. All nine old ones were sent even with a simple hello.

With the old tools, the model saw search next to rates and price_lookup. All three could answer a price question, and nothing told it which one to use.

Give each tool one job and a name that states that job as a verb and a noun. Then write a description that says what it does, when to use it and when not to. Write it for a reader who knows nothing about your system.

A name like get_today_price says the action and the thing. Names like search or get_data could mean almost anything. Avoid version numbers too: if order and order_v2 are both visible, the model cannot tell the first one is old.

A good description answers four questions, in this order:

• What does it do? Get today's mandi (wholesale market) price for one crop, in rupees per kg.
• When should the model use it? When the buyer asks what a crop costs today.
• When should it not? Not for stock levels or past prices, which have their own tools.
• What comes back? The price, the grade and the time the price was last updated.

The when-not-to-use-it line does the most work. Most wrong picks happen between two close neighbours, like price and stock. One sentence that points to the other tool settles the choice.

Here is what the team changed. The old list had nine tools and the new one has six.

Names can also clash when one agent gathers tools from several MCP servers. The MCP specification gives the example of two servers that both expose a search tool. It says clients should handle this, for example by adding a prefix that names the server.

Design parameters so the model has few ways to get them wrong: strict types, fixed lists of allowed values, units in names and one date format. Anything your code already knows should not be a parameter.

The quintal mix-up from the opening shows why. The old input was called quantity, with no unit, so 4 quintal became 4 kg. The team now follows these rules for every input:

• Put the unit in the name: quantity_kg, not quantity. Say in the description that 1 quintal is 100 kg.
• Use the real type: quantity_kg is a number, not text like forty, so the schema can reject anything else.
• Use a fixed list of allowed values wherever you can. JSON Schema calls this an enum, short for enumeration.
• Pick one date format, such as 2026-10-23 (year, month, day). Put today's date in the prompt, so the model can turn Thursday into a real date.
• Mark which inputs are required. Give optional ones a clear default, like grade A when the buyer does not say.
• Keep the list short. Three or four inputs are easier to fill correctly than ten.

Here is the new price tool as a Python dictionary. The input_schema part is plain JSON Schema. MCP calls the same field inputSchema, and model services use their own key names, so check your provider's documentation.

GET_TODAY_PRICE = {
    "name": "get_today_price",
    "description": (
        "Get today's mandi price for one crop, in rupees per kg. "
        "Use this when the buyer asks what a crop costs today. "
        "Do not use it for stock levels; call check_stock for that. "
        "Returns the price, the grade and when the price was updated."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "crop": {"type": "string",
                     "enum": ["onion", "groundnut", "jeera", "cotton_seed"]},
            "grade": {"type": "string", "enum": ["A", "B"],
                      "description": "Quality grade. Use A if the buyer does not say."},
        },
        "required": ["crop"], "additionalProperties": False,
    },
}

Two lines matter most. The enum means crop can only be one of four words, so a buyer's cumin must become jeera. Setting additionalProperties to False rejects any input the schema does not list.

You can check a schema before any model sees it. Install the checker with pip install jsonschema==4.25.1. Put the dictionary above and this code in one file, then run it:

from jsonschema import Draft202012Validator

checker = Draft202012Validator(GET_TODAY_PRICE["input_schema"])
tries = [{"crop": "jeera"}, {"crop": "cumin"},
         {"crop": "jeera", "qty": 5}, {"grade": "A"}]
for args in tries:
    errors = [e.message for e in checker.iter_errors(args)]
    print(args, "->", errors or "OK")

The checker uses JSON Schema draft 2020-12, which is also the version MCP assumes when a schema does not name one. Expected output on Python 3.13 with jsonschema 4.25.1:

{'crop': 'jeera'} -> OK
{'crop': 'cumin'} -> ["'cumin' is not one of ['onion', 'groundnut', 'jeera', 'cotton_seed']"]
{'crop': 'jeera', 'qty': 5} -> ["Additional properties are not allowed ('qty' was unexpected)"]
{'grade': 'A'} -> ["'crop' is a required property"]

Return errors as normal tool results that say what went wrong, whether trying again can help, and what to do next. A clear error lets the model fix its own mistake instead of giving up.

Say a buyer asks for delivery on a date that has already passed. The old order tool returned Error 500, so the model apologised and stopped. The new tool returns a short structured error instead.

A useful error has four parts:

• code: a short fixed label, like DATE_IN_PAST, that your program and your logs can count.
• message: what went wrong in plain words, like delivery_date 2026-10-12 is before today, 2026-10-19.
• retryable: true if the same call might work later, like after a timeout, and false if it never will.
• fix: what to do next, like asking the buyer for a date from tomorrow onwards.

Web APIs, the services programs call over HTTP, already have a standard for this idea: Problem Details, in RFC 9457. An RFC is a numbered document in the series that publishes internet standards, and this one comes from the IETF, the group that writes them. RFC 9457 defines fields such as type, title, status and detail, and replaces the older RFC 7807.

It also warns against exposing a stack dump, the long listing a program prints when it crashes, because it can reveal how your server works. The same rule fits tool errors: tell the model what to fix, not how your server failed.

The Model Context Protocol makes a split worth copying. Errors the model can fix, like a date in the wrong format or a value out of range, go back inside the tool result with isError set to true. Its specification says clients should pass these to the model so it can correct itself.

Problems with the request itself, like an unknown tool name, go back as protocol errors instead. The specification says models are less likely to recover from those, so clients may pass them on but need not.

Timeouts on tools that are safe to repeat do not reach the model at first, because your code retries them quietly and waits longer each time. Engineers call this backoff. The repeat count also lives in your code, so a confused model cannot loop forever.

Give an agent as few tools as its job needs, and never two tools that do the same thing. There is no magic number, but every extra tool is one more wrong choice the model can make.

Two papers point the same way. A 2024 paper tested function calling on edge devices, small low-power computers that run a model locally. Offering fewer tools per request improved success rates and cut execution time by up to 70%.

A 2025 paper tested very large lists of MCP tools. A search step that picked the few relevant tools before the model chose raised correct picks from 13.62% to 43.13% in its tests. It also cut prompt tokens by more than half.

For the ordering agent, merging look-alike tools and deleting unused ones was enough. Teams with dozens of tools often use one of two patterns:

• Route first: a small first step decides what the message is about, like orders or payments, and the agent then sees only that group's tools.
• Search first: your code finds the few tools whose descriptions best match the message, and shows only those to the model.

Build a small test set of real messages, each with the tool and key inputs it should lead to, and run it after every change. A test set is a fixed list of example inputs with the answers you expect.

Here the answer is not the final reply. It is which tool the model calls first, and with what inputs.

The team starts with 40 messages from old chats, with buyer names removed. They make sure the set includes:

• Close neighbours, like a price question and a stock question about the same crop.
• Unit traps, like 4 quintal, 400 kg and half a tonne.
• Date words, like Thursday, tomorrow and day after tomorrow.
• Messages that need no tool, like thank you, so the agent does not call one for no reason.
• Messages that mix English with a local language, the way buyers really type.

They then run the set in five steps:

1. 1

   Write the expected answer

   For each message, write the tool the model should call first and its key inputs. Book 4 quintal onions for Friday should call place_order with quantity_kg 400.

2. 2

   Run every message a few times

   The model can answer differently on two runs. Three runs per message show which choices are shaky.

3. 3

   Score the tool and the inputs separately

   The right tool with 4 kg instead of 400 kg is still a failure, so count both.

4. 4

   Read every failure

   Ask which words in the tool list misled the model. The fix is usually a name, a description or an enum.

5. 5

   Run it again after every change

   Rerun the set when you change a tool, the prompt or the model. A fix for one tool can break the choice between two others.

On the team's set, the old nine tools picked correctly on 29 of 40 messages and the six new tools on 38 of 40 (made-up numbers). Both misses were date words, so the team moved today's date to the top of the prompt and reran the set.

Make every tool that changes data idempotent, with a request key that your code builds and your database enforces. A repeat call with the same key then returns the first result instead of doing the work again.

Go back to the double groundnut order. The first call saved the order, but the reply came too late, so it looked like a failure. A timeout tells you only that you did not hear back, not whether the work was done.

HTTP's core standard, RFC 9110, draws the same line. It lets a client repeat an idempotent request automatically after a connection failure. It says a client should not automatically retry a non-idempotent request unless it can tell the request is actually idempotent or never took effect.

Reading tools like get_today_price are already idempotent: ask twice, get the same price, change nothing. Tools that change data, like place_order, need a request key, often called an idempotency key: a unique id for one intended action.

Your code builds the key, not the model

If the model invents the key, a retry may arrive with a new one, and the tool sees a fresh order. So the agent loop builds the key from the chat id, the buyer and the order details: crop, quantity and delivery date.

The same key comes out even when the model retries through a new tool call. If the buyer really wants a second, identical order, the agent asks them to confirm, and your code adds an order number to the key. A repeat order is then chosen, never guessed.

The place_order tool in code

Here is the new place_order tool. It runs as it is with Python's built-in sqlite3 module, which uses SQLite, a small database stored in one file or in memory. This form of ON CONFLICT, which SQLite calls UPSERT, needs SQLite 3.24.0 or later.

import sqlite3

db = sqlite3.connect(":memory:")
db.execute("""CREATE TABLE orders (
    id INTEGER PRIMARY KEY, buyer_id TEXT NOT NULL, crop TEXT NOT NULL,
    quantity_kg INTEGER NOT NULL, delivery_date TEXT NOT NULL,
    request_key TEXT NOT NULL UNIQUE)""")


def place_order(buyer_id, crop, quantity_kg, delivery_date, request_key):
    if not 10 <= quantity_kg <= 5000:
        return {"ok": False, "code": "BAD_QUANTITY", "retryable": False,
                "message": f"{quantity_kg} kg is outside 10 to 5000 kg",
                "fix": "Ask the buyer again. 1 quintal is 100 kg."}
    cur = db.execute(
        "INSERT INTO orders (buyer_id, crop, quantity_kg, delivery_date,"
        " request_key) VALUES (?, ?, ?, ?, ?)"
        " ON CONFLICT (request_key) DO NOTHING",
        (buyer_id, crop, quantity_kg, delivery_date, request_key))
    db.commit()
    order_id = db.execute("SELECT id FROM orders WHERE request_key = ?",
                          (request_key,)).fetchone()[0]
    note = "New order placed" if cur.rowcount == 1 else "Already placed"
    return {"ok": True, "order_id": order_id, "note": note}


key = "chat-8812|B-17|groundnut|40|2026-10-23"
print(place_order("B-17", "groundnut", 40, "2026-10-23", key))
print(place_order("B-17", "groundnut", 40, "2026-10-23", key))  # the retry
print(place_order("B-17", "onion", 4, "2026-10-23", "chat-8812|B-17|onion|4|2026-10-23"))
print(db.execute("SELECT COUNT(*) FROM orders").fetchone()[0], "order row")

Pause and predict: the second call is the retry after the timeout. Will the table hold one order or two? Expected output on Python 3.13 with SQLite 3.45.1:

{'ok': True, 'order_id': 1, 'note': 'New order placed'}
{'ok': True, 'order_id': 1, 'note': 'Already placed'}
{'ok': False, 'code': 'BAD_QUANTITY', 'retryable': False, 'message': '4 kg is outside 10 to 5000 kg', 'fix': 'Ask the buyer again. 1 quintal is 100 kg.'}
1 order row

What just happened? The first call saved order 1. The retry carried the same key, so the insert did nothing and the tool returned order 1 with the note Already placed. The 4 kg order failed the range check before anything was saved.

Three design choices matter. buyer_id and request_key come from your code, never from the model. The duplicate check and the save are one statement. And the UNIQUE rule on request_key lets the database, not your code, decide which call wins.

With the UNIQUE rule added, the second save in that test failed with an error instead, and one order stayed. With ON CONFLICT DO NOTHING, five retries at once left exactly one order in 10 of 10 trials. PostgreSQL has the same ON CONFLICT DO NOTHING clause.

Retry automatically only tools that are safe to repeat, wait longer after each failure, add a little randomness and stop after a fixed number of tries. Everything else goes back to the model or to a person.

Waits that double each time are called exponential backoff: here about 1, 2 and then 4 seconds. The small random extra on each wait is called jitter. It spreads the retries out, so calls that failed together do not all retry at the same moment.

import random
import time


class ToolTimeout(Exception):
    pass


def call_with_retry(tool, args, idempotent, retries=3):
    for attempt in range(retries + 1):
        try:
            return tool(**args)
        except ToolTimeout:
            if not idempotent or attempt == retries:
                return {"ok": False, "code": "NO_ANSWER", "retryable": False,
                        "message": "No reply. The action may or may not have run.",
                        "fix": "Hand to staff to check before trying again."}
            wait = 2 ** attempt + random.uniform(0, 0.5)  # 1, 2, 4 s + jitter
            print(f"timeout, retrying in {wait:.1f} s")
            time.sleep(wait)


calls = []


def slow_tool(**args):  # stands in for a tool that times out twice
    calls.append(args)
    if len(calls) < 3:
        raise ToolTimeout()
    return {"ok": True, "note": "done"}


print(call_with_retry(slow_tool, {}, idempotent=True), len(calls), "calls")
calls.clear()
print(call_with_retry(slow_tool, {}, idempotent=False), len(calls), "call")

Expected output: two timeout lines, the first wait between 1.0 and 1.5 seconds and the second between 2.0 and 2.5 seconds. Your numbers will differ because of the jitter, and the run takes between 3 and 4 seconds.

timeout, retrying in 1.2 s
timeout, retrying in 2.3 s
{'ok': True, 'note': 'done'} 3 calls
{'ok': False, 'code': 'NO_ANSWER', 'retryable': False, 'message': 'No reply. The action may or may not have run.', 'fix': 'Hand to staff to check before trying again.'} 1 call

The second run stops after one call. A tool not marked as safe to repeat is never retried blindly; a person checks first.

Where does the safe-to-repeat flag come from? For your own tools, you set it. MCP lets a server attach optional annotations to a tool, including idempotentHint, a hint that repeat calls with the same arguments have no extra effect. It is a claim by the server, not a promise.

The 2026-07-28 MCP specification says clients must treat annotations as untrusted unless they come from trusted servers. So never retry a write just because an outside server's hint says it is safe.

Explain it as a contract between the model and your code: clear tools going in, structured results coming out, and retries that cannot repeat an action. Interviewers want to see that you design for the model's mistakes, not only the happy path.

1. 1

   Start with how the model chooses

   The model picks from names, descriptions and schemas alone, so overlapping tools cause wrong picks.

2. 2

   Design the tool list

   A few tools with one job each, verb_noun names, and descriptions that say when not to use them.

3. 3

   Tighten the inputs

   Enums, units in names and one date format. Ids come from your code, never from the model.

4. 4

   Shape the errors

   A code, a message, a retryable flag and a fix. Cap repeated errors in the loop and hand over to a person.

5. 5

   Make writes idempotent

   A request key built by your code on every tool that changes data, enforced by a UNIQUE rule in the database.

6. 6

   Show how you test

   The test set, the two scores you track, and when you rerun it.