> Source: https://wexa.ai/docs/tools/overview

# Tool reference

This reference covers 62 governed tools. Each one is the same tool on all four surfaces — the Wexa
MCP server, the REST API, the TypeScript SDK and the Python SDK — running through the same governance and
writing the same audit record. Each has one page here.

It also covers the calls that sign a Wexa user in through an SDK — [login](/docs/tools/login),
[refresh-session](/docs/tools/refresh-session) and [logout](/docs/tools/logout). They are not governed
tools: they run before any tool call, on the REST API and both SDKs only.

Three pages are about all of them rather than any one:
[errors](/docs/tools/errors) for every class both SDKs raise,
[which identifier goes where](/docs/tools/identifiers) for the id each argument actually accepts, and
[connection-info](/docs/api/discovery) to see which tools you can call.

## Return shape

Every tool returns the same data on every surface, but each surface wraps it differently, and code
written against one will not read another correctly.

| Surface | What you get |
| --- | --- |
| REST API | `{"lifecycle_id": "qlc_...", "result": { ... }}` — read `result`. |
| TypeScript SDK | `result` **already unwrapped**: the object you get back *is* the result. The governance ids are non-enumerable properties named **`lifecycleId`** and **`traceId`** — camel case, so `result.lifecycle_id` is `undefined`. `Object.keys()` and `JSON.stringify()` omit them. Reading `.result` gives you nothing. |
| Python SDK | `result` already unwrapped, the same way, but the ids are attributes named **`lifecycle_id`** and **`trace_id`** — snake case. The two SDKs differ here, and code ported between them by hand gets `undefined` rather than an error. |
| Wexa MCP server | `{"content": [{"type": "text", "text": "..."}], "isError": false}`, where `text` is the REST envelope as a JSON **string**. The client must parse it. |

Every tool page shows its own real captured output in all of these forms.

## Every tool

### Signing in

| Tool | What it does |
| --- | --- |
| [`login`](/docs/tools/login) | Log a Wexa user in with email and password and get an SDK session for one project. |
| [`refresh-session`](/docs/tools/refresh-session) | Trade an SDK session's refresh token for a new token pair. |
| [`logout`](/docs/tools/logout) | End an SDK session so it can no longer be used or refreshed. |

### Reading context and code

| Tool | What it does |
| --- | --- |
| [`connector-read`](/docs/tools/connector-read) | Run a READ-ONLY query for the ACTUAL ROWS of an OM-synced/Wexa DB source, LIVE against the source (nothing is copied into Wexa — ideal for large warehouse/DB sources). |
| [`fetch-code`](/docs/tools/fetch-code) | Fetch a single code span from the ingested codebase (CodeChunk store). |
| [`query-context`](/docs/tools/query-context) | Run a read-only Cypher query against this project's Wexa context graph. |
| [`search-code`](/docs/tools/search-code) | Grep-like search over the project's ingested codebase (CodeChunk fulltext on the server). |

### Writing context

| Tool | What it does |
| --- | --- |
| [`create-ontology`](/docs/tools/create-ontology) | Define graph ontology (node types, relationships, properties) for this project. |
| [`delete-context`](/docs/tools/delete-context) | Delete a node from this project's context graph, together with its relationships. |
| [`save-context`](/docs/tools/save-context) | Save nodes and relationships into this project's context graph (Simple/auto mode). |

### Running agents

| Tool | What it does |
| --- | --- |
| [`run-agent`](/docs/tools/run-agent) | Resume an agent that ALREADY EXISTS in this project, with a natural-language goal, and return its execution_id. |
| [`run-process-flow`](/docs/tools/run-process-flow) | Run a process flow against the knowledge base. |

### Agents

| Tool | What it does |
| --- | --- |
| [`agent-versions`](/docs/tools/agent-versions) | Read an agent's promoted version history. |
| [`create-agent`](/docs/tools/create-agent) | Create an agent in the Orchestrate Agents registry and return its agent_id, which get-agent, update-agent, delete-agent and run-agent all accept unchanged. |
| [`delete-agent`](/docs/tools/delete-agent) | Delete an agent from the Orchestrate Agents registry by its agent_id. |
| [`get-agent`](/docs/tools/get-agent) | Read one agent from the Orchestrate Agents registry by its agent_id (the id list-agents and create-agent return, and the one the console shows in its URL). |
| [`list-agents`](/docs/tools/list-agents) | List the agents in this project — the same set the console's Agents page shows, one row per agent. |
| [`rollback-agent-version`](/docs/tools/rollback-agent-version) | Make an earlier promoted version of an agent live again. |
| [`update-agent`](/docs/tools/update-agent) | Change an agent in the Orchestrate Agents registry. |

### Process flows

| Tool | What it does |
| --- | --- |
| [`create-process-flow`](/docs/tools/create-process-flow) | Create a multi-agent process flow. |
| [`delete-process-flow`](/docs/tools/delete-process-flow) | Delete a process flow from this project by id. |
| [`flow-versions`](/docs/tools/flow-versions) | List a process flow's promoted versions, newest first, with which one is live. |
| [`get-process-flow`](/docs/tools/get-process-flow) | Fetch a multi-agent process flow by id or name, including its agents and wiring. |
| [`promote-flow`](/docs/tools/promote-flow) | Snapshot a process flow exactly as it stands now and record that snapshot as its next version, becoming the live one. |
| [`rollback-flow-version`](/docs/tools/rollback-flow-version) | Mark an earlier version of a process flow as the live one. |
| [`update-process-flow`](/docs/tools/update-process-flow) | Add ONE new agent (skilled_agent, decider_agent or interop_agent — the external agent node) to an EXISTING process flow -- the tool equivalent of the UI's '+' button -- OR, if agent_id is given, EDIT an agent already in the process flow in place (a PARTIAL update: only the fields you include in `agent` change, everything else on that… |

### Executions

| Tool | What it does |
| --- | --- |
| [`get-execution`](/docs/tools/get-execution) | Poll a process flow execution, including one waiting on an external agent. |

### Schedules

| Tool | What it does |
| --- | --- |
| [`create-schedule`](/docs/tools/create-schedule) | Schedule an agent or a process flow to run unattended, and return its schedule_id. |
| [`delete-schedule`](/docs/tools/delete-schedule) | Cancel and remove a schedule by its schedule_id. |
| [`get-schedule`](/docs/tools/get-schedule) | Read one schedule by its schedule_id. |
| [`list-schedules`](/docs/tools/list-schedules) | List the schedules in this project — the same set the console's Schedules panel shows. |
| [`update-schedule`](/docs/tools/update-schedule) | Change a schedule. |

### Triggers

| Tool | What it does |
| --- | --- |
| [`list-triggers`](/docs/tools/list-triggers) | List the triggers attached to one target, or to every target of one kind in this project. |
| [`set-triggers`](/docs/tools/set-triggers) | Replace the triggers on one agent, connector, table or column. |

### Knowledge base

| Tool | What it does |
| --- | --- |
| [`delete-kb-document`](/docs/tools/delete-kb-document) | Delete knowledge base documents from this project by tag. |
| [`knowledge-base-add`](/docs/tools/knowledge-base-add) | Add a document to this project's knowledge base so knowledge-base-retrieve can find it. |
| [`knowledge-base-retrieve`](/docs/tools/knowledge-base-retrieve) | Retrieve raw KB documents by tags. |

### Connectors and skills

| Tool | What it does |
| --- | --- |
| [`list-connectors`](/docs/tools/list-connectors) | List the connectors this project may use, each with its actions and the JSON Schema of every action's arguments. |
| [`list-skills`](/docs/tools/list-skills) | List this project's existing, already-usable skills, grouped by connector -- each skill's real `_id` can be put directly into an agent's skills[] (create-process-flow's manifest mode or update-process-flow). |
| [`provision-connector`](/docs/tools/provision-connector) | Provision a credential-free connector in this project, which mints one skill per action it supports — the only way to get skills into a new project, and the first step before create-process-flow (agent.skills[] must reference real ids from list-skills). |
| [`run-connector-action`](/docs/tools/run-connector-action) | Run one action of a connector this project may use, and return its result. |
| [`sync-connector`](/docs/tools/sync-connector) | Sync one connector this project may use, the same as the console's Sync this connector, and get a sync id back at once. |
| [`get-connector-sync`](/docs/tools/get-connector-sync) | The status of a connector sync, in two parts: whether the refresh succeeded, and what is known about ingestion. |

### Peer agents

| Tool | What it does |
| --- | --- |
| [`list-peer-agents`](/docs/tools/list-peer-agents) | List the peer agent connections this project holds, with the connection_id an external agent node points at. |
| [`handshake-peer-agent`](/docs/tools/handshake-peer-agent) | Ask a candidate external agent who it is and what it says it can do, without creating anything. |
| [`register-peer-agent`](/docs/tools/register-peer-agent) | Register an external agent on another platform as a peer agent connection, and return its connection_id. |
| [`delete-peer-agent`](/docs/tools/delete-peer-agent) | Remove a peer agent connection, unless an external agent node still delegates to it. |

### Data Tables

| Tool | What it does |
| --- | --- |
| [`add-column`](/docs/tools/add-column) | Add one or more columns to an existing Data Table. |
| [`create-table`](/docs/tools/create-table) | Create a Data Table with its columns in one call, and return its table_id. |
| [`delete-column`](/docs/tools/delete-column) | Delete a column from a Data Table, and its values in every row. |
| [`delete-table`](/docs/tools/delete-table) | Delete a Data Table, its rows AND the connector behind it. |
| [`delete-table-rows`](/docs/tools/delete-table-rows) | Delete rows from a Data Table by their row ids. |
| [`edit-column`](/docs/tools/edit-column) | Change one column of a Data Table. |
| [`get-table`](/docs/tools/get-table) | Read one Data Table's shape: its name, its columns with their types, and the connector behind it. |
| [`insert-table-rows`](/docs/tools/insert-table-rows) | Insert rows into a Data Table. |
| [`list-tables`](/docs/tools/list-tables) | List the Data Tables in this project. |
| [`query-table-rows`](/docs/tools/query-table-rows) | Read rows from a Data Table with paging, sorting, free-text search and structured filtering. |
| [`rename-table`](/docs/tools/rename-table) | Rename a Data Table. |
| [`update-table-row`](/docs/tools/update-table-row) | Change one row in a Data Table, addressed by its row_id (the row's _id as query-table-rows returns it). |

### Models

| Tool | What it does |
| --- | --- |
| [`list-models`](/docs/tools/list-models) | List the AI models this organization can run, and which one is the default. |
| [`run-model`](/docs/tools/run-model) | Send a prompt to one of this organization's AI models and get the answer back, with the tokens, the cost and the latency. |
| [`set-model`](/docs/tools/set-model) | Set this organization's default AI model — the one every agent uses unless it names its own. |

### Approvals

| Tool | What it does |
| --- | --- |
| [`request-approval`](/docs/tools/request-approval) | Ask a person in this project to approve something your app is about to do; it shows in the Approvals Inbox as an App request. |
| [`get-approval`](/docs/tools/get-approval) | Read one approval in this project and its decision. |

### Documentation

| Tool | What it does |
| --- | --- |
| `docs` | Wexa documentation for agents: topic=ontology (the live project ontology), query-examples, governance (your scopes/limits), tool-usage, orchestrate (process flows and knowledge base tools), or search with a query. |

## How to read a tool page

Each page opens with what the tool is for, in the tool's own words, then says what it is called on each of the
four surfaces, lists its arguments with types and which are required, shows the same call four ways, and ends
with the errors it can raise and the governance it runs under. The arguments come from the gateway itself, so
a page cannot describe an argument the tool does not take.