Many tools, and how it chooses

Adding a second tool is adding a second function. Making the agent pick the right one is a writing problem, not a code problem.

Two tools

python

def lookup_order(order_id: str) -> dict:
    """Look up the delivery status of an existing order by its id."""
    return {"status": "success", "state": "shipped"}


def refund(order_id: str, amount: int) -> dict:
    """Refund an amount in rupees to the customer for an order."""
    return {"status": "success", "refunded": amount}

Read the two docstrings rather than the code. One is about where something is, the other is about money going back. That difference is the whole basis of the model's choice.

python

agent = LlmAgent(
    name="support",
    model=PretendModel(replies=[call("refund", order_id="A17", amount=500),
                                say("I have refunded 500 rupees.")]),
    instruction="Help with orders. Use the right tool for the job.",
    tools=[lookup_order, refund],
)

Example

print("tools it has:", [t.__name__ for t in agent.tools])
print("answer:      ", await ask(agent, "Please refund 500 rupees for order A17"))

The stand-in is scripted here so the lesson stays about the wiring. A real model makes that choice from three things only: the names, the descriptions and the parameters.

What makes a description work

Weak	Better	Why
Looks up an order	Look up the delivery status of an existing order by its id	Says what kind of question this answers
Refunds	Refund an amount in rupees to the customer for an order	Says what it does to the world, and in what unit
Handles cancellations	Cancel an order that has not shipped yet	Says the condition, so it is not chosen after shipping

The pattern is the same every time: what it does, to what, and when it applies. A description that only names the mechanism leaves the model to guess the situation.

Print the declarations from lesson 3, side by side, and read them the way the model does.
Look for overlap. Two descriptions that could both answer the question is a description problem.
Name the boundary in the instruction as a last resort.

Edit descriptions, not prompts

Fixing tool choice by writing a longer instruction is the slow way round. The model reads tool descriptions every turn, and they are shorter, so that is where the fix belongs.

Try it yourself

Make both descriptions vague and see whether the right tool is still chosen.
Add a third tool that overlaps the other two, then rewrite it so it does not.

PreviousWhat a tool should return

This is what real progress feels like.