> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mitu.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mitu.ai/_mcp/server.

# 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.

**`input_schema`**

```json title="input_schema"
{
  "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.

**`output_schema`**

```json title="output_schema"
{
  "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

#### [Endpoints](/platform/mcp/endpoints)

Configure the operations represented by your tool schemas.

#### [OpenAPI import](/platform/mcp/open-api-import)

Derive schemas from an API specification you already maintain.