Tool reference

Every tool the Surface Area MCP server exposes, grouped by feature. The proxy discovers tools from your instance at startup, so call tools/list (or ask your agent to list its tools) to see what is available.

In personal access token (PAT) mode every proxied tool takes an extra project_id argument that selects the project; it is optional when you set GATEWAY_PROJECT_ID. In project-key (BasicAuth) mode the project is fixed by your keys, so you omit project_id. The “key inputs” below describe each tool’s own arguments; project_id is added by the proxy in PAT mode. A misspelled argument is refused with the names the tool takes.

Built-in tools

Two tools are defined by the local proxy itself rather than fetched from the backend.

Tool	What it does	Key inputs
`get_context`	Returns the database schema, the available tools, query patterns, and the recommended workflow. Call it first to learn how to use the others.	none
`list_projects`	Lists every project your account can reach, with IDs, names, organizations, and roles. PAT mode only.	none

Connectors and worlds

The connectors feature authors the contract a world answers to and makes a world from it. A connector template is the vendor connection plus the schema; a world is a built, versioned instance of one.

Tool	What it does	Key inputs
`list_connectors`	Lists the connector templates the organization can build worlds from: its own, plus every connector another organization published (`isOwn=false`). Each row carries the head commit’s vendor, base URL, auth scheme, entity and operation counts, and pin digest.	`query`
`get_connector`	Reads one template by slug or repo id: provenance, head-commit summary, and with `includeFiles` the files and the full schema — every entity with its fields, primary key, unique constraints and relationships.	`slug` or `repoId`, `includeFiles`
`get_connector_authoring_skill`	Returns the connector-authoring skill: the file contract, the fidelity shapes, and the definition of done. Read it before validating or publishing.	none
`validate_connector_template`	Compiles a template in the platform’s schema runtime and saves nothing. Answers `valid=true` with the summary, or `valid=false` with the runtime’s reason.	inline `files`
`publish_connector`	Creates a workspace connector, or commits to an existing one, from inline files. The merged tree is compiled first, so a template that cannot make a world is refused and nothing is stored.	`files`, `slug`, `parentCommit`
`clone_connector`	Copies a connector another organization published into this one, recording `clonedFromRepoId` and `clonedFromCommitId`. Later edits by the publisher do not reach the clone.	source slug or repo id
`init_world_from_connector`	Makes a world from a workspace connector’s head commit, pinned by repo, commit and digest. Returns a request id and container id to poll.	connector `slug`, `name`
`create_world`	Creates a world directly: from a shipped template, a `workspace:<slug>` connector, or an inline tree, with an optional overlay and seed rows. A tree the contract refuses is refused here, naming the path.	`slug`, `from`, `overlay`, `data`

publish_connector refuses to land over a moved head when you pass parentCommit, which keeps concurrent agents safe. Validate until it passes, then publish the same files.

A world is stored as its schema tree. One session serves its tools and, when the tree has a connector.toml, its HTTP routes.

World data

The world-data feature puts rows into a world or one of its live sessions, reads rows back out, and exports a session’s calls.

Tool	What it does	Key inputs
`import_world_data`	Loads rows into a world as a new `READY` version. `mode: append` upserts by primary key, `replace` swaps the named entities. Every row is checked against the contract; a refused row names its field and nothing is written.	`slug`, `rows`, `mode`
`request_data_upload`	Starts a bulk import: opens a batch and answers a presigned upload URL and headers per gzipped JSONL chunk.	`slug`, chunk digests
`confirm_data_upload`	Seals an uploaded batch and queues the job that validates every row, applies it onto the world’s snapshot, and publishes a data-only version.	`batchId`
`get_data_batch`	Reads a batch: state, progress, row counts, the first 200 refusals with a report URL for the rest, and the version it produced.	`batchId`
`publish_world_data`	Cuts one data-only version from every batch imported with `publish: later`. Refuses when nothing is pending.	`slug`
`seed_world_session`	Loads rows into a live session only; the world’s versions are untouched. Waits up to 60 seconds for the engine, then returns a call id to poll.	`sessionId`, `rows`, `mode`
`export_world_session`	The session’s call log in order: one record per call with `seq`, `kind`, `tool`, `args`, `result`, `error`, `state` and timestamps.	`sessionId`
`query_world_data`	Reads one entity’s rows at the world’s head through an equality filter, paged. `resolve: true` treats the filter values as plaintext and maps each through the world’s `[redact]` table before matching, so a hashed email is found by its address. `across: true` repeats the query in every linked world whose entity mapping covers a filtered field and answers `groups`, root world first; `compare: true` adds the per-field parity report. Read-only.	`containerId` or `slug`; `entity`; `where`, `resolve`, `limit` (default 100, max 1000), `offset`, `across`, `compare`

where is { "<field>": "<value>" }, and a list of values matches any of them. Omit it for every row of the entity. compare is refused without across, and an unknown entity or field is refused by name.

A real run’s calls, exported with export_world_session, become the rows the next version imports.

Stored world tasks

The world-tasks feature keeps a task — instruction, seed and grader — as a versioned project resource, so one task serves many sessions and their grades are comparable.

Tool	What it does	Key inputs
`create_world_task`	Stores a task at version 1: the instruction, an optional seed laid on the world’s snapshot at open, a grader (assertions over the final state, or a Python verifier) and metadata.	`spec`, `name`, `world`
`update_world_task`	A new `spec` is appended as the next version; `name` and `world` change the record in place. Sessions already open keep their own copy.	`taskId`, and one of `spec`, `name`, `world`
`list_world_tasks`	The project’s stored tasks, newest change first. Filters by the world a task is pinned to and by `spec.metadata` key/value pairs.	`world`, `metadata`, paging
`get_world_task`	One task’s current (or named) version, its world pin, hash, authors, and version history.	`taskId`, `version`
`validate_world_task`	Checks a task against a world version before any session opens: every entity its seed and assertions name must be one the world defines, and the world pin must match.	`taskId`, `world` or `versionId`
`delete_world_task`	Deletes the task and all its versions. Sessions that opened on it keep their copy, so nothing running breaks.	`taskId`
`save_world_session_task`	Promotes a session’s inline task into a stored one at version 1, pinned to the session’s world, and marks the session as running it.	`sessionId`, `name`, `world`

Open a session with gateway worlds session open, the Python client, or POST /api/public/world-sessions, then pass its id to seed_world_session, export_world_session and save_world_session_task.

World sandboxes

The world-sandboxes feature edits a stored world on the platform: open a version, write and run there, check the tree against the push gate, and commit a new version. Each tool is the twin of a gateway worlds sandbox command, and no platform credential enters the sandbox.

Tool	What it does	Key inputs
`open_world_sandbox`	Opens a sandbox on a `READY` version of an existing world, or on a world that does not exist yet, seeded from `custom` or a shipped template. The `gateway` CLI and `sqlite3` are staged inside.	`slug` and `ref`, or `new` and `from`
`get_world_sandbox`	One sandbox’s status: world, base version, open or closed, last commit, `idleExpiresAt` and `closedReason`. Read-only.	`sandboxId`
`read_world_sandbox_file`	Reads one file from the working tree, uncommitted edits included, as base64. Read-only.	`sandboxId`, `path`
`write_world_sandbox_file`	Creates or replaces one file in the working tree from base64 bytes. Nothing is committed until `commit_world_sandbox`.	`sandboxId`, `path`, `contentBase64`
`exec_in_world_sandbox`	Runs one shell command in the world root and returns `exitCode`, `stdout` and `stderr`. A non-zero exit is a normal result. A call first gets the sandbox ready, then waits for the command until 40 seconds have passed in all; a command not done by then answers `running` with an `execId`: call again with it to wait. If getting the sandbox ready took longer than 45 seconds, nothing ran and the call answers `sandbox_exec_deferred`, its `warnings` saying what getting ready found: call again, and it starts at once. If the sandbox lost the command (it ran out of memory or restarted), the call answers `sandbox_exec_lost`: run the command again. If the sandbox could not prepare to run it, the call answers `sandbox_exec_start_failed` and nothing ran.	`sandboxId`, `command`, `cwd`, `timeoutMs`, or `execId`
`check_world_sandbox`	Runs the push gate on the tree without committing: ok or error, the diff against the base, and the paths left out as `ignored`. It names a batch the sandbox is waiting on, and checks against the version a landed one brings. Read-only.	`sandboxId`
`commit_world_sandbox`	Commits the source tree as a new version. A moved branch answers `base_moved`; commit again with `rebase: true` to re-apply your changes onto the tip. When the change migrates the world’s data, the answer is the new version, or a `batchId` to follow with `get_data_batch` if the migration is still running.	`sandboxId`, `message`, `branch`, `rebase`
`import_world_sandbox_data`	Imports a rows file already in the sandbox tree into the platform world as a data-only version. A commit never carries data, so rows go through this tool.	`sandboxId`, `path`, `entity`, `mode`, `dryRun`
`close_world_sandbox`	Closes the sandbox and releases its workspace. Refused with `sandbox_uncommitted` while the tree holds uncommitted changes, unless you pass `force`.	`sandboxId`, `force`

To find a sandbox you left open, run gateway worlds sandbox list.

Dashboards

The dashboards feature reads and writes a design dashboard’s code: TypeScript render files, an entrypoint and an optional transform. Each tool is the twin of a gateway dashboards command; the same checks as the Design Agent run on every push.

Tool	What it does	Key inputs
`list_dashboards`	The project’s dashboards, newest first, with kind and app URL. Read-only.	`limit`
`create_dashboard`	Creates a dashboard, from starter code unless `template: "empty"`, and answers its code.	`name`, `taskSetId` or `environmentId`, `template`
`pull_dashboard`	The code and the `stamp` to send back on push. Read-only.	`dashboardId`
`push_dashboard`	Replaces the render files and transform in one write. Refused, writing nothing, when the code does not compile or the dashboard changed since `baseStamp`.	`dashboardId`, `files`, `entrypoint`, `transform`, `baseStamp`, `dryRun`
`test_dashboard_transform`	Runs a transform on a real session and answers its output and shape. Nothing is saved.	`dashboardId`, `transform`, `sessionId`
`preview_dashboard`	Renders the saved dashboard on real data: whether it rendered, the error, the app URL. Read-only.	`dashboardId`, `sessionId`, `taskSetId`, `taskId`

Trace exploration

The agent-tools feature exposes read tools for analyzing traces, sessions, scores, and project statistics. It is always registered.

Tool	What it does	Key inputs
`guide`	Returns detailed help on a topic. Ask for `connectors` or `world-data` for the world-building walkthroughs.	`topic` (default `overview`)
`describe_project`	One-call statistical overview: row counts, score configs and aggregates, observation types, session counts, models, tags, and the time range.	none
`get_trace`	Fetches up to 10 traces with their observations and scores, paginated. Input and output are cut at 15000 characters. An ID the project does not hold is listed in `notFound`.	`traceIds` (array), `observationOffset`, `observationLimit`
`get_session`	Fetches up to 5 sessions with their trace summaries, paginated. An ID the project does not hold is listed in `notFound`.	`sessionIds` (array)
`get_observations`	Fetches up to 20 observations by ID. Input and output come in a window of `ioLimit` characters (default 15000, at most 100000) from `ioOffset`, with each field’s full length, so a long field can be read whole.	`observationIds` (array), `ioOffset`, `ioLimit`
`diff_traces`	Compares two traces side by side.	two trace IDs
`trace_stats`	Rolls up cost and latency grouped by trace name, with p50 and p95 latency.	optional time window
`execute_query`	Runs read-only ClickHouse SQL. Pass `sql` for a single query (`query` is accepted as an alias), or `queries` for up to 10 named queries run in parallel.	`sql` (string) or `queries` (array of `{ id, sql }`); `offset`, `limit` for single mode
`search_gateways`	Semantic vector search over score reasoning and comments.	`query` (string)

execute_query is read-only and accepts SELECT statements only. Provide either sql or queries, never both.

Context hub

The context-hub feature gives read-only access to your prompts, skills, memories, and agent definitions — the versioned items an execution can be traced back to. It is always registered.

Tool	What it does	Key inputs
`search_context`	Searches the context hub by kind and query, returns item summaries with their IDs and handles.	`query`, `kind` (`prompt`/`skill`/`memory`/`agent`), `limit`, `offset`
`get_context_item`	Reads an item’s files at the latest version, or at a specific version by short commit hash. Large files are truncated.	`identifier` (handle or ID), `version` (optional)

Environments and task sets

The environments feature lets an agent author, run, and analyze benchmark environments end-to-end. It is registered only in environment-kind projects, so these tools appear in tools/list only when your project is an environment.

An environment is a versioned benchmark container — a bundle of code plus tasks that you run models against and score.
A task set is a kind='tasks' dataset whose items are individual tasks. Tasks are versioned and attributed, exactly like dataset items.
A rollout is one model’s attempt at one task. Every rollout is stored as a Surface Area session, so you can open its full trace.

Read

Tool	What it does	Key inputs
`list_environments`	Lists the environments (benchmark containers) in the project, each with its latest version: the head of your `main`.	none
`get_environment`	Full detail for one environment: slug, name, linked task set, evaluation count, `main` (the version an unpinned run uses), the version history (content hash, semver, author, change reason, provenance, `envKind`, and the edit session each version was written in), and the entities of `main` with their field names.	`containerId`
`list_task_sets`	Lists the project’s task sets with each one’s task count and linked environment, if any.	none
`get_task_set`	One task set’s full hub in a single call: dataset meta, the linked environment, its tasks, that environment’s evaluations, and the set’s runs (set runs and single task runs, as the Runs tab shows them).	`datasetId`
`get_set_run`	One set run: its tasks, each task’s checks and result, progress and score.	`setRunId`
`list_rollouts`	Lists the evaluations run against an environment, newest first, with model, status, aggregate metrics, cost, and the pinned version.	`containerId`, `limit`
`get_rollout_samples`	Per-sample detail for one evaluation: `exampleId`, `rolloutIndex` (for pass@k / variance), `reward`/`score`/`correct` (each nullable — nulls stay null, never coerced to 0), the named sub-reward breakdown, and `info` (which may carry a `sessionId`/`traceId` to drill into the trace).	`evaluationId`, `limit`
`get_task_performance`	Per-task performance across all evaluations, worst-first: sample counts, average reward, pass rate, reward stddev, null-score count, and a per-version breakdown so regressions between pushes are visible.	`containerId`
`get_task_distribution`	Reward distributions: a `[0,1]` 10-bucket histogram with an explicit null bucket, the per-task difficulty list, and named sub-reward averages.	`containerId`

Write

Tool	What it does	Key inputs
`create_task_set`	Creates a `kind='tasks'` dataset to hold tasks and returns its `datasetId`.	`name`, `description`
`link_task_set`	Attaches a task set to an environment, or detaches it with `datasetId: null`. The link powers per-task performance and task-scoped runs.	`containerId`, `datasetId`
`create_task`	Adds a task to a task set. The task becomes visible on the task-set page and is included in runs; it is attributed to you (PAT auth) or your API key, and versioned.	`datasetId`, `name`, `prompt`, `expectedOutput`, `metadata`
`update_task`	Edits a task, creating a new attributed version (the old version is preserved). Only the fields you pass change.	`datasetId`, `taskId`, `prompt`, `expectedOutput`, `changeReason` (required)
`create_environment_version`	Authors a new environment version by editing one existing file in the current READY version. The bundle is re-tarred and content-hashed; an identical edit dedups to the existing version.	`containerId`, `filePath`, `newContent`, `changeReason`
`run_evaluation`	Runs an evaluation: dispatches one hosted-runner job per model against a READY version; results commit back as an evaluation.	`runConfigId` or `models` (array); `versionId`, `limit`, `rolloutsPerExample`

The full off-platform lifecycle is create_task_set → create_task (repeat) → link_task_set → run_evaluation → poll list_rollouts / get_rollout_samples → update_task / create_environment_version to iterate. Every tool mirrors the Task Sets and Environment pages in the dashboard one to one.

Environment Agent

The Environment Agent is a background analysis agent — one per project — that reads per-task performance, checks reward distributions, and can auto-heal tasks by authoring a new environment version. You can chat with it in the Agent Console or let it run on a schedule or after every evaluation.

Tool	What it does	Key inputs
`get_environment_agent`	Returns the project’s Environment Agent config (enabled, cron schedule, post-eval analysis, auto-heal, prompt, model) and its recent runs, or `null` if none is saved.	`limit`
`configure_environment_agent`	Creates or replaces the whole config and registers/unregisters the cron schedule to match. Read `get_environment_agent` first if unsure.	`enabled`, `cronExpression`, `postEvalAnalysis`, `autoHeal`, `prompt`, `model`
`trigger_environment_agent`	Queues a manual analysis run now (requires a saved config) and returns a `runId`; a durable worker analyzes performance and distributions in the background.	none

Console parity: everything the in-app agent can do

Twenty further tools ship with the same environments feature, so they appear under the same environment-project gating. They mount the in-app Environment Agent’s own surface: the same factory, the same handlers, the same durable staging. Every tool in the five tables below also accepts an optional containerId (an id from list_environments). Pass it whenever the project owns more than one environment; omit it when the project owns one. Staged edits are keyed to your API key and the environment, and they persist in the database. A file staged in one call is still staged on the next call, from any process.

Stage file edits, then land them

Edits go into a workspace first. Nothing reaches a version until you commit or propose, so batch every file of one coherent change before landing it.

Tool	What it does	Key inputs
`env_write_file`	Stages a write: the complete new content replaces the file, or creates it at a new relative path. Content is the whole file, never a diff.	`path`, `newContent`
`env_delete_file`	Stages a deletion. The path must exist in the current workspace view.	`path`
`env_diff`	Shows the pending changeset as per-file unified diffs against the base version. Read it before committing or proposing.	none
`env_commit`	Commits everything staged as one new READY version, authored by you. Refuses when the environment advanced since you last read it, unless you pass `acknowledgeDivergence`.	`changeReason` (required, up to 1000 characters), `acknowledgeDivergence`, `branch` (default `main`)
`env_propose`	Records the staged changeset as one reviewable change proposal — a pull request to the environment — with full per-file diffs. No version is authored, and staging is cleared afterwards.	`title` (required, up to 160 characters), `changeReason` (required, up to 2000 characters), `targetBranch` (default `main`)
`propose_task_fix`	Commits a single-file create-or-replace edit directly as a new version, skipping the workspace. The same path the background agent’s auto-heal takes.	`path`, `newContent`, `changeReason` (required)

env_commit refuses to land over a version the workspace never saw, which keeps concurrent agents safe. Read env_diff, rebase your edits, and commit again — or pass acknowledgeDivergence: true to fork deliberately.

Review the proposals other agents file

Proposals are also reviewed from here: the apply and dismiss verbs are part of the same tool set.

Tool	What it does	Key inputs
`env_list_proposals`	Lists the environment’s change proposals, open ones first, then recent applied and dismissed history.	`status` (`open`, `applied`, `dismissed`, `all`; default `all`), `limit` (default 20)
`env_get_proposal`	Reads one proposal with a per-file unified diff against the version it was staged on.	`id`
`env_apply_proposal`	Applies an open proposal as a new READY version. The changeset rebases onto the container’s current head, so a proposal stays applicable after other commits. Deletes of already-gone paths are no-ops.	`id`, `force`
`env_dismiss_proposal`	Dismisses an open proposal without applying it. The proposal and its changes stay readable as history.	`id`

env_apply_proposal refuses when the proposal would overwrite concurrent changes and names the conflicting files. Pass force: true to take the proposal’s side.

Check a version actually runs

A bundle can parse and still be unrunnable. Both tools below block and return the result, so call each once rather than polling.

Tool	What it does	Key inputs
`env_run_tests`	Runs the environment against a few of its own tasks and waits up to four minutes for the per-task rewards. Omit `model` and the platform picks a cheap compatible one from what the project holds. Dispatches through the same path as the Run button.	`model` (a `provider/model` id), `numExamples` (default 5, max 10)
`env_get_run`	Waits for and reads a run started by `env_run_tests`: status plus per-task reward and verifier scores. Call it only when `env_run_tests` reported `settled: false`.	`runId`, `waitSeconds` (default 180, max 240; `0` reads immediately)

env_run_tests dispatches a real hosted run. A null reward means the verifier graded nothing — a failure to fix, not a pass.

Read a version’s files, reports, and evals

Tool	What it does	Key inputs
`list_task_files`	Every file in a version, with path, size and sha256, plus a `taskFiles` subset highlighting the task-shaped ones. Defaults to the newest READY version.	`versionId`
`get_task_file`	One file’s content from a version’s source bundle.	`path`, `versionId`
`get_agent_reports`	Recent Environment Agent runs, newest first: status, summary, the full findings report, any version a run authored, what triggered it, and timestamps.	`limit` (default 10, max 50)
`list_environment_evals`	The registry of evals the project’s environments run, derived from evaluation results and enriched from the source: key, kind, run and sample counts, mean (null rewards counted separately, never coerced to 0), per-version stats, and any pass threshold.	none
`get_environment_eval`	One derived eval: its stats, its source snippet (the `@vf.reward` function or `verifiers/*.sql` body), and its per-version results series.	`containerId`, `key`

Environment evals are defined in environment code. To change one, edit the source with env_write_file and land it with env_commit or env_propose.

Schedule analysis and runs

Scheduled work executes in the worker and survives the session closing.

Tool	What it does	Key inputs
`trigger_environment_analysis`	Queues a manual Environment Agent analysis run against a named environment, and returns a `runId`. The container-pinned twin of `trigger_environment_agent`. Requires a saved config.	none beyond `containerId`
`schedule_environment_work`	Schedules work for later: `delayMinutes` queues one background run that far out, `cronExpression` sets a recurring schedule. `task` is the woken run’s only briefing, so be concrete. Read results with `get_agent_reports`.	`task` (required, up to 2000 characters), `delayMinutes` (1 to 10080), `cronExpression` (5 or 6 fields), `clearSchedule`
`create_run_schedule`	Creates a recurring graded run through the same scheduler as Runs → Configs. `LATEST_READY` resolves the newest ready build each firing; `PINNED_BUILD` always runs one immutable version.	`cronExpression` (required), `pinMode` (`LATEST_READY` or `PINNED_BUILD`, required), `runConfigId`, `versionId`

Every firing of a create_run_schedule schedule dispatches one run per model in the chosen run config. Confirm the environment, cadence, config, models and pin mode with a person before calling it. runConfigId may be omitted only when the project has exactly one schedulable config, and versionId is required for PINNED_BUILD and refused for LATEST_READY.

Prompt management

The prompts feature adds six tools for managing prompt versions.

Tool	What it does
`getPrompt`	Fetches a prompt by name, label, or version with all composition dependencies resolved.
`getPromptUnresolved`	Fetches a prompt with its dependency tags left intact, for analyzing composition.
`listPrompts`	Lists and filters prompts with pagination.
`createTextPrompt`	Creates a new text-prompt version.
`createChatPrompt`	Creates a new chat-prompt version.
`updatePromptLabels`	Updates the labels on a prompt version.

Features register by project kind, and a deployment can add modules of its own. tools/list is the authority on the tools your instance answers to.

Next steps

Setup — install the client and connect it to your MCP client.
Getting started with worlds — the same workflow end to end, with each step’s MCP twin named.
The gateway CLI — the terminal twin of most of the tools above.

CLI

Python SDK

TypeScript SDK

SDK Reference

REST API

MCP Server

Built-in tools

Connectors and worlds

World data

Stored world tasks

World sandboxes

Dashboards

Trace exploration

Context hub

Environments and task sets

Read

Write

Environment Agent

Console parity: everything the in-app agent can do

Stage file edits, then land them

Review the proposals other agents file

Check a version actually runs

Read a version’s files, reports, and evals

Schedule analysis and runs

Prompt management

Next steps

​Built-in tools

​Connectors and worlds

​World data

​Stored world tasks

​World sandboxes

​Dashboards

​Trace exploration

​Context hub

​Environments and task sets

​Read

​Write

​Environment Agent

​Console parity: everything the in-app agent can do

​Stage file edits, then land them

​Review the proposals other agents file

​Check a version actually runs

​Read a version’s files, reports, and evals

​Schedule analysis and runs

​Prompt management

​Next steps

Built-in tools

Connectors and worlds

World data

Stored world tasks

World sandboxes

Dashboards

Trace exploration

Context hub

Environments and task sets

Read

Write

Environment Agent

Console parity: everything the in-app agent can do

Stage file edits, then land them

Review the proposals other agents file

Check a version actually runs

Read a version’s files, reports, and evals

Schedule analysis and runs

Prompt management

Next steps