A tool is a name, a description and a JSON Schema for its parameters. If your agent already sends tools to OpenAI or Anthropic, you can send the same list.
Accepted shapes
All three of these describe the same tool. Send whichever you have; you can mix them in one list.
OpenAI
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Look up where an order is and when it will arrive.",
"parameters": {
"type": "object",
"properties": { "order_id": { "type": "string", "description": "Order number, digits only" } },
"required": ["order_id"]
}
}
}Anthropic
{
"name": "get_order_status",
"description": "Look up where an order is and when it will arrive.",
"input_schema": {
"type": "object",
"properties": { "order_id": { "type": "string", "description": "Order number, digits only" } },
"required": ["order_id"]
}
}Plain
{ "name": "get_order_status", "description": "Look up where an order is and when it will arrive.", "parameters": { "type": "object", "properties": {} } }Rules
A build is rejected with 422 TOOL_DEFINITION_INVALID when a tool breaks one of these. The error lists every problem, each with the tool's name and a JSON pointer to the field.
| Rule | Limit |
|---|---|
| Name | Letters, digits, _ and -, 1 to 64 characters. Unique within the toolset, ignoring case. |
| Parameters | A JSON Schema object ("type": "object"), at most 64 properties, nested at most 10 levels. |
required | Every listed name must be a property. |
| Description | Up to 16,384 characters. Past 4,096, only the start is used for matching. |
$ref | Local references only (#/...). No remote schemas, no cycles. |
enum | Up to 2,048 values. |
| Tools per toolset | 20 on Free, 2,000 on Plan A, 10,000 on Plan S, no limit on S+. |
| Request body | 1 MiB. |
Some problems are warnings, not errors: a missing or very short description, a parameter with no description. The build goes ahead and the warnings come back in the response, because these tools are harder to pick and to fill.
Writing tools that get picked
Matching reads the name, the description and the parameter descriptions. A few habits make a large difference:
- Start the description with what it does. "Refund an order in full or in part to the original payment method." beats "This endpoint handles refunds."
- Say when to use it if there's a near neighbour. "Cancel an order that has not shipped yet" separates it from refunding.
- Describe every parameter the way a person would say it: "Number of people", not "int, required". Arguments are found by those descriptions.
- Use
enumfor fixed choices. A value outside the list is never returned. - Use
formatfor dates (date,date-time) and email addresses (email). Relative dates like "tomorrow" are turned into real dates in the user's time zone. - Name with a verb first:
get_,list_,search_,delete_. The first word sets the default side effect.