Roe

Permanently delete an agent and all its versions. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. The agent and its run history are removed; in-flight async jobs may continue but their results become unrecoverable. Returns `{agent_id, deleted: true}` on success.

Delete one version of an agent. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Deleting the agent's CURRENT version is allowed and does NOT fail: the backend silently promotes the next-newest remaining version to current, so the agent immediately starts serving a different config — re-check `get_current_agent_version` afterwards. The one refusal is the agent's ONLY version (400); delete the whole agent with `delete_agent` instead. This is NOT a rollback tool — to go back to an older config, re-submit that config with `create_agent_version`. Returns `{agent_id, version_id, deleted: true}` on success.

Permanently delete one saved connection and its stored credentials. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Use `list_connections` first to confirm the id and name. Returns `{connection_id, deleted: true}` on success.

Permanently delete a policy and all its versions. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. The policy and its version history are removed; any agent currently referencing this policy will see its lookups start failing. Returns `{policy_id, deleted: true}` on success.

Permanently delete a skill set and all its versions after explicit user confirmation. Returns a conflict when agents still reference the set; update those agents first.

Permanently delete one Roe table in the caller's organization. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation. Drops the underlying table and removes table-link metadata such as project table links and dataset table sync rows.

Describe one Roe table in the caller's organization without reading rows. Returns column metadata, the total row count when ClickHouse can determine it cheaply, and the latest metadata-modification timestamp (`updated_at`) when available. Use after `list_tables` to inspect a table's schema and size before previewing or querying it.

Download a resource referenced by an async job's output (e.g. a small text/JSON artifact emitted by the agent). Returns `{job_id, resource_id, byte_count, encoding: "base64", content_base64}`. Use this ONLY for small text-like references (≤~190 KiB raw, ~256 KiB base64). For large binaries — PDFs, images, audio, video — do NOT use this tool: the base64 inflation will trip the MCP response size cap and return a truncation envelope instead. Prefer reading the `trace_url` field from `get_agent_job_result` and showing the user a link they can open in a browser. Set `as_attachment=true` if you want the backend to include a `Content-Disposition: attachment` hint (does not affect the bytes returned — useful only if a downstream tool consumes the disposition).

Clone an existing agent — copies its config and current version into a new agent owned by the caller's org. Useful for forking a template agent before modifying it. Returns the new duplicated agent object; the top-level `id` is the id to use with `get_agent`, `run_agent`, `update_agent`, and `delete_agent`.

Start asynchronous skill generation from a use case and organization tables or uploaded files, with an optional policy. At least one table name or attachment is required; a use case or policy alone is not a data source. Returns run_id and stream location. Poll get_skill_set_generation. By default the draft is only available for review through the Roe UI/stream; set auto_commit=true only when the user wants the generated version saved and made current automatically. After auto-commit succeeds, read the version through get_skill_set_version using the set id. This may incur model usage and create tables when importing CSV attachments.

Fetch one agent's full record by id. Use when you already have the agent_id (e.g. from `list_agents`) and need its config / current version / metadata. Returns the full agent object.

Fetch the result content of a tool-result artifact produced during an agent job. Use this to expand an artifact key found in `get_agent_job_result` output — e.g. an `evidence_data` value like `MerchantRiskEngine-<job-id>/extraction_<...>.json` — into the underlying extraction/analysis it points to.

Fetch the stored result of a terminal async agent job (3 SUCCESS, 4 FAILURE, 5 CANCELLED, or 6 CACHED). Output data is normally present for 3 SUCCESS and 6 CACHED jobs; 4 FAILURE and 5 CANCELLED jobs are terminal but may have no stored output, so this call can return an error envelope — use `get_agent_job_status` to read why a job failed or was cancelled. Returns `{job_id, output, tokens, cost, trace_url, ended_at}`; `cost` and token fields may be absent — treat an absent field as unavailable, never as zero.

Get the status of an async agent job from `trigger_agent_run` or `run_batch_agent_jobs`. Use to poll until the job reaches a terminal state. Returns `{job_id, status, progress?, started_at, ended_at?}`. `status` is the raw integer code used by roe-main job status: 0 PENDING — queued, not yet picked up 1 STARTED — running 2 RETRY — backend is retrying after a transient failure (not terminal) 3 SUCCESS — complete, call `get_agent_job_result` for the output 4 FAILURE — terminal, `get_agent_job_result` returns the error 5 CANCELLED — terminal, was cancelled via `cancel_agent_job` 6 CACHED — terminal, result served from the agent's run cache Terminal set: `{3, 4, 5, 6}`. Stop polling on any of those.

Fetch stored results for many terminal async jobs in one call (each 3 SUCCESS, 4 FAILURE, 5 CANCELLED, or 6 CACHED). Returns `{results: [{job_id, output, tokens, cost, ...}, ...]}` preserving input order; `cost` and token fields may be absent — treat an absent field as unavailable, never as zero. Output data is normally present for 3 SUCCESS and 6 CACHED jobs; 4 FAILURE and 5 CANCELLED jobs may have no stored output, so those entries can come back as error envelopes — read `get_agent_jobs_status_batch` for why. Each result may contain the full agent output. Keep `len(job_ids) ≤ 25` per call so the combined payload remains within the MCP response limit. Truncation returns a `{truncated: true, ...}` envelope.

Fetch the status of many async jobs in a single call. Use this when polling a batch returned by `run_batch_agent_jobs`. Returns `{statuses: [{job_id, status, ...}, ...]}` preserving input order. `status` values are the integer codes documented on `get_agent_job_status` (terminal set: {3, 4, 5, 6}). Roe processes up to 1000 ids in server-side chunks. Keep `len(job_ids) ≤ 100` per call so the response remains within the MCP response limit. Responses past the limit return a `{truncated: true, ...}` envelope.

Fetch one specific version of an agent. Use when comparing versions or inspecting a historical config. `get_supports_eval=true` includes the eval-support flag. Returns the full version object.

Fetch one saved connection by id. Returns non-secret connection metadata, including whether credentials are configured, without returning secret values.

Fetch the agent's current live version. Use this when the active `engine_config` and `input_definitions` are needed before creating a new version or running the agent. Returns the version object.

Explain how the Roe MCP works end-to-end and how to get started, with a link to the official docs. Call this when a request is ambiguous or you are unsure which tool to use. Returns guidance plus `docs_url`. Pass `topic` to focus on one of: overview, getting-started, auth, tools, workflows, troubleshooting. Call `get_help` with topic `workflows` before building or editing a multi-step workflow (WorkflowOrchestrator) — it returns the full authoring contract plus a docs link. This is a local tool — it makes no backend call and needs no arguments.

Fetch one policy's full record by id. Use when you already have the policy_id (e.g. from `list_policies`) and need its metadata / `current_version`. To inspect the policy's actual rule content, fetch the version via `get_policy_version` or `list_policy_versions`. Returns the full policy object.

Fetch one specific version of a policy, including its full `content`. Use when comparing versions, inspecting a historical config, or templating `content` for a new policy. Returns the full version object.

Read skill-set metadata and its current_version_id. To read the actual Markdown files, call get_skill_set_version with that version id.

Read the latest tracked generation status and stream location for a skill set. Returns generation=null when none is tracked. After an auto-commit run succeeds, get_skill_set_version with the set id reads the committed files; this status response does not contain an uncommitted draft.

Read a skill-set version with its full Markdown file collection. Pass a version UUID to pin it, or a skill-set UUID to resolve its current version. Use the returned version id as agent engine_config.skill_set_version_id.

Poll or fetch a table SQL query result. Use the `table_query_id` returned by `query_tables`. If the job is still running, returns `{table_query_id, status, error}` with no rows. If complete, returns `{table_query_id, status, columns, rows, row_count, truncated, execution_time_ms}`. Rows are JSON objects keyed by column name. `truncated: true` means the result hit the row limit, backend result byte cap, or an individual huge cell was shortened; oversized cells may be returned as shortened strings even when the original ClickHouse value was a nested object or array.

List current-version context sources for an agent, with each source's callable read-only operations inlined (name, description, params_schema, response_hint). Use the returned `source_index` plus an operation name with `call_context_source_operation`; indexes are not stable IDs. Sources without operations include an `unsupported_reason`.

List the production agent engine types that can be used as `engine_class_id` when calling `create_agent`. Use this to find available engines and engine-specific config schema before creating or versioning an agent; use `list_supported_models` separately to list valid model ids. Do not guess engine names from examples. Returns `{engine_types, total_count, engines}` where `engine_types` is the compact list of valid ids and `engines` contains the richer live workflow metadata, including input schema, default configuration hints, and categories when the backend exposes them. EXCEPTION: for `WorkflowOrchestrator` (multi-step workflows) the schema is NOT sufficient — utility-node configs and ordering rules are not expressed in it; call `get_help` with topic `workflows` for the authoring contract before constructing that config. Each engine's `input_schema` is slimmed for LLM context budgets: structural fields (type, properties, required, enum, default, items, oneOf/anyOf/allOf, additionalProperties) are preserved verbatim so a valid `engine_config` can be constructed from the response, while docs-only fields (examples, title, $schema, $id) are dropped and long property descriptions are truncated.

Browse the async run (job) history for ONE agent. `cost` and token fields may be absent from a result; treat an absent field as unavailable, never as zero. `ordering=cost` / `-cost` can be rejected with 400 when cost is unavailable, so fall back to another ordering. Use to find past runs, inspect their outcomes, or locate a `job_id` to pass to `get_agent_job_status` / `get_agent_job_result`. Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to first page of 20. For "failed jobs in the last 7 days", set `status_code="4"` and `created_from` to the ISO-8601 timestamp seven days ago. Stop paging when `len(results) < page_size` or `page * page_size >= total` — requesting beyond the last page returns an empty `results` list, not an error. Filters combine as AND across distinct parameters, with OR WITHIN a single comma-separated parameter. `status_code` accepts job status codes (0 PENDING, 1 STARTED, 2 RETRY, 3 SUCCESS, 4 FAILURE, 5 CANCELLED, 6 CACHED; terminal set {3,4,5,6}) — use `status_code="4"` for failed jobs, or `status_code="4,5"` for failed OR cancelled jobs. `version_name` accepts comma-separated version names (OR). `metadata` takes `key:value` pairs (`k1:v1,k2:v2` is AND across pairs). `search` substring-matches the job id, display name, or serialized inputs. `created_from` / `created_to` bound `created_at`; pass ISO-8601 datetimes with timezone, e.g. `2024-01-01T00:00:00Z`. `ordering` sorts (prefix `-` for descending); default is `-created_at`. `limit` caps the most-recent jobs considered and counted (default 100000) so `total` stays cheap for agents with very large histories.

List the full version history for one agent. Returns every version, newest first. Use to compare configurations or to find an older config to restore. Returns `{results: [...], total: N}` — the Roe versions endpoint does not paginate, so this returns all versions in a single response. ROLLBACK: MCP cannot promote an existing version to current. To roll back, read the old version's `engine_config` / `input_definitions` (here or via `get_agent_version`) and re-submit them with `create_agent_version`, which makes that config the new current version. Do NOT try to roll back by deleting newer versions with `delete_agent_version` — that destroys history, and the promotion it triggers is by newest-remaining `created_at`, not by your choice.

List agents in the caller's Roe organization. Use this to discover agents before running one. Use `get_agent` when the agent id is already known. Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to the first page of 20.

List saved connections in the caller's Roe organization. Use this to discover connection ids before viewing, testing, or deleting a connection. Returns paginated non-secret connection metadata.

List policies in the caller's Roe organization. Use to discover which policies exist before fetching one — do NOT use to fetch a single policy you already have the id for (use `get_policy`). Returns `{results: [...], page, page_size, total, next, previous}` paginated. Defaults to first page of 20. Stop paging when `len(results) < page_size` or `page * page_size >= total` — requesting beyond the last page returns an empty `results` list, not an error.

List the version history for one policy, including each version's `content`. Returns `{results, page, page_size, total, next, previous}` paginated. Defaults to first page of 20. Stop paging when `len(results) < page_size` or `page * page_size >= total`. Use to find a previous version to roll back to (via `create_policy_version` with `base_version_id`) or compare versions.

List immutable versions of a skill set, including their complete Markdown files, newest first. Use page and page_size to browse version history.

List skill sets in your organization, with current_version_id. Use search to find a named skill set; results are paginated.

List non-deprecated LLM model ids that can be used in agent `engine_config.model`. Use this before setting or repairing a model value in `create_agent` or `create_agent_version`; do not hardcode stale model names from examples. Returns `{models, total_count, tenant_scope}` where each model includes the canonical id plus capability, provider, context/output token limits, and feature flags such as JSON mode, structured output, vision, audio, tools, and reasoning support when available. Optional `capability` filters the list to image-, audio-, or video-capable models (text-capable models are always included).

List Roe tables in the caller's organization, including each table's column names and ClickHouse column types. Use this before `preview_table` or when discovering table names created by `upload_table`. Returns `{results: [...], total}`.

Preview one Roe table in the caller's organization. Returns column metadata plus up to `limit` sample rows keyed by column name. Use after `list_tables` to inspect small examples without running an arbitrary SQL query. Defaults to 3 rows, allows at most 50, and accepts `limit: 0` when you only need table and column metadata without reading sample rows.

Irreversibly purge uploaded inputs, workflow artifacts, and stored blob data (outputs, steps, logs, trace) for one job while retaining DB metadata. DESTRUCTIVE. Requires `confirm=true` after explicit user confirmation.