> ## Documentation Index > Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP tools reference > All tools exposed by the Roe MCP server, with parameters and behavior annotations. 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 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. | 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`. 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. 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`. | ### `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 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. | 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. 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). 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. Unset = leave unchanged. | | `description` | New free-text description. Unset = leave unchanged. | ### `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. | 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_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. | Parameter | Description | | ---------- | --------------------------------------------------------------------------------- | | `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`. | ## 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. | Parameter | Description | | ---------------- | --------------------------------------------------------------- | | `connector_type` | Connector type id from `list_connectors`, such as `custom_api`. | ### `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. | 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. | ### `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. | Parameter | Description | | ---------------- | --------------------------------------------------------------------------------------------- | | `connector_type` | Connector type id from `list_connectors`, such as `custom_api`. | | `name` | Human-readable connection name. Must be unique within the org. | | `config` | Connector-specific non-secret configuration from `get_connector`. | | `auth_config` | Connector-specific credentials from `get_connector`; omit if unused. Treat values as secrets. | | `description` | Optional free-text description shown in Roe. | ### `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. | Parameter | Description | | --------------- | --------------------------------------------------------------- | | `connection_id` | Connection UUID from `list_connections` or `create_connection`. | ### `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. | Parameter | Description | | --------------- | ------------------------------------------------------------------------------------ | | `connection_id` | Connection UUID from `list_connections`, `get_connection`, or `create_connection`. | | `name` | New connection name. Unset = leave unchanged. | | `description` | New connection description. Unset = leave unchanged. | | `config` | Replacement connector config. Unset = leave unchanged. | | `auth_config` | Replacement connector credentials. Unset = leave unchanged. Treat values as secrets. | ### `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. | Parameter | Description | | --------------- | ---------------------------------------------------------------------------------- | | `connection_id` | Connection UUID from `list_connections`, `get_connection`, or `create_connection`. | ### `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. | Parameter | Description | | --------------- | ---------------------------------------------------------------------------------- | | `connection_id` | Connection UUID from `list_connections`, `get_connection`, or `create_connection`. | ### `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. | Parameter | Description | | ---------------- | --------------------------------------------------------------------------------------------- | | `connector_type` | Connector type id from `list_connectors`, such as `custom_api`. | | `config` | Connector-specific non-secret configuration from `get_connector`. | | `auth_config` | Connector-specific credentials from `get_connector`; omit if unused. Treat values as 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). | 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) and, by default, makes the lens public — pass `public: false` to keep it org-private. 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 true. Set false to keep the lens org-private. 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. 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`. | Parameter | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------- | | `name` | Human-readable policy name. Must be unique within the org. | | `content` | Initial policy content as a free-form dict. Template from `get_policy_version`; if none exists, start with `{}`. | | `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. 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`. | ### `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. | Parameter | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `policy_id` | Policy UUID from `list_policies`, `get_policy`, or `create_policy`. | | `content` | New policy content as a free-form dict. Template from `get_policy_version` on the current or a historical version. | | `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 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`. | Parameter | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | `agent_id` | Agent UUID from `list_agents`, `get_agent`, `create_agent`, or `duplicate_agent`; cancels its pending/running jobs. | ### `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_agents_batch`, 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_agents_batch`, 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-/extraction_<...>.json` — into the underlying extraction/analysis it points to. | Parameter | Description | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `job_id` | Job UUID from `trigger_agent_run`, `run_agents_batch`, 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_agents_batch`, or `list_agent_jobs`. | ### `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. | Parameter | Description | | --------- | ---------------------------------------------------------------------------- | | `job_id` | Job UUID from `trigger_agent_run`, `run_agents_batch`, or `list_agent_jobs`. | ### `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. | Parameter | Description | | --------- | ---------------------------------------------------------------------------- | | `job_id` | Job UUID from `trigger_agent_run`, `run_agents_batch`, 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 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. | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `job_ids` | Job UUIDs from `trigger_agent_run`, `run_agents_batch`, 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_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. | Parameter | Description | | --------- | --------------------------------------------------------------------------------------------------------------------------------- | | `job_ids` | Job UUIDs from `trigger_agent_run`, `run_agents_batch`, or `list_agent_jobs`. Must contain at least one item. Keep ≤100 per call. | ### `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: ...}`. | 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 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`. | 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_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`. | 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. 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. | ### `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`. | ### `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. | Parameter | Description | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `table_name` | Roe table name to create. Letters, digits, and underscore only; must start with a letter or underscore. | | `csv_content` | Raw CSV body as a string. Max 5 MB inline; for larger local files use the Roe public API multipart endpoint rather than embedding the file in the tool call. For file references, use upload\_file\_as\_table. | | `with_headers` | If true, the first CSV row is column headers and is not inserted as data. If false, every CSV row is data and columns are generated as column\_1, column\_2, etc. | ### `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. | Parameter | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `table_name` | Roe table name to create. Letters, digits, and underscore only; must start with a letter or underscore. | | `csv_file` | File reference object with download\_url, file\_id, and optional file\_name/mime\_type. This is not a local filesystem path. | | `with_headers` | If true, the first CSV row is column headers and is not inserted as data. If false, every CSV row is data and columns are generated as column\_1, column\_2, etc. | ### `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_`) 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. | Parameter | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `pdf_file` | PDF file reference object with download\_url, file\_id, and optional file\_name/mime\_type. This is not a local filesystem path. | | `dataset_id` | Optional Roe dataset UUID to upload into. Omit to use the caller's default dataset in the authenticated organization. |