Module 2 · Building Agents · scripted
Tool Parameters and Descriptions
Overview
If the tool list gives the agent its words of action, this lesson gives that language its grammar. Parameters state exactly how each word may be spoken — a calendar will not accept "sometime Tuesday" — and descriptions define words the model has never heard before, because everything the LLM knows about a tool comes from the conversation itself. In this lesson, we learn to write the grammar precisely enough that every action the agent speaks is legal, and to teach the language entirely new words — even for tools that did not exist when the model was trained.
Tools have controls
Declaring which tools exist bounds what actions the agent can take. But a real tool also constrains how it may be used. The microwave from last lesson wants a power level and a time. A calendar wants a date, a start time, and a duration. An email won't send without an address.
These are the tool's parameters: the inputs a tool requires before it can act at all.
Two tools, spelled out
schedule_meeting( date, start: 24-hour HH:MM, duration: whole minutes, title )
send_email( to: email address, subject, body )
Say exactly what the tool accepts
Here is where precision starts to matter enormously. How a parameter must be expressed depends on the actual tool — and the LLM can only know what the conversation tells it:
The same calendar, four honest contracts
- Why is "2:30 PM" a perfectly good answer for calendar B and a meaningless one for calendar A?
- What happens to the conversation if the LLM starts issuing "2:30 PM" commands at calendar A?
Why be this careful? Because of everything we know about trajectories. At the start of the conversation, we want to provide enough information that the LLM heads off on a trajectory that leads efficiently to a correct solution. If it begins writing times in a format the tool doesn't accept, those invalid actions are now in the conversation — conditioning what comes next, costing correction turns, and bending the trajectory. (There are ways to catch and repair invalid tool use, which come later — but repair is always the expensive path. Precision up front is the cheap one.)
You have the following tools available for use:
- find_free_slot( date, duration: whole minutes )
- schedule_meeting( date, start: 24-hour HH:MM, duration: whole minutes, title )
- send_email( to: email address, subject, body )
Task: Schedule a 45-minute project check-in with the two collaborators next Tuesday, June 9, and email them both the details. Their addresses: a41@example.com and b17@example.com.
Rules: the same five rules as before.
Step 1: Use find_free_slot( 2026-06-09, 45 ) - Find an opening before promising anyone a time.
The calendar returns one free slot: 10:15.
Step 2: Use schedule_meeting( 2026-06-09, 10:15, 45, Project check-in ) - Booking the slot we just found.
The meeting is created.
Step 3: Use send_email( a41@example.com, Project check-in Tuesday, "Hi — our check-in is Tuesday June 9, 10:15–11:00. See you then." ) - One participant at a time.
The email to a41@example.com was sent.
Step 4: Use send_email( b17@example.com, Project check-in Tuesday, "Hi — our check-in is Tuesday June 9, 10:15–11:00. See you then." ) - And the second participant.
The email to b17@example.com was sent.
END
Tools the LLM has never heard of
There is a second thing every tool may need: a description. Not all tools are well known to the LLM. It has never seen your lab's equipment, your company's internal software — or, say, the escape systems of an alien spaceship:
You have the following tools available for use:
- QX754( toppings )
- VN2( song )
- PRT9( destination on Earth )
Descriptions: QX754 bakes one alien pizza in the ship's galley synthesizer — Zorblaxian guards cannot resist the smell and will leave their posts to investigate. VN2 plays one Beatles song over the ship-wide speakers; Beatles harmonies put Zorblaxians into a trance for exactly 3 minutes. PRT9 opens a portal to Earth in the cargo bay for 30 seconds, and takes 2 minutes to charge — the charging whine is loud enough to alert any guard nearby.
Task: I am locked in the cargo bay's holding cell, the cell door unlatches from outside the bay, and two guards are posted here. Get me back to Earth.
Rules: the same five rules.
Step 1: Use QX754( quadruple gloop-cheese ) - The smell will pull both cargo-bay guards to the galley, on the far side of the ship — and someone leaving usually unlatches the cell to gloat first. Tell me what happens.
The synthesizer hums. Both guards sniff the air, unlatch my cell to taunt me about pizza, and hurry out toward the galley.
Step 2: Use VN2( Here Comes the Sun ) - Three minutes of trance covers the portal's two-minute charging whine — even if the pizza brings them back early.
The speakers ring out. Somewhere down the corridor, two Zorblaxians are swaying and humming along.
Step 3: Use PRT9( Nashville, Tennessee ) - Charged under cover of the trance. You have 30 seconds — run.
A shimmering portal opens in the cargo bay. I jump through — I'm standing on Broadway in Nashville, Tennessee.
END
Now the same ship, but the names describe themselves — and the descriptions are gone:
You have the following tools available for use:
- cook_irresistible_alien_pizza( toppings )
- play_trance_inducing_beatles_song( song )
- open_portal_to_earth( destination on Earth )
Task: I am locked in the cargo bay's holding cell, the cell door unlatches from outside the bay, and two guards are posted here. Get me back to Earth.
Rules: the same five rules.
Step 1: Use cook_irresistible_alien_pizza( quadruple gloop-cheese ) - An irresistible pizza should pull the guards off their posts. Tell me what happens.
The synthesizer hums. Both guards sniff the air, unlatch my cell to taunt me about pizza, and hurry out toward the galley.
Step 2: Use play_trance_inducing_beatles_song( Here Comes the Sun ) - Hold them in a trance so nothing interrupts the escape.
The speakers ring out. Somewhere down the corridor, two Zorblaxians are swaying and humming along.
Step 3: Use open_portal_to_earth( Nashville, Tennessee ) - The way home. Run.
A shimmering portal opens in the cargo bay. I jump through — I'm standing on Broadway in Nashville, Tennessee.
END
Creative combination
Nobody described this plan. Given nothing but a set of tools and a goal, the agent searched for a way to COMBINE them: pizza to clear the guards, a song to cover the escape, a portal to go home.
Give an agent tools, and it will put them together in unexpected ways to solve novel problems.
The name is the first description
The worse the names, the bigger the descriptions you have to write.
So a tool, fully stated, has three parts: a name, a description of what it does and how it behaves, and parameters with exactly what values they accept. Get those three right in the conversation, and the agent's actions arrive legal, precise, and executable — which is exactly what we'll need when the participant performing the actions stops being a patient human and becomes a computer.
Take one real tool from your research — an instrument, a dataset query, a piece of software. Write its name, description, and parameters precisely enough that an LLM could operate it without a single invalid action. Then test it: give the spec and a goal to an LLM, and audit every action it proposes against your spec.