Tool schemas

Tool schemas describe the data an AI agent can send to an operation and the response it should expect in return. Together with the tool name, description and when_to_use guidance, they give the model the contract it needs to call your API without understanding your application’s internal implementation.

Use JSON Schema to represent the same inputs and outputs your API already understands. You do not need to create agent-specific fields or redesign your request objects simply because the caller is an AI model.

Input schema

The input schema describes the arguments available to the agent. These arguments are converted into the request your existing API expects.

{
  "type": "object",
  "properties": {
    "location_id": {
      "type": "string",
      "description": "Location identifier returned by list_locations"
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Booking date in YYYY-MM-DD format"
    },
    "party_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12,
      "description": "Number of people in the booking"
    },
    "seating": {
      "type": "string",
      "enum": ["indoor", "outdoor", "bar"],
      "description": "Preferred seating area"
    }
  },
  "required": [
    "location_id",
    "date",
    "party_size"
  ]
}

Keep the schema aligned with the request shape your API already accepts. Do not add fields such as agent_instruction, llm_context or conversation history unless those values are genuinely part of your application’s API contract.

Output schema

The output schema describes the structure returned by your API. A clear output contract helps the agent understand which values are important and how the result can be used in later operations.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Booking reference"
    },
    "status": {
      "type": "string",
      "enum": ["confirmed", "waitlisted"]
    },
    "date": {
      "type": "string",
      "format": "date"
    },
    "party_size": {
      "type": "integer"
    }
  },
  "required": [
    "id",
    "status"
  ]
}

For example, identifying id as the booking reference tells the agent that the value can be shown to the customer or supplied to another tool such as get_booking. Without that context, the model has to infer the meaning of fields from the raw response.

Design schemas for clear choices

Field names should be understandable without knowledge of your codebase. Prefer names such as location_id, delivery_address and party_size over internal abbreviations that only your engineering team understands.

Descriptions should explain the meaning of a field and, where relevant, where the value comes from. If location_id must be obtained from list_locations, say so in the schema. This helps the agent understand the relationship between tools rather than inventing identifiers.

Use required only for values your API genuinely requires. Making an optional field required can cause the agent to invent a value, while failing to mark a required field can produce requests your API cannot process. Closed sets should use enum, and numerical or formatted values should use constraints such as minimum, maximum and format when those constraints reflect the actual API contract.

Keep schemas aligned with your API

The schema presented to the agent should describe the same contract your backend enforces. A schema that permits values your API rejects creates avoidable failures, while a schema that is more restrictive than your API hides capabilities the customer could otherwise use.

Update your tool schema when the corresponding API contract changes. Treat the schema as part of the public interface of the operation rather than as descriptive metadata that can drift independently from your backend.

If your OpenAPI document already represents these request and response shapes accurately, importing it can provide a useful starting point. You should still review the resulting tool definitions for agent-facing descriptions and usage guidance.

Related