MCP tools reference

​

Agents

​

list_agents

read-only idempotent List agents in the caller’s Roe organization. Use to discover which agents exist before running one — do NOT use to fetch a single agent you already have the id for (use get_agent). 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.

​

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.

​

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.

​

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.

​

delete_agent

destructive idempotent Permanently delete an agent and all its versions. DESTRUCTIVE. 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.

​

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.

​

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.

​

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.

​

Agent versions

​

list_agent_versions

read-only idempotent List the full version history for one agent. Returns every version, newest first. Use to find a previous version to roll back to or to compare configurations. Returns {results: [...], total: N} — the Roe versions endpoint does not paginate, so this returns all versions in a single response.

​

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

​

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.

​

update_agent_version

idempotent Update mutable metadata on a version (version_name, description). 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}.

​

delete_agent_version

destructive idempotent Delete one version of an agent. DESTRUCTIVE. Will fail if you try to delete the agent’s current version. If you need a different current version before deleting this one, create a new version with create_agent_version first (or delete the whole agent with delete_agent). Returns {agent_id, version_id, deleted: true} on success.

​

get_current_agent_version

read-only idempotent Fetch the agent’s CURRENT (live) version — the one that handles new runs. Use this as the preferred source for the current engine_config and input_definitions before calling create_agent_version. Cheaper than get_agent + version lookup when you only need the active config. Returns the version object.

​

Connections

​

list_connectors

read-only idempotent List available connector types and their configuration/authentication schemas. Use this before creating or testing a connection so you can choose a valid connector_type and build the required config and auth_config shapes. Returns connector metadata only; it does not include connection credentials. No parameters.

​

get_connector

read-only idempotent Fetch one connector type’s metadata, including config and auth schemas. Use after list_connectors when you need the exact fields for create_connection, update_connection, or test_connection_credentials. Returns connector metadata only; it does not include saved connection credentials.

​

list_connections

read-only idempotent List saved connections in the caller’s Roe organization. Use to discover connection ids before fetching, updating, testing, or deleting one. Returns {results, page, page_size, total, next, previous} paginated. This list response is metadata-only and does not include auth_config credentials.

​

create_connection

Create a saved connection in the caller’s Roe organization. Use list_connectors and get_connector first to construct valid config and auth_config payloads. The response may include plaintext auth_config credentials from the newly created connection; handle the result as sensitive data and prefer list_connections when you only need metadata.

​

get_connection

read-only idempotent Fetch one saved connection by id. WARNING: the response may include plaintext auth_config credentials fetched from secret storage. Use list_connections instead when metadata is enough, and treat this result as sensitive data.

​

update_connection

idempotent Update one saved connection’s name, description, config, or credentials. At least one field is required. WARNING: the response may include plaintext auth_config credentials; handle the result as sensitive data and prefer list_connections when you only need metadata.

​

delete_connection

destructive idempotent Permanently delete one saved connection and its stored credentials. DESTRUCTIVE. Use list_connections first to confirm the id and name. Returns {connection_id, deleted: true} on success.

​

test_connection

read-only idempotent Test a saved connection using its stored configuration and credentials. No connection is created, updated, or deleted, but the connector may contact the external service to validate access. Use after create_connection or update_connection to confirm the credentials work.

​

test_connection_credentials

read-only idempotent Test connector credentials without saving a connection. Use get_connector first to build valid config and auth_config payloads. No Roe connection is created, but the connector may contact the external service to validate access; use dummy values in tests and never log real secrets.

​

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

​

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.

​

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.

​

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.

​

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.

​

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.

​

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) and, by default, makes the lens public — pass public: false to keep it org-private. Returns the finalized knowledge base object (use its id).

​

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.

​

create_policy

Create a new Roe policy with an initial version. Policies are config blobs referenced by agents (unlike agents themselves, policies have no engine class — content is a free-form dict whose schema is defined by the policy’s consumer). Returns the created policy object. Policy content lives on versions. Template content from get_policy_version on an existing policy; if none exists, start with {} and iterate with create_policy_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.

​

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.

​

delete_policy

destructive idempotent Permanently delete a policy and all its versions. DESTRUCTIVE. 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.

​

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.

​

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.

​

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.

​

Runs & jobs

​

cancel_all_agent_jobs

destructive idempotent Cancel EVERY in-flight async job for one agent. DESTRUCTIVE. Cancels all pending/running jobs the caller has scheduled against the agent — for selective cancellation, call cancel_agent_job per job_id instead. Returns {agent_id, all_cancelled: true} on success. The Roe API returns no body, so this tool does not enumerate the cancelled job_ids — follow up with get_agent_jobs_status_batch if you need to confirm individual job states settled to 5 CANCELLED.

​

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.

​

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

​

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

​

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.

​

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.

​

agents_jobs_delete_data_create

destructive Irreversibly purge uploaded inputs, workflow artifacts, and stored blob data (outputs, steps, logs, trace) for one job while retaining DB metadata. DESTRUCTIVE: use only when the user explicitly wants job data purged.

​

get_agent_job_status

read-only idempotent Get the status of an async agent job from trigger_agent_run or run_agents_batch. 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.

​

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 itself be large (full agent output). If you batch many of them, the combined payload can easily exceed the MCP response size cap — RECOMMENDED: keep len(job_ids) ≤ 25 per call and split bigger fetches across multiple calls. Truncation returns a {truncated: true, ...} envelope so the LLM knows to retry with a smaller batch.

​

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_agents_batch. 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}). The Roe API chunks at 1000 ids server-side, but a single MCP response this large is hard for an LLM to consume — RECOMMENDED: keep len(job_ids) ≤ 100 per call from this side. Responses past the MCP size cap return a {truncated: true, ...} envelope instead of the statuses list.

​

run_agent

Run a Roe agent SYNCHRONOUSLY for quick single-shot inference (under ~25 seconds). Do NOT use for long-running runs — use trigger_agent_run instead. Inputs must match get_current_agent_version.input_definitions, or get_agent_version.input_definitions when version_id is set. inputs.metadata is reserved. Returns {agent_id, result: ...}.

​

trigger_agent_run

Start an asynchronous Roe agent run and return a job id. Use for runs over ~25 seconds or parallel tracking; for quick single-shot inference use run_agent. Inputs must match get_current_agent_version.input_definitions, or get_agent_version.input_definitions when version_id is set. Reserved input keys: idempotency_key, metadata, timeout_seconds. Poll the returned job_id with get_agent_job_status until terminal, then call get_agent_job_result.

​

run_agents_batch

Start many async runs for ONE agent using its current version only; there is no version_id. Use for ≥3 input maps; for 1-2 runs prefer trigger_agent_run. Build batch_inputs from get_current_agent_version.input_definitions. metadata is batch-level only, not per input. Returns {agent_id, job_ids, timeout_seconds}; poll with get_agent_jobs_status_batch, then fetch terminal results with get_agent_jobs_result_batch.

​

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. Drops the underlying table and removes table-link metadata such as project table links and dataset table sync rows.

​

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.

​

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.

​

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.

​

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.

​

upload_table

Upload an inline CSV body and create a new Roe table in the caller’s organization. Use this for small CSV payloads that fit directly in the tool call; use a file-upload workflow outside MCP for larger local files. Returns {table_name, organization_id, summary} where summary is the ClickHouse insert summary such as read_rows, written_rows, and elapsed_ns. CSV header behavior: when with_headers: true, the first CSV row is sanitized into column names and is not inserted as data. When with_headers: false, every CSV row is inserted as data and the table columns are generated as column_1, column_2, etc. FOOTGUN: table_name must match ^[a-zA-Z_][a-zA-Z0-9_]*\Z and must NOT already exist; duplicate table names return a backend validation error.

​

upload_file_as_table

Upload a CSV file reference as a Roe table using the existing synchronous table upload API. Use only when the client provides csv_file as a file-reference object with a download URL and the CSV is at most 100 MiB. Do NOT pass local filesystem paths here; for local or larger files, use the Roe public API multipart table upload endpoint with file, table_name, and with_headers. MCP clients that support file reference parameters can supply csv_file; from any other client (Claude, Cursor, etc.), upload the file in the Roe UI or via the Roe public API instead, or use upload_table for small inline CSVs. CSV header behavior matches upload_table: when with_headers: true, the first CSV row becomes column headers and is not inserted as data. When with_headers: false, every CSV row is data and columns are generated as column_1, column_2, etc. Returns {table_name, organization_id, summary}. Local tool — runs inside the MCP server; no backend API call.

​

upload_file_to_dataset

Upload a PDF file reference (at most 100 MiB) into Roe dataset storage using the existing public dataset upload API. Use this when the user provides a PDF file and wants Roe to store it for document/agent workflows. This does NOT create a queryable Roe table; for CSV tables use upload_file_as_table. Returns {file_id, file_ref, dataset_id, name, content_type, size, uploaded_file}. Use file_ref (file_<uuid>) as the durable Roe file reference for agent inputs such as pdf_files, document, or attachments. Omit dataset_id to upload to the caller’s default dataset. MCP clients that support file reference parameters can supply pdf_file; from any other client (Claude, Cursor, etc.), upload the file in the Roe UI or via the Roe public API instead. Local tool — runs inside the MCP server; no backend API call.