MCP tools

The MCP server mirrors the CLI nouns: same ids, same vocabulary. Org-scoped tools use the current MCP org (see mcp_org tools) unless you pass an org_id override. Arguments marked required must be supplied; everything else is optional.

Experiment tools

experiment_list filters with search, owner, agents, models, products, environments, updated_since (RFC 3339), and limit. Same-axis values OR; different axes AND.

experiment_view includes a resources array (id, title, url, createdAt, updatedAt). Empty is []. Resources hang off the experiment, not a version, and are not in YAML. Tool arguments are snake_case (experiment_id, resource_id); structured results use the same lowerCamelCase JSON as the HTTP API.

experiment_resource_add takes required experiment_id plus either one title and url, or a resources array of {title, url}. Do not send both shapes. Title and URL are both required on each item. http:// or https:// only; same title or URL twice is allowed.

experiment_resource_edit takes required experiment_id and resource_id (UUID from experiment_view) plus at least one of title or url. experiment_resource_delete takes required experiment_id and resource_id. A missing resource is an error, not a silent success.

experiment_push takes required experiment_yaml. An experiment that declares required dependencies (files:, setup.files, setup.skills, or tests[*].files entries with a source) needs its complete package to become a runnable version — ax experiment push resolves and uploads those files for you. A YAML-only call is only accepted when it matches the YAML of an existing stored version (an idempotent re-push); otherwise it fails rather than registering an incomplete version. A caller that has already staged each dependency's content-addressed blob for this org can supply the package directly with replace_version_files: true and version_files (dest, tar_sha256, size_bytes, source, and optionally variant_id, test_names, name) — the same fields the API's JSON push body accepts.

experiment_fork takes required experiment_id plus optional new_experiment_id (kebab-case; derived as <experiment_id>-v2 when omitted, with a counter appended when that id is taken) and new_name (derived as the source name followed by (V2)). It registers the source's latest stored definition and dependencies as a new experiment on the current results pipeline (session_data_v1) and creates no runs. The source experiment is only read. Use it when an experiment's results are held in the retired data pipeline and you want to run the same definition again, then pass the returned experimentId to experiment_run.

experiment_run accepts version, repeat, exact variant_ids, the axis selectors (prompt_ids, agents, models, product_ids, environment_ids), registered flags, mock, and setup_only. A setup_only submit runs one sandbox per distinct setup unless all_variants is set, the same as ax experiment run --setup-only. Selectors are a union; no selector runs every variant. The response pins the version and returns its fingerprint, ordinal, selected variant ids, and the run request id.

experiment_query takes required experiment_id plus either raw sql (scoped to the experiment) or the experimental modeled fields (metrics, ordered group_by, stat (only mean today), dimension filters, version, and dimensions discovery; the surface may change). Both modes support limit (default 100, cap 10,000), dry_run, and save ({heading, slug?, description?, labels?, force?}); dry_run, save, and dimension discovery are mutually exclusive. Metrics are testPassRate, testsPassed, testsFailed, cost, wallClockTime, tokens, toolCalls, toolFailures. Both modes leave out runs classified as "test aware" (the agent noticed it was being tested) unless include_test_aware is set; those runs may not mimic real-world agent behavior. The modeled result reports how many were held back as excludedTestAwareRuns.

Run tools

run_list accepts experiment_id, version_scope, the dimension filters, exact variant_ids, statuses, created_by_ids, status_updated_since (when the run entered its current status, not creation), test_aware (only runs classified as "test aware", where the agent noticed it was being tested or changed its behavior because of it), run_request_id (only the runs of one submission), and limit.

run_view takes a request id or composite run id. Set tests: true for every captured test, or test_name for one test's exit code, duration, and output tails (composite run ids only; not both). For a transcript, select one composite run with transcript: true. Pass include: ["reasoning"] to add reasoning and limit to change the 500-turn default (minimum 1, maximum 10,000). Transcript and test payloads cannot be combined.

Set setup_log: true with one composite run id for the run's setup.log (the tail when it exceeds the size cap) and its setup-check results, the same as ax run view --setup-log. The structured result carries found, content, truncated, totalSizeBytes, maxBytes, and setupChecks. setup_log cannot be combined with tests, test_name, or transcript.

The transcript object matches CLI JSON. Its ordered turns contain seq, nullable ts, role, nullable origin (human or harness on user turns), kind, and text; include_reasoning, limit, truncated, shown, total, and skipped_malformed describe completeness.

A composite run's run_view result also lists its failed tool calls, with or without a transcript. The run's failedToolCalls array (up to 50 calls, with failedToolCallsTruncated set when there were more) gives each call's seq, position, tool_name, error_text (the joined error content with likely secrets redacted, shown as [redacted], cut to at most 2,000 Unicode code points; error_truncated says when the redacted text was cut, and error_chars is the length in Unicode code points of the redacted error text, before the cut), and the summary text lists them. With a transcript, each listed failed call also appears as a tool_error turn carrying the same tool_call object. When failedToolCallsTruncated is set, query every failed call with run_query (pass limit: 10000, since the default is 100): SELECT seq, tool_name, payload FROM tool_interactions WHERE is_error ORDER BY seq.

run_query takes required composite run_id plus sql or tables, and limit, dry_run, and save with the same semantics as experiment_query.

Pass tables to run_query or experiment_query to discover what raw sql can read, the same as ax run query <RUN_ID> sql --tables and ax experiment query <EXPERIMENT_ID> --table on the CLI: "" lists the tables, and a table name returns its columns, types, join keys, and allowed values. run_query also reports each table's row count. The structured result carries the same fields as the CLI's JSON output, in the tools' lowerCamelCase JSON. tables cannot be combined with sql, limit, dry_run, save, or the modeled fields.

Insight tools

insight_create takes required heading and sql, plus slug, description, labels, and force (overwrite mutable content on slug collision; slugs are immutable). insight_view executes live unless sql_only: true. insight_edit is presence-aware: an empty description or labels array clears the field (clear_labels also works).

Set experiment on insight_list to discover its three built-in Results charts.

Report tools

report_get, report_edit, report_append_blocks and report_delete take required report_id. report_create takes required title plus description and body_markdown. report_edit takes required expected_updated_at, the updatedAt you last read, and is presence-aware: title, description and body_markdown change only when sent, and an empty description or body_markdown clears the field. A report changed since the stamp refuses the write; read it again and retry. report_append_blocks takes required markdown and an optional expected_updated_at.

The report_append_blocks description states the document format and carries the JSON Schema for every ax-block kind, so an agent can build a valid fence without another lookup. Results use the same lowerCamelCase JSON as the HTTP API. For chart insights, insight_view with sql_only: true returns the parameter schema, response schema, and available filter values as parameterSchema, responseSchema, and availableValues inside insight.

Execute with a parameters object, for example {"ref":"<INSIGHT_REF>","parameters":{"group_by":"model","metric":"wallSeconds"}}. Chart results are in chartData; saved SQL results remain in rows. To retrieve points or underlying runs, set result_view to points or runs, then pass chartData.nextCursor as cursor until it is null. Keep the same parameters and view for every page. Use group_value and test_name for an exact heatmap cell. Omit limit for chart insights; summaries always cover all matching runs.

See CLI insight usage for filter and pagination examples.

Secret tools

Org context and CLI auth

Context tools

context_objects, context_list, context_get, and context_documents accept scope: "org" (default) or "global". Object discovery is the source of truth for object types, allowed filters, ordering, and the relationships context_get embeds one level deep. Relationship tables are not object types and cannot be listed; their rows appear only as embedded arrays. Document hosts are companies, products, use-cases, personas, agents, persona-agents, interfaces, capabilities, user-flows, product-categories, product-packages, product-versions, product-competitors, agent-versions, and models. The companies type holds Company Context objects (companies, customers, vendors, and competitors), shown as Companies in the platform.

context_edit is organization-only. Its actions are read, options, preview-delete, mutate, mutate-many, flow-steps, and document upload actions. models, agent-versions, user-flow-steps, and user-flow-step-capabilities are read-only through this editor. context_copy accepts only global companies, products, use cases, personas, and agents, and carries their published tags into the organization library (reusing tags matched by origin or name, creating the rest, and keeping local edits); a name collision with a different organization tag fails the whole copy with a message naming both tags. context_claim can check companies, products, agents, personas, use cases, or documents; ownership writes are limited to companies, products, and agents for organization admins.

context_tags takes one action: targets, list, get, create, update, delete, assign, unassign, usage, or assigned (the tags one object carries, by kind and target_id), with snake_case fields (tag_id, target_id, kind, name, color, patch, expected_updated_at, expected_usage_count, search, after, limit, include_usage, scope). Organization tags and their assignments are editable; scope: "global" reads the shared library and refuses writes, and shared objects take tag changes through the tags action of context_suggestions instead of assign. create returns the existing tag with created: false when the name is taken, and assign and unassign are idempotent, so retries are safe. update requires the tag's current updatedAt as expected_updated_at, and delete requires the count from usage as expected_usage_count once a tag is in use; when the count moved, the error message names the current count to confirm with. usage items carry parentKind and parentId for nested objects such as an interface under its product. context_list narrows taggable types to objects carrying any of the tags in filters.tags (comma-separated tag ids), alongside its column filters.

context_follow and context_follow_state act on global companies, products, use cases, personas, and agents. They change or read only the authenticated person's own follow state and never list other followers; org_id only selects the organization whose feature rollout applies.

context_suggestions takes input, the same JSON action used by ax context suggest, and optional org_id. Actions are snapshot, submit, tags, list, and withdraw. tags proposes shared-tag changes for any taggable shared object: {"action":"tags","op":"snapshot","kind","targetId"} returns the published tags plus the shared library, and {"action":"tags","op":"submit","kind","targetId","add","remove","reason","idempotencyKey"} files the proposal. It never edits shared Context directly and cannot approve or deny a suggestion. list and withdraw only access the authenticated user's own suggestions; list takes requestKind (suggestion or tag_assignment) to return one kind. Reuse a submission's idempotencyKey only when retrying that same submission.

Notification tools

Both act only on the authenticated person's feed in the current MCP org. notification_feed takes page_size (at most 100), cursor (the previous result's next_cursor), and unread_only. Each entry is one changed object with a stable event_id. notification_feed_mark_read takes 1 to 100 event_ids and returns marked_count; already-read or unknown ids are ignored, so repeating it is safe. The same routes are /api/v1/notifications.

Legacy tools

Kept for compatibility; prefer experiment_query, run_query, and insight_* for new agent workflows.

Not in MCP

Local authoring (ax experiment create / validate / schema / variants) and resolving local files into a package stay CLI-side — experiment_push accepts an already-staged package by reference (see above) but never reads from or uploads a caller's local disk. experiment_run can run registered experiments with files: after ax experiment push has stored their dependencies. There is no watch tool (poll run_view with the request id), and insight export is a client-side CLI operation; agents can consume the structured rows the query and insight tools return.