Skip to main content
A few rules apply across every tool in the catalog, 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: Each response carries a pagination object:
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

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

​
Next steps

Tool catalog

Every tool, grouped by resource.

Connect your client

Per-client setup for Claude Code, Cursor, Claude Desktop, Codex, and others.