Tools and tool calling

What a tool looks like to a model

A model never touches your CRM or your inbox directly. It is shown a list of tools, each described in three parts, and it asks for one to be used. The surrounding runtime does the actual work. Every tool, in every agent framework, has the same shape:

• A name, such as search_invoices.
• A description in plain language: what it does, when to use it, what it returns.
• An input schema: the parameters it accepts, their types, which are required, and what each one means.

The description is the part people underrate. The model chooses a tool almost entirely by reading descriptions. A vague description is like a vague job ad: you get the wrong applicant.

How a tool call works

When the model decides it needs a tool, it does not run code. It produces a structured request: the tool's name and a set of arguments. Then the runtime takes over:

1. Validate. Do the arguments match the schema? Is anything required missing?
2. Check permission. Is this agent allowed to use this tool, in this system, for this person? Does the action need someone's approval first?
3. Execute. Call the real system with the person's own access.
4. Return. Hand the result, or the error, back to the model, which reads it and decides what to do next.

Steps 1 and 2 are where good runtimes earn their keep. The model proposes; the runtime disposes. A model can ask to delete a record; whether that happens is a decision made outside the model, by rules and by people.

Writing a tool description a model can use

You may never write a tool from scratch, but you will judge tools, choose between them, and write instructions that steer them. The same checklist applies to all three. A good description says:

1. What it does, in one plain sentence.
2. When to use it, and when not to. "Use for unpaid invoices. For paid invoices use search_payments."
3. What each parameter means, with formats and examples. Not "date" but "due date on or before this day, ISO format, e.g. 2026-09-30."
4. What it returns, so the model knows what it will have to work with.
5. Side effects: does it only read, or does it change something? Can it be undone?

create_meeting(title, time, people)
"Creates a meeting."

create_meeting(title, start, duration_minutes, attendee_emails, timezone)
"Creates a calendar event and SENDS invitations to every attendee.
 Only call after find_free_time has returned a confirmed slot.
 start: ISO 8601 date-time, e.g. 2026-09-29T14:00.
 attendee_emails: addresses from lookup_contact only. Never construct one.
 Returns the event id and link."

Predicting tool failures

Tool calls fail in a small number of recognisable ways. Learn to spot them in a run:

• Wrong tool: it sent an email when it should have saved a draft. Usually caused by overlapping descriptions.
• Missing parameter: a required field was left out or filled with a lazy default.
• Hallucinated parameter: it passed an argument that is not in the schema at all.
• Ungrounded value: the argument is valid but the value came from nowhere: a guessed email address, an invented ID.
• Ignored error: the tool failed and the agent carried on as if it had worked.
• Loops: the same search, again and again, with tiny variations.

Lesson 9 turns these into things you can test for. For now, when you read a run, check every tool call against two questions: was this the right tool? and where did each value come from?

More tools is not better

An agent given forty tools picks the wrong one more often than an agent given six. The descriptions start to overlap, and every extra tool costs tokens on every step. Two practical rules follow:

• Give an agent the tools its job needs, not every tool you have. A finance agent does not need your design tools.
• Prefer read access unless the job truly needs write. This is least privilege from the Responsible AI course, applied to tools: narrow access limits how far a mistake can travel.

In Renly, the descriptions of built-in tools are written and maintained by Renly, and tools from an MCP server come with that server's own descriptions. What you control is which connectors an agent may use, whether it may only read or also write, and the instructions that tell it how to use them.