Bluwing/Docsv0.9.0
Operational
API ReferenceConsole

Get started

  • Introduction
  • Quickstart
  • How it works

Build

  • Tool format
  • Matching hints
  • Toolsets and builds
  • Versions and live

Call

  • Resolve a request
  • Reading responses
  • OpenAI and Anthropic compatibility

Account

  • Authentication
  • Credits and billing
  • Limits
  • Errors
  • Security and data
  • FAQ

Build

Tool format

The shapes a tool can take, the rules it has to follow, and how to write one that gets picked.

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

json
{
  "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

json
{
  "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

json
{ "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.

RuleLimit
NameLetters, digits, _ and -, 1 to 64 characters. Unique within the toolset, ignoring case.
ParametersA JSON Schema object ("type": "object"), at most 64 properties, nested at most 10 levels.
requiredEvery listed name must be a property.
DescriptionUp to 16,384 characters. Past 4,096, only the start is used for matching.
$refLocal references only (#/...). No remote schemas, no cycles.
enumUp to 2,048 values.
Tools per toolset20 on Free, 2,000 on Plan A, 10,000 on Plan S, no limit on S+.
Request body1 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 enum for fixed choices. A value outside the list is never returned.
  • Use format for 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.
Tip

The console's builder checks every rule above as you type, before anything is sent.

PreviousHow it worksNext Matching hints

Something unclear or missing? Write to [email protected] and we'll fix the page.

On this page

  • Accepted shapes
  • Rules
  • Writing tools that get picked