Tools
Declare a tool, its parameters and the facts it needs. A tool is how an agent reads or changes something in your systems.
On this page
- A Domain Pack: The Domain Pack
- At least one agent: Agents
How a tool call flows
You declare the tool in your Domain Pack. The agent decides when to call it. The platform sends the call to your adapter, and your adapter’s answer goes back to the agent.
Declare a tool
A tool lives in your pack’s tools file. It is versioned like every other entry: a change is a new version, and a pipeline runs the version it pins. Each version has a description, which the agent reads to decide when to call the tool, and a list of parameters. Write the description for the agent: say what the tool does, when it is the right one, and what to do with its result.
{
"toolName": "find_slots",
"versions": [
{
"version": 1,
"toolName": "find_slots",
"description": "Finds free repair slots at this shop for one service on one day. Call it before book_repair, and show the contact the times it returns. The result lists each time with a slot handle; pass the chosen time's handle to book_repair and never show a handle to the contact.",
"parameters": [
{ "name": "service", "type": "string", "required": true,
"description": "The service code from get_shop_info, for example \"brake-service\"." },
{ "name": "date", "type": "string", "required": true,
"description": "The day, as YYYY-MM-DD in the shop's time zone." }
]
}
]
}
Tool names are snake_case. A parameter has a name, a type, a description and required.
Parameters
- Ask only for what the tool needs. Every parameter is something the agent must find out first.
- Describe each parameter with its format and an example. The agent fills parameters from the description.
- Personal data goes only to the tool that records it.
book_repairtakes the contact’s name;find_slotsdoes not.
The platform sends the Partner and the contact’s phone in every call’s context. Never add them as parameters.
Tools that depend on what you know about the contact
Some tools only make sense in a given state: Cogwheel’s move_booking needs an open booking. Your adapter reports such state as facts when it resolves the contact’s context, and a tool version can require them. A fact can also fill a parameter, so the agent never has to ask for or copy a value you already hold.
{
"version": 1,
"toolName": "move_booking",
"description": "Moves the contact's open booking at this shop to another free slot.",
"requires": [{ "fact": "has_open_booking", "equals": true }],
"parameters": [
{ "name": "booking_ref", "type": "string", "required": true, "fact": "open_booking_ref",
"description": "The open booking's reference." },
{ "name": "slot_id", "type": "string", "required": true,
"description": "The handle of the new slot, from find_slots." }
]
}
Declare each fact once, with its type, in your Domain config’s context-facts.json. When a required fact does not hold, the platform refuses the call before it reaches your adapter, with the error code precondition_failed. See Facts.
Give tools to an agent
An agent can call only the tools listed on its version. Give each agent the smallest set it needs: Cogwheel’s booking agent gets the five booking tools, and its shop information agent gets only get_shop_info.
"tools": [
{ "toolName": "get_shop_info", "versionNumber": 1 },
{ "toolName": "find_slots", "versionNumber": 1 },
{ "toolName": "book_repair", "versionNumber": 1 },
{ "toolName": "get_booking", "versionNumber": 1 },
{ "toolName": "move_booking", "versionNumber": 1 }
]
Tools the platform provides
| Tool | When an agent has it |
|---|---|
hand_off_to_human | When human hand-off is on for the pipeline. You do not declare or implement it. See Human hand-off. |
What your adapter returns
Every call is answered with the tool envelope: a success with text for the agent, or an error with a category and a message the agent can act on. Executing tools walks through both.