Roe

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

Commit a `ready` draft into a permanent lens and mark the knowledge base `active`. Only after this can the knowledge base be wired to an agent via `engine_config.knowledge_base_id`. Check the draft is `ready` with `poll_knowledge_base_draft` first. Finalizing enables MCP access so agents can query the lens. The lens remains org-private by default; pass `public: true` only when public access is intended. Returns the finalized knowledge base object (use its `id`).

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}`.

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. 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 knowledge base's full record by id, including `status` (`drafting`/`active`/`orphaned`) and a names-only `lens_snapshot` once active. Use when you already have the id (e.g. from `list_knowledge_bases` or `create_knowledge_base`). Returns the full knowledge base object.

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.

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. 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 knowledge bases (Atlas typology lenses) in the caller's Roe organization. A knowledge base whose `status` is `active` has a finalized lens and can be wired to an agent via `engine_config.knowledge_base_id`; `drafting` ones are still generating. Use to discover an existing lens before creating a new one. 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`.

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 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}`.

Poll the async draft for a knowledge base. Returns the projected draft with `status` one of `generating`, `ready`, or `error`. Call repeatedly after `create_knowledge_base` until `status` is `ready` (then `finalize_knowledge_base`) or `error`. Read-only — does not advance the lifecycle.

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.

Submit one bounded read-only ClickHouse SQL query over Roe tables in the caller's organization. Use after `list_tables`, `describe_table`, and usually `preview_table`. SQL format: pass exactly one `SELECT` or `WITH ... SELECT` statement. Do not include multiple statements. Mutating SQL (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, `ALTER`, etc.), database-qualified names, eval tables, system tables, and Roe SQL functions such as `run_agent` are rejected. Request shape: `{sql, limit?}`. `limit` defaults to 1000 and maxes at 1000. Returns `{table_query_id, status, created_at}`. Then call `get_table_query_result` with `table_query_id`; keep polling that same tool until status is terminal.

Run one Roe agent synchronously when completion is expected within about 25 seconds. Use `trigger_agent_run` for longer work. Inputs must match the selected agent version and must not contain secrets or regulated personal data. Returns the completed result in the same call without a job id.

Start multiple asynchronous jobs for one agent using its current version. Use this when several input maps should be processed as a batch. Inputs must match the current version and must not contain secrets or regulated personal data. Returns job ids for batch status and result retrieval.

Test an existing saved connection using access already configured in Roe. Use this to verify that Roe can reach the connected external service. The tool does not expose or accept secret values.

Start one asynchronous Roe agent job. Use this for work expected to exceed about 25 seconds or when job tracking is required. Inputs must match the selected agent version and must not contain secrets or regulated personal data. Returns a job id for status and result retrieval.