> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Tool Reference (beta)
> Every tool the Chamelio MCP server exposes, grouped by what it works on.
The [Chamelio MCP server](/api-reference/mcp/overview) exposes 17 tools. Every tool runs as the
signed-in user. Most tools mirror a REST endpoint, linked in each section, where you can find the
full response shape.
| Group | Tools |
| ------------------------------------- | ---------------------------------------------------------------------------------- |
| [Workflows](#workflows) | `list_workflows`, `get_workflow_schema`, `initiate_workflow` |
| [Tasks](#tasks) | `list_tasks`, `get_task` |
| [Files](#files) | `get_signed_documents`, `download_file` |
| [Users](#users) | `list_users`, `get_current_user` |
| [Knowledge Center](#knowledge-center) | `search_documents`, `get_document`, `list_document_types`, `list_org_fields` |
| [Search](#search) | `global_search` |
| [Agent](#agent) | `ask_chamelio_agent`, `follow_up_with_chamelio_agent`, `respond_to_agent_approval` |
## Workflows
### `list_workflows`
**Read.** List the workflows the user may see or request, with their ID and latest version. This
is where to start when looking for a `workflow_id`. Mirrors
[List Workflows](/api-reference/endpoint/v2/workflows/list).
| Parameter | Type | Default | Description |
| ------------- | ------- | ------- | ---------------------------- |
| `active_only` | boolean | `false` | Return only active workflows |
### `get_workflow_schema`
**Read.** Get a workflow's full schema - its variables, steps, and validation rules. Mirrors
[Get Workflow Schema](/api-reference/endpoint/v2/workflows/get-schema).
| Parameter | Type | Default | Description |
| ------------- | ------ | ---------- | ----------------------------------- |
| `workflow_id` | string | - | The workflow, from `list_workflows` |
| `version` | string | `"latest"` | A version number, or `latest` |
### `initiate_workflow`
**Write.** Start a new run of a workflow. Returns the new `task_id` and a `task_url`. Mirrors
[Initiate Workflow](/api-reference/endpoint/v2/workflows/initiate).
| Parameter | Type | Default | Description |
| ------------- | -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow_id` | string | - | The workflow to start |
| `variables` | array | - | One entry per `init_variables` entry in the workflow schema, shaped for that variable's type. See [InputValue types](/api-reference/endpoint/v2/workflows/initiate) |
| `version` | string | `"latest"` | A version number, or `latest` |
| `metadata` | object or null | `null` | Optional string key-value pairs stored with the task |
This creates a real task that people will be asked to act on. The assistant is instructed to
confirm the values with you before calling it.
## Tasks
### `list_tasks`
**Read.** List the tasks (workflow runs) the user may see, newest first, as a summary per task.
Mirrors [List Tasks](/api-reference/endpoint/v2/tasks/list).
| Parameter | Type | Default | Description |
| ------------------ | -------------- | ------- | ------------------------------------------------ |
| `limit` | integer | `50` | Maximum number of tasks to return |
| `offset` | integer | `0` | Number of tasks to skip |
| `status` | string or null | `null` | Filter by task status, for example `in_progress` |
| `include_inactive` | boolean | `false` | Include inactive tasks |
### `get_task`
**Read.** Get one task's full state: its status, workflow, steps, step runs, and collected variable
values. Mirrors [Get Task](/api-reference/endpoint/v2/tasks/get).
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | ---------------------------------------------- |
| `task_id` | integer | - | The task, from `list_tasks` or `global_search` |
## Files
### `get_signed_documents`
**Read.** List the signed documents produced by a completed task's signature steps, with a download
URL for each. Available only once the task is completed. Mirrors
[Get Signed Documents](/api-reference/endpoint/v2/tasks/signed-documents).
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | ------------------ |
| `task_id` | integer | - | The completed task |
### `download_file`
**Read.** Get a time-limited download URL for a file. Returns the URL and its expiry, not the file
contents. Mirrors [Download File](/api-reference/endpoint/v2/files/download).
| Parameter | Type | Default | Description |
| --------- | ------ | ------- | ---------------------------------------------------------------------------------------- |
| `file_id` | string | - | The prefixed ID returned by `get_signed_documents`: `document_{id}` or `attachment_{id}` |
## Users
### `list_users`
**Read.** List the users in your organization, paginated. The list is organization-wide. Mirrors
[List Users](/api-reference/endpoint/v2/users/list).
| Parameter | Type | Default | Description |
| ---------------- | ------- | ------- | ----------------------------------------- |
| `limit` | integer | `100` | Maximum number of users to return |
| `offset` | integer | `0` | Number of users to skip |
| `include_groups` | boolean | `false` | Also return each user's group memberships |
| `only_active` | boolean | `true` | Return only active users |
### `get_current_user`
**Read.** Identify the user the session acts as: their name, email, role, organization, and the
scopes the token was granted. Takes no parameters.
## Knowledge Center
### `search_documents`
**Read.** Search your organization's documents with structured filters. Results are limited to the
document types the user may reach. Mirrors
[Search Documents](/api-reference/endpoint/v2/core/search), including its filter types and paging
rules.
| Parameter | Type | Default | Description |
| ----------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `filters` | array or null | `null` | Field, attribute, and group filters. Field IDs come from `list_org_fields`; attribute IDs (`_`) from `list_org_fields` with `include_attributes` |
| `limit` | integer | `100` | Maximum number of documents to return |
| `offset` | integer | `0` | Number of documents to skip |
| `last_updated_at` | string or null | `null` | Cursor for incremental fetching by update time |
| `last_created_at` | string or null | `null` | Cursor for incremental fetching by creation time |
### `get_document`
**Read.** Get one document's fields, summary, and mapped attributes. Mirrors
[Get Contract Data](/api-reference/endpoint/v2/core/get-contract-data).
| Parameter | Type | Default | Description |
| -------------------------- | ------- | ------- | -------------------------------------------------------- |
| `document_id` | integer | - | The document, from `search_documents` or `global_search` |
| `include_summary` | boolean | `true` | Include the document summary |
| `include_attributes` | boolean | `true` | Include mapped attributes |
| `include_extracted_fields` | boolean | `true` | Include extracted field values |
The tool's defaults differ from the REST endpoint, which returns only extracted fields unless you
ask for more.
### `list_document_types`
**Read.** List your organization's document types, with the IDs to filter on in
`search_documents`. Takes no parameters. Mirrors
[Get Document Types](/api-reference/endpoint/v2/core/document-types).
### `list_org_fields`
**Read.** List your organization's fields with their numeric IDs - the vocabulary for
`search_documents` filters. Mirrors [Get Org Fields](/api-reference/endpoint/v2/core/org-fields).
| Parameter | Type | Default | Description |
| -------------------- | ------- | ------- | ------------------------------------ |
| `include_attributes` | boolean | `false` | Also return the mapped attribute IDs |
## Search
### `global_search`
**Read.** Find items by name when there is no ID yet. Searches one category at a time. Omit `query`
to get the most recently updated items in that category. Each hit carries an `item_type` and an
`item_id`: a `flow_task_*` ID goes to `get_task`, a `sor_contract` ID to `get_document`. Mirrors
[Global Search](/api-reference/endpoint/v2/search/global).
| Parameter | Type | Default | Description |
| ---------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | string | - | `workflows` (workflow definitions and their tasks), `sor` (contracts), `sor_archive` (archived contracts), or `vault` (files and folders) |
| `query` | string or null | `null` | Free text to match |
## Agent
The agent tools hand a question in plain language to the Chamelio agent, which reads the same
workflows, tasks, and documents the user can and may run its own tools. Agent runs are much slower
than the other tools - often a minute or two.
### `ask_chamelio_agent`
**Write.** Ask the agent a question, starting a new conversation. Use it for questions that span
several contracts, comparisons, or work that takes several steps. Returns a `session_id`. Mirrors
[Ask the Agent](/api-reference/endpoint/v2/agent/ask).
| Parameter | Type | Default | Description |
| --------- | ------- | ------- | ------------------------------------------------ |
| `prompt` | string | - | The question or task, in plain language |
| `use_web` | boolean | `false` | Let the agent search the public internet as well |
### `follow_up_with_chamelio_agent`
**Write.** Continue an existing agent conversation. The agent keeps the earlier context. Mirrors
[Continue a Conversation](/api-reference/endpoint/v2/agent/follow-up).
| Parameter | Type | Default | Description |
| ------------ | ------ | ------- | ------------------------------------------ |
| `session_id` | string | - | The `session_id` from `ask_chamelio_agent` |
| `prompt` | string | - | The follow-up message |
### `respond_to_agent_approval`
**Write.** Allow or refuse a tool the agent is waiting on, and resume its run. Needed only when a
previous agent call came back with `pending_approval`. Mirrors
[Answer an Approval](/api-reference/endpoint/v2/agent/approvals).
| Parameter | Type | Default | Description |
| ----------------------- | -------------- | ------- | --------------------------------------------- |
| `session_id` | string | - | The parked conversation |
| `source_interaction_id` | string | - | From `pending_approval.source_interaction_id` |
| `decision` | string | - | `approved` or `rejected` |
| `reason` | string or null | `null` | Optional explanation shown to the agent |
The agent stopped because a person should decide. The assistant is instructed to ask you what you
want before answering an approval.