> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AX MCP Conventions

> Shared rules every Arize AX MCP tool follows: pagination and limits, rate limits, search tools, errors, timeouts, and tool annotations.

A few rules apply across every tool in the [catalog](/docs/api-clients/mcp/tool-catalog.md), not just one. The server runs as stateless Streamable HTTP, so there are no sessions to manage between calls.

## Pagination

Most `list` tools take the same two arguments:

| Argument | Type | Default | Description |
| - | - | - | - |
| `limit` | int | 50 | Items to return, between 1 and 100 |
| `cursor` | string | none | Pagination cursor from a previous response |

Each response carries a `pagination` object:

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "pagination": {
    "has_more": true,
    "next_cursor": "<opaque-cursor-string>"
  }
}
```

When `has_more` is `true`, pass `next_cursor` back in as the next call's `cursor`. Agents pick this up on their own once they see a first response, though it's worth telling yours to stop after a page or two when you only need a sample rather than the full set.

### Limits that differ

| Tool | Limit |
| - | - |
| `list_traces` | Default 25, maximum 50 |
| `list_annotation_queue_records` | Maximum 500 |
| `list_spans` | The server clamps `limit` to 100, even if you ask for more |
| `*_tags`, `search_*`, `list_evaluator_templates` | No `limit` argument |

Span payloads are large enough to fill a context window on their own. Point your agent at a specific trace when you're debugging rather than paging through a busy project's full span list.

## Search and span tools

`search_dataset_examples` and `search_experiment_runs` send a `POST` request with the filter in the request body. If you omit the filter, they return everything, so ask your agent to filter first on large datasets.

`list_spans` and `list_traces` also take a `POST` body. `list_spans` requires `project_id`.

## Rate limits

The REST API applies rate limits, and MCP tool calls count against them. Limits apply per user, so all of a user's API keys share one bucket. Each endpoint is tracked separately, on a fixed one-minute window.

* The default is 100 requests per minute.
* `POST /v2/spans` (the `list_spans` tool), `DELETE /v2/spans`, and the annotate endpoints are limited to 10 requests per minute.

When you exceed a limit, the API returns `429 Too Many Requests` with a `Retry-After` header that holds the seconds left in the window. See [rate limits](/docs/ax/rest-reference/overview.md#rate-limits) in the REST API reference for the full table of endpoint-specific limits.

## Timeouts

Requests to the REST API time out after 30 seconds.

## Errors

Two kinds of errors can reach your agent.

The MCP server itself returns a tool error when the input does not match the tool's schema or when the request carries no valid credential.

Failures from the REST API come back in [RFC 9457 problem format](/docs/ax/rest-reference/errors.md): a JSON body with `type`, `title`, `status`, and `detail` fields. Most agents read and explain these rather than retry blindly. Two cases carry extra detail:

* A `403` can mean your plan does not include a feature or has reached a limit. The body includes `entitlement` or `limit` and `current_count`, along with `required_plan`, which names the plan that unlocks the feature or raises the limit.
* A `429` means you hit a rate limit. Wait for the number of seconds in `Retry-After`.

## Tool annotations

Every tool declares annotations that MCP clients can use to decide when to ask for approval. They are hints, and the server does not enforce them.

| Annotation | Meaning |
| - | - |
| `readOnlyHint` | The tool does not change anything |
| `destructiveHint` | The tool can change or delete existing data |
| `idempotentHint` | Calling the tool again with the same arguments has no further effect |
| `openWorldHint` | The tool talks to an external system. This is `true` for every REST-backed tool. |

Of the 93 tools generated from REST operations:

* 45 are read-only.
* 15 create or insert data and are not marked destructive (the `create_*` and `insert_*` tools).
* 33 are marked destructive: every `update_*` and `delete_*` tool, the `annotate_*` and `assign_*` tools, `trigger_task_run`, `cancel_task_run`, and the prompt label tools `set_prompt_version_label` and `delete_prompt_version_label`.

`server_info` is read-only and not open-world. Because the annotations are only hints, check your client's approval settings. See [safety and permissions](/docs/api-clients/mcp/overview.md#safety-and-permissions).

## Next steps

> [card] [Tool catalog](/docs/api-clients/mcp/tool-catalog.md)
>
> Every tool, grouped by resource.

> [card] [Connect your client](/docs/api-clients/mcp/connect.md)
>
> Per-client setup for Claude Code, Cursor, Claude Desktop, Codex, and others.