# MCP tool schemas

Expose each assigned service as one MCP tool with a schema derived from its input and output.

Each service assigned to an [MCP gateway](https://zato.io/docs/ai/mcp/index.html) becomes one tool, and everything an AI agent learns about it through `tools/list` comes from the service itself - there is no separate tool definition to write or keep in sync.

| Tool element | Where it comes from |
| --- | --- |
| `name` | The service's name, e.g. `billing.get-invoice` |
| `description` | The service's docstring - this is what the agent's model reads when deciding which tool to call, so write docstrings for the model as much as for colleagues |
| `inputSchema` | Generated from the service's declared input |

## Input schema generation {#input-schema-generation}

Both I/O styles produce the same JSON Schema. With plain declarations, each element maps to its JSON Schema type - `Int` becomes `integer`, `Bool` becomes `boolean`, `Float` becomes `number`, `Dict` becomes `object`, `List` becomes `array`, `Date`, `DateTime` and `UUID` become strings with their `format`, and text-like elements become strings:

```python
class GetInvoice(Service):
    """ Returns one invoice by its ID, optionally with line items.
    """
    input = 'invoice_id', '-include_items'
```

With dataclass models, each field's Python annotation maps to its JSON Schema type - `str`, `int`, `float`, `bool`, `list[T]` with its element type, `dict`, dates, `Decimal`, `UUID` - and nested dataclasses recurse into nested object schemas. A field is required unless it has a default or its type is optional, and required names are listed in the schema's `required` list. In plain declarations the `-` prefix marks an element optional.

When [argument validation](https://zato.io/docs/ai/mcp/argument-validation.html) is on, it enforces the generated schema itself, so the schema agents see and the schema calls are checked against are always the same one.

A service with no declared input produces a schema that accepts any arguments.

## Exposed services {#exposed-services}

- Only services assigned to the gateway appear - the **Services** picker on the wizard's step 01 lists what can be assigned.
- Internal services - names starting with `zato.` - are never exposed, regardless of the assignment. The picker does not offer them, and the runtime refuses them even if configuration were to name them. The picker does not offer services starting with `pub.zato.` either.
- Tools are listed in a deterministic alphabetical order, so clients can cache the list.

## Live updates {#live-updates}

Hot-deploying a changed service rebuilds the tool list of every gateway that exposes it - the next `tools/list` already advertises the schemas the redeployed code declares, with no restarts. Editing the gateway itself also rebuilds its registry without a restart.

The **Export** document described under [sharing a gateway with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) uses the same schema generation.

## See also {#see-also}

- [Argument validation](https://zato.io/docs/ai/mcp/argument-validation.html) - Checks tools/call arguments against the same generated schema
- [Sharing with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) - Exports the tool list with its schemas as one server.json document
- [MCP gateways](https://zato.io/docs/ai/mcp/index.html) - Configuration, endpoint behavior and the governance controls
- [Tool selection](https://zato.io/docs/ai/examples/tool-selection.html) - Docstrings and schemas that steer agents to the right tool

## Learn more {#learn-more}

- [MCP tutorial](https://zato.io/tutorials/mcp/01.html) - Expose Python services as AI tools and connect Claude Code in minutes
- [AI Integrations overview](https://zato.io/docs/ai/) - Both directions of AI traffic in one platform, and where to start
- [MCP gateway reference](https://zato.io/docs/ai/mcp/) - Configuration, endpoint behavior and the governance controls
- [MCP gateway security](https://zato.io/docs/ai/mcp/security.html) - API keys, Basic Auth and bearer tokens for AI agents
- [MCP response controls](https://zato.io/docs/ai/mcp/response-controls.html) - PII removal, prompt-injection safeguards and token-denominated size caps
- [MCP audit log](https://zato.io/docs/ai/mcp/audit-log.html) - What each agent did, when and with what outcome - payloads never recorded
- [MCP alerts](https://zato.io/docs/ai/mcp/alerts.html) - Failing backends, agents stuck in a loop and gateways with too many tools
- [Cost and limits](https://zato.io/docs/ai/cost-and-limits.html) - Every setting that caps AI cost and traffic, with worked examples
- [GitOps for AI integrations](https://zato.io/docs/ai/enmasse.html) - LLM connections and MCP gateways as YAML in version control
- [AI examples](https://zato.io/docs/ai/examples/) - Complete, runnable scenarios - one real-world need per file