MCP tools reference - Roe Documentation

This page lists the standard Roe MCP tools. Your deployment may expose additional workflow-specific tools — check the tool list advertised by your MCP client, or call get_help.

Agents

`list_agents`

read-only idempotent 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.

Parameter	Description
`page`	1-indexed page number.
`page_size`	Results per page (1-100). 20 is a good default for browsing.

`create_agent`

Create a new Roe agent. The first version is created implicitly from engine_class_id + engine_config + input_definitions. Use create_agent_version to add subsequent versions. Returns the full agent object (id, name, current_version, etc.). Navigation for config/model discovery: call list_agent_engine_types to find valid production engine_class_id values plus the engine-specific config schema/hints. Call list_supported_models to see the available model ids before setting engine_config.model. For complete working examples, call list_agents then get_current_agent_version on an agent with the engine class you want and template from its engine_config and input_definitions. Models and config can be found with those discovery tools, then made here by passing engine_class_id, engine_config, and input_definitions. Multi-step workflows: to chain agents into a pipeline (engine_class_id WorkflowOrchestrator — loops, if-branches, merges), call get_help with topic workflows FIRST; the engine schema alone is not enough to author a correct workflow config. Cold-start tip: each engine’s schema/hints from list_agent_engine_types determine which keys engine_config needs. Start from that response or template from get_current_agent_version; do not invent engine_class_id, config keys, or model ids from memory.

Parameter	Description
`name`	Human-readable agent name. Must be unique within the org.
`engine_class_id`	Engine identifier from `list_agent_engine_types`. Do not invent this value; call that tool for current production ids and choose one from the response.
`input_definitions`	List of input field specs: `[{key, data_type, description, accepts_multiple_files?}]`. `key` becomes the input parameter name on `run_agent`. `data_type` is a CLOSED MIME-type enum: use `text/plain` for ordinary strings such as URLs, names and free text — `text`, `string` and `file` are all rejected. Valid values: `text/plain`, `text/html`, `text/xml`, `text/csv`, `text/markdown`, `application/json`, `application/pdf`, `image/jpeg`, `image/png`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-m4a`, `video/mp4`, plus the wildcards `text/`, `image/`, `audio/`, `video/` and `/`. Find working examples with `list_agents` + `get_current_agent_version` and adapt that version’s `input_definitions`.
`engine_config`	Engine-specific config. Required keys vary by `engine_class_id`. Find config shape with `list_agent_engine_types`; find valid model ids with `list_supported_models`; then create the config here in `engine_config`. To make an investigation agent: also set `policy_version_id` (a policy version UUID from `create_policy` / `list_policy_versions`) to run against a policy SOP, and/or `enable_knowledge_base: true` + `knowledge_base_id` (an active knowledge base id from `list_knowledge_bases` / `finalize_knowledge_base`) to investigate against a typology lens. These are standard keys the backend understands across investigation engines.
`version_name`	Optional name for the implicitly-created first version.
`description`	Optional free-text description shown in the Roe UI.

`get_agent`

read-only idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.

`update_agent`

idempotent Update an agent’s top-level metadata (name, cache flags). To change engine config / inputs, create a new version with create_agent_version instead — agent versions are immutable once created. Returns the updated agent object.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`name`	New agent name. Unset = leave unchanged.
`disable_cache`	Controls whether this agent uses cached results for repeated inputs. Set `disable_cache=false` to allow normal cache reuse; set `disable_cache=true` to force every run to execute instead of returning cached results. Unset/null = leave the current setting unchanged.
`cache_failed_jobs`	Controls whether failed runs are also cacheable. Set `cache_failed_jobs=false` to avoid reusing failures so retries can execute again; set `cache_failed_jobs=true` to allow the same failed result to be returned from cache for repeated inputs. Unset/null = leave the current setting unchanged.

`delete_agent`

destructive idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`confirm`	Must be `true`. Set only after the user explicitly confirms permanent deletion of this agent and all its versions.

`duplicate_agent`

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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.

`list_agent_context_sources`

read-only idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents` or `get_agent`.

`call_context_source_operation`

read-only Call one read-only operation on an agent context source. Get source_index, operation names, and parameter schemas from list_agent_context_sources first. Custom API connections expose their configured GET endpoints as operations; results are JSON capped at 200KB with a truncated flag.

Parameter	Description
`agent_id`	Agent UUID from `list_agents` or `get_agent`.
`source_index`	0-based index from `list_agent_context_sources`; do not guess.
`operation_name`	Operation name from `list_agent_context_sources`; omit only if the source pins one.
`parameters`	Operation parameters keyed by the listed params_schema.

Agent versions

`list_agent_versions`

read-only idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.

`create_agent_version`

Create a new version of an existing agent — the version becomes the agent’s current_version and serves all subsequent runs. Use to iterate on engine_config or input_definitions while keeping agent history. Returns the new version object. Engine class is INHERITED from the parent agent — do NOT pass engine_class_id. Versions can swap engine_config and input_definitions only; to change the engine class itself, create a new agent with create_agent. Navigation for config/model discovery: call get_current_agent_version to inspect the current engine_config and input_definitions you are changing. Call list_agent_engine_types to find config-shape hints for the parent engine class. Call list_supported_models to see valid model ids before changing engine_config.model. Models and config can be found with those tools, then made here by passing new engine_config and/or input_definitions. For WorkflowOrchestrator agents, call get_help with topic workflows first for the authoring contract (node shapes, input_mapping syntax, loop/if/merge configs).

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`input_definitions`	New input field specs `[{key, data_type, description}]`. Unset = inherit from current version. `data_type` is a CLOSED MIME-type enum: use `text/plain` for ordinary strings such as URLs, names and free text — `text`, `string` and `file` are all rejected. Valid values: `text/plain`, `text/html`, `text/xml`, `text/csv`, `text/markdown`, `application/json`, `application/pdf`, `image/jpeg`, `image/png`, `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/x-m4a`, `video/mp4`, plus the wildcards `text/`, `image/`, `audio/`, `video/` and `/`. Find the current shape with `get_current_agent_version`; find working examples with `list_agents` + `get_current_agent_version` on similar agents.
`engine_config`	New engine-specific config. Shape varies by parent agent’s `engine_class_id`. Find the current config with `get_current_agent_version`; find config schema hints with `list_agent_engine_types`; find valid model ids with `list_supported_models`. Unset = inherit from current version. Investigation keys (same as `create_agent`): `policy_version_id` for a policy SOP, and `enable_knowledge_base: true` + `knowledge_base_id` (active knowledge base id) to investigate against a typology lens.
`version_name`	Optional name for this version (shown in the UI).
`description`	Optional free-text description for this version.

`get_agent_version`

read-only idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`version_id`	Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`.
`get_supports_eval`	Set true only when deciding whether this version can be used with Roe eval features; omit/null otherwise.

`update_agent_version`

idempotent Update mutable metadata on a version (version_name, description). Sends PATCH, so a field you omit is left unchanged and an explicit null clears it. This does not promote the version or change the agent’s current/live version; it only edits name/description metadata. Engine config and input definitions are immutable — to change those, use create_agent_version. Returns {agent_id, version_id, updated: true}.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`version_id`	Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`.
`version_name`	New version name. Omit to leave it unchanged; a blank or `null` value makes the backend auto-assign `version N`.
`description`	New free-text description. Omit to leave it unchanged; pass `null` to clear it.

`delete_agent_version`

destructive idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`version_id`	Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`.
`confirm`	Must be `true`. Set only after the user explicitly confirms permanent deletion of this agent version.

`get_current_agent_version`

read-only idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.

Connections

`list_connections`

read-only idempotent 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.

Parameter	Description
`page`	1-indexed page number.
`page_size`	Results per page (1-100). 20 is a good default for browsing.
`connector_type`	Optional connector type id to filter by, such as `custom_api`.
`search`	Optional case-insensitive search over connection name and description.

`get_connection`

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

Parameter	Description
`connection_id`	Connection UUID from `list_connections`.

`delete_connection`

destructive idempotent 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.

Parameter	Description
`connection_id`	Connection UUID from `list_connections` or `get_connection`.
`confirm`	Must be `true`. Set only after the user explicitly confirms permanent deletion of this connection and its stored credentials.

`test_connection`

read-only idempotent 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.

Parameter	Description
`connection_id`	Connection UUID from `list_connections` or `get_connection`.

Discovery

`list_supported_models`

read-only idempotent 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).

Parameter	Description
`capability`	Optional capability filter. Typical values are `image`, `audio`, or `video`; omit (default) to return every non-deprecated text-capable model.

`list_agent_engine_types`

read-only idempotent 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. No parameters.

Help

`get_help`

read-only idempotent 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. Local tool — runs inside the MCP server; no backend API call.

Parameter	Description
`topic`	Optional help topic: overview \| getting-started \| auth \| tools \| workflows \| troubleshooting. Omit for the full guide.

Identity

`whoami`

read-only idempotent Return the authenticated Roe user’s profile. Use this as a connection check before listing or running agents. Returns {user_id, org_id, email, source}. No parameters.

Knowledge base

`list_knowledge_bases`

read-only idempotent 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.

Parameter	Description
`page`	1-indexed page number.
`page_size`	Results per page (1-100). 20 is a good default for browsing.

`create_knowledge_base`

Start a new knowledge base by kicking off async typology-lens generation from a company + brief. Returns immediately with the created knowledge base id and a draft status — generation runs in the background. This is step 1 of 3: (1) create_knowledge_base; (2) poll_knowledge_base_draft until the draft status is ready; (3) finalize_knowledge_base to commit it into an active lens. Only an active knowledge base can be wired to an agent.

Parameter	Description
`company`	Company the lens is built for (e.g. ‘Acme Corp’).
`brief`	Free-text brief (>=10 chars) describing the company/product and the kinds of risk the lens should cover. Drives typology generation.
`name`	Optional display name. Defaults to the company name.
`product_name`	Optional product name to focus the typology selection.
`website_url`	Optional company/product website URL for extra context.

`get_knowledge_base`

read-only idempotent 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.

Parameter	Description
`knowledge_base_id`	Knowledge base UUID from `list_knowledge_bases`, `create_knowledge_base`, or `finalize_knowledge_base`.

`poll_knowledge_base_draft`

read-only idempotent 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.

Parameter	Description
`knowledge_base_id`	Knowledge base UUID from `create_knowledge_base` or `list_knowledge_bases`.

`finalize_knowledge_base`

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

Parameter	Description
`knowledge_base_id`	Knowledge base UUID from `create_knowledge_base` or `list_knowledge_bases`. Its draft must be `ready` (check with `poll_knowledge_base_draft`).
`name`	Optional final lens name. Unset = keep the current name.
`public`	Whether the finalized lens is publicly accessible (visible beyond this organization). Defaults to false so the lens remains org-private. Set true only when public access is intended. Finalizing always enables MCP access so agents can query the lens.

Policies

`list_policies`

read-only idempotent 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.

Parameter	Description
`page`	1-indexed page number.
`page_size`	Results per page (1-100). 20 is a good default for browsing.

`create_policy`

Create a new Roe policy with an initial version. A policy is the rulebook a policy-driven agent reasons against — every investigation engine (AMLInvestigationEngine, KYCInvestigationEngine, FraudInvestigationEngine, MerchantRiskEngine, ProductPolicyEngine, StrategyEngine) requires one via engine_config.policy_version_id. Returns the created policy object, including current_version_id, which is the id to put in engine_config. content is NOT free-form. It must match the structured schema below. Content that omits guidelines.categories is rejected, because an agent built on it fails at run time with SOP guidelines.categories is required to build plan steps — the policy also renders as empty in the Roe UI. Minimal valid content: {“guidelines”: {“categories”: [{“title”: “Prohibited products”, “description”: “What the merchant may not sell.”, “rules”: [{“title”: “No nicotine”, “description”: “Reject if the site sells vapes, e-cigarettes or nicotine pouches.”, “flag”: “RED_FLAG”}]}]}, “dispositions”: {“classifications”: [{“name”: “Reject”, “description”: “Sells a prohibited product.”}, {“name”: “Approve”, “description”: “Nothing prohibited found.”}]}, “instructions”: “Review the merchant website against the categories below.”} Field reference:

guidelines.categories[] (REQUIRED, at least one): {title (required, non-empty), description, rules[]}. Group related rules under one category.
categories[].rules[]: {title (required, non-empty), description, flag, sub_rules[]}. flag is RED_FLAG or GREEN_FLAG or omitted. Put the actual decision logic in description.
rules[].sub_rules[]: {title (required), description}. Optional; only for genuinely nested conditions.
dispositions.classifications[]: {name (required, non-empty), description, prompt}. These are the allowed verdicts the agent may return — define them whenever the agent must reach a decision, and name them exactly as the customer says them.
instructions: free text prepended to the agent’s reasoning. Scope and tone, not rules.
summary_template.template: optional handlebars-style report template.
Do NOT invent top-level keys. A flat dict of your own keys (for example {"verdicts": [...], "prohibited_items": [...]}) is the legacy shape, is not readable by the Roe UI, and will fail at run time.
Omit id and content_uuid everywhere; the backend assigns them.

Copy the shape from a working policy with list_policies then get_policy_version before authoring one from scratch. Iterate with create_policy_version.

Parameter	Description
`name`	Human-readable policy name. Must be unique within the org.
`content`	Structured policy content. Requires `guidelines.categories[]` with at least one category, each `{title, description, rules[]}`. Add `dispositions.classifications[]` for the allowed verdicts. See the tool description for the full schema and a minimal example. A flat dict of arbitrary keys is rejected.
`description`	Optional free-text description shown in the Roe UI.
`version_name`	Optional name for the implicitly-created first version.

`get_policy`

read-only idempotent 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.

Parameter	Description
`policy_id`	Policy UUID from `list_policies`, `get_policy`, or `create_policy`.

`update_policy`

idempotent Update a policy’s top-level metadata (name, description) only. To change policy content, create a new version with create_policy_version; existing policy versions are immutable. Returns the updated policy object.

Parameter	Description
`policy_id`	Policy UUID from `list_policies`, `get_policy`, or `create_policy`.
`name`	New policy name. Unset = leave unchanged.
`description`	New description. Unset = leave unchanged.

`delete_policy`

destructive idempotent 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.

Parameter	Description
`policy_id`	Policy UUID from `list_policies`, `get_policy`, or `create_policy`.
`confirm`	Must be `true`. Set only after the user explicitly confirms permanent deletion of this policy and all its versions.

`list_policy_versions`

read-only idempotent 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.

Parameter	Description
`policy_id`	Policy UUID from `list_policies`, `get_policy`, or `create_policy`.
`page`	1-indexed page number.
`page_size`	Results per page (1-100). 20 is a good default for browsing.

`create_policy_version`

Create a new version of an existing policy — the version becomes the policy’s current_version and serves all subsequent lookups. Use to iterate on policy content while preserving history. Returns the new version object (server re-fetches the full record after POST). To fork from a non-current version, set base_version_id to a version from list_policy_versions, get_policy_version, or create_policy_version. Default is the current version. content follows the same structured schema as create_policy — see that tool’s description for the full field reference. It requires guidelines.categories[] with at least one category; content that omits it is rejected, because agents built on it fail at run time with SOP guidelines.categories is required to build plan steps. Editing an existing policy: read the current content with get_policy_version, change the categories, rules or dispositions you need, and send the WHOLE document back. This is a replace, not a merge — anything you leave out is gone from the new version. Agents do not follow the change on their own: an agent pins engine_config.policy_version_id, so after creating a version you must also call create_agent_version with the new id for the change to take effect.

Parameter	Description
`policy_id`	Policy UUID from `list_policies`, `get_policy`, or `create_policy`.
`content`	Complete replacement policy content, same structured schema as `create_policy` (requires `guidelines.categories[]`). Read the current version with `get_policy_version` first and send the whole document back — omitted fields are dropped, not merged.
`version_name`	Optional name for this version (shown in the UI).
`base_version_id`	Policy version UUID from `list_policy_versions`, `get_policy_version`, or `create_policy_version`. Unset = fork from current version.

`get_policy_version`

read-only idempotent 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.

Parameter	Description
`policy_id`	Policy UUID from `list_policies`, `get_policy`, or `create_policy`.
`version_id`	Policy version UUID from `list_policy_versions`, `get_policy_version`, or `create_policy_version`.

Runs & jobs

`cancel_all_agent_jobs`

destructive idempotent Request cancellation of EVERY in-flight async job for one agent. DESTRUCTIVE. Requires confirm=true after explicit user confirmation. Targets all pending/running jobs scheduled against the agent — for selective cancellation, call cancel_agent_job per job_id instead. ASYNCHRONOUS: the Roe API only enqueues the revocation, so NOTHING is cancelled yet when this tool returns. Returns {agent_id, task_id, targeted_count, note}; targeted_count is how many non-terminal jobs were targeted, and targeted_count: 0 with task_id: null means the agent had nothing running (no work was queued). The cancelled job_ids are not enumerated — poll get_agent_jobs_status_batch to confirm individual jobs settled to 5 CANCELLED.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`; cancels its pending/running jobs.
`confirm`	Must be `true`. Set only after the user explicitly confirms cancelling every in-flight job for this agent.

`list_agent_jobs`

read-only idempotent 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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`page`	1-indexed page number.
`page_size`	Results per page (1-100). 20 is a good default for browsing.
`status_code`	Filter by job status integer code(s). Use `4` for failed jobs; comma-separated values are OR’d (e.g. `4,5` for FAILURE or CANCELLED). Codes: 0 PENDING, 1 STARTED, 2 RETRY, 3 SUCCESS, 4 FAILURE, 5 CANCELLED, 6 CACHED; terminal set {3,4,5,6}.
`version_name`	Filter by agent version name(s). Comma-separated values are OR’d.
`metadata`	Filter by job metadata as `key:value` pairs. Multiple comma-separated pairs (`k1:v1,k2:v2`) are AND’d together.
`search`	Case-insensitive substring match across the job id, display name, and serialized job inputs.
`created_from`	Only include jobs created at or after this ISO-8601 datetime (inclusive lower bound on `created_at`). Use a timezone, e.g. `2024-01-01T00:00:00Z`.
`created_to`	Only include jobs created at or before this ISO-8601 datetime (inclusive upper bound on `created_at`). Use a timezone, e.g. `2024-01-01T00:00:00Z`.
`ordering`	Sort field; prefix with `-` for descending. Supported: `created_at`, `last_updated_at`, `status_code`, `cost`, `id`, `agent_version_name`. Default `-created_at` (newest first).
`limit`	Cap on the most-recent jobs considered and counted, across all pages. Bounds the reported `total` so listing stays fast for agents with very large job histories. Defaults to 100000 when omitted; raise it to page deeper into history or lower it for an even cheaper count.

`download_job_reference`

read-only idempotent 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).

Parameter	Description
`job_id`	Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`.
`resource_id`	Resource id referenced from the job’s output. Find this value in `get_agent_job_result` output/reference fields for the job.
`as_attachment`	If true, request `?download=true` so the backend sets a `Content-Disposition: attachment` header on its response. Default false (in-context display).

`get_agent_job_result`

read-only idempotent 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}.

Parameter	Description
`job_id`	Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`; must already be terminal.

`get_agent_job_artifact`

read-only idempotent 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.

Parameter	Description
`job_id`	Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`.
`artifact_key`	Artifact key referenced from the job’s output (e.g. an `evidence_data` value). Find it in `get_agent_job_result` output/evidence fields for the job.

`cancel_agent_job`

destructive idempotent Cancel one pending/running async agent job. DESTRUCTIVE. On success returns {job_id, status: "cancelled"}. Follow with get_agent_job_status; settled jobs should reach 5 CANCELLED. Already-terminal jobs may return a structured error.

Parameter	Description
`job_id`	Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`.

`purge_agent_job_data`

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

Parameter	Description
`job_id`	Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`.
`confirm`	Must be `true`. Set only after the user explicitly confirms permanent deletion of this job’s stored data.

`get_agent_job_status`

read-only idempotent 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 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.

Parameter	Description
`job_id`	Job UUID from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`.

`get_agent_jobs_result_batch`

read-only idempotent 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.

Parameter	Description
`job_ids`	Job UUIDs from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`; each must be terminal. Must contain at least one item. Keep ≤25 because results can be large.

`get_agent_jobs_status_batch`

read-only idempotent 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.

Parameter	Description
`job_ids`	Job UUIDs from `trigger_agent_run`, `run_batch_agent_jobs`, or `list_agent_jobs`. Must contain at least one item. Keep ≤100 per call.

`run_agent`

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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`inputs`	Map of input `key` to value. Match `get_current_agent_version.input_definitions`, or `get_agent_version.input_definitions` when `version_id` is set. Do not include reserved key `metadata`; pass `{}` if no inputs are required.
`version_id`	Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. Unset = current version.

`trigger_agent_run`

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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`inputs`	Map of input `key` to value. Match `get_current_agent_version.input_definitions`, or `get_agent_version.input_definitions` when `version_id` is set. Do not include reserved keys `idempotency_key`, `metadata`, or `timeout_seconds`; pass `{}` if no inputs are required.
`version_id`	Version UUID from `list_agent_versions`, `get_current_agent_version`, `get_agent_version`, or `create_agent_version`. Unset = current version.
`idempotency_key`	Optional client-supplied dedupe key. Reuse the same key only to retrieve the same `job_id` instead of starting a new run.

`run_batch_agent_jobs`

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.

Parameter	Description
`agent_id`	Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`.
`batch_inputs`	List of per-run input maps matching `get_current_agent_version.input_definitions`. Must contain at least one item. Do not put per-input metadata here.
`timeout_seconds`	Per-job timeout in seconds. The returned JobBatch includes this value. Unset = backend default.
`metadata`	Optional free-form metadata attached to the whole batch, not individual input maps.

Tables

`list_tables`

read-only idempotent 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}. No parameters.

`delete_table`

destructive idempotent 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.

Parameter	Description
`table_name`	Roe table name to permanently delete. Letters, digits, and underscore only; must start with a letter or underscore.
`confirm`	Must be `true`. Set only after the user explicitly confirms permanent deletion of this table and its related metadata.

`preview_table`

read-only idempotent 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.

Parameter	Description
`table_name`	Roe table name to preview. Letters, digits, and underscore only; must start with a letter or underscore.
`limit`	Maximum number of sample rows to return. Defaults to 3; maximum 50. Use 0 to return only table and column metadata.

`describe_table`

read-only idempotent 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.

Parameter	Description
`table_name`	Roe table name to describe. Letters, digits, and underscore only; must start with a letter or underscore.

`query_tables`

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.

Parameter	Description
`sql`	Single read-only ClickHouse SELECT or WITH … SELECT statement over public Roe table names.
`limit`	Maximum returned rows, 1-1000. Defaults to 1000.

`get_table_query_result`

read-only idempotent 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.

Parameter	Description
`table_query_id`	UUID returned by `query_tables`.

​Agents

​list_agents

​create_agent

​get_agent

​update_agent

​delete_agent

​duplicate_agent

​list_agent_context_sources

​call_context_source_operation

​Agent versions

​list_agent_versions

​create_agent_version

​get_agent_version

​update_agent_version

​delete_agent_version

​get_current_agent_version

​Connections

​list_connections

​get_connection

​delete_connection

​test_connection

​Discovery

​list_supported_models

​list_agent_engine_types

​Help

​get_help

​Identity

​whoami

​Knowledge base

​list_knowledge_bases

​create_knowledge_base

​get_knowledge_base

​poll_knowledge_base_draft

​finalize_knowledge_base

​Policies

​list_policies

​create_policy

​get_policy

​update_policy

​delete_policy

​list_policy_versions

​create_policy_version

​get_policy_version

​Runs & jobs

​cancel_all_agent_jobs

​list_agent_jobs

​download_job_reference

​get_agent_job_result

​get_agent_job_artifact

​cancel_agent_job

​purge_agent_job_data

​get_agent_job_status

​get_agent_jobs_result_batch

​get_agent_jobs_status_batch

​run_agent

​trigger_agent_run

​run_batch_agent_jobs

​Tables

​list_tables

​delete_table

​preview_table

​describe_table

​query_tables

​get_table_query_result

Agents

`list_agents`

`create_agent`

`get_agent`

`update_agent`

`delete_agent`

`duplicate_agent`

`list_agent_context_sources`

`call_context_source_operation`

Agent versions

`list_agent_versions`

`create_agent_version`

`get_agent_version`

`update_agent_version`

`delete_agent_version`

`get_current_agent_version`

Connections

`list_connections`

`get_connection`

`delete_connection`

`test_connection`

Discovery

`list_supported_models`

`list_agent_engine_types`

Help

`get_help`

Identity

`whoami`

Knowledge base

`list_knowledge_bases`

`create_knowledge_base`

`get_knowledge_base`

`poll_knowledge_base_draft`

`finalize_knowledge_base`

Policies

`list_policies`

`create_policy`

`get_policy`

`update_policy`

`delete_policy`

`list_policy_versions`

`create_policy_version`

`get_policy_version`

Runs & jobs

`cancel_all_agent_jobs`

`list_agent_jobs`

`download_job_reference`

`get_agent_job_result`

`get_agent_job_artifact`

`cancel_agent_job`

`purge_agent_job_data`

`get_agent_job_status`

`get_agent_jobs_result_batch`

`get_agent_jobs_status_batch`

`run_agent`

`trigger_agent_run`

`run_batch_agent_jobs`

Tables

`list_tables`

`delete_table`

`preview_table`

`describe_table`

`query_tables`

`get_table_query_result`