---
title: MCP Actions
description: What a connected AI client can start or write when its grant allows actions — audits, draft listings and recommendation state — with confirmation, idempotency keys and operations.
---

## Actions

With **Allow actions** on in the grant, these tools are also available. Each is the Public API's [action](/docs/api/actions) of the same name: the same checks, the same limits and the same result.

| Tool | What it does | Arguments |
|---|---|---|
| `start_audit` | Starts an audit of one project's store app and answers its operation. The audit runs for several minutes: follow it with get_operation, then get_audit with the audit id the operation lists. Asks you to confirm first where your client can. | `orgId`, `projectId`, `idempotencyKey`; `store` |
| `start_audit_batch` | Starts one audit per listed project as one operation. Every project is checked before anything starts. Follow it with get_operation. Asks you to confirm first where your client can. | `orgId`, `items`, `idempotencyKey` |
| `create_revision_draft` | Writes text into a project's working draft listing for one store, for a person to review and publish in Apptonomy. Nothing is published. Name the accepted recommendation the text implements, if any. | `orgId`, `projectId`, `store`, `fields`, `idempotencyKey`; `recommendationId`, `baseRevision` |
| `transition_recommendation` | Moves a recommendation to open, accepted, deferred, resolved or dismissed — for every audit that observed it (its stableKey) — and records who, why and when. Pass the stateVersion you read as expectedVersion. From resolved or dismissed it can only go back to open. | `orgId`, `recommendationId`, `to`, `expectedVersion`, `idempotencyKey`; `reason`, `deferredUntil`, `resolution`, `draftRevisionId` |
| `get_operation` | The status of an operation start_audit, start_audit_batch, create_revision_draft or transition_recommendation queued: its state, each item's end, and the audits, revision or recommendation it produced. | `orgId`, `operationId` |

- **Confirming.** Starting audits counts against your organization's quota and its plan's audit cadence, so before `start_audit` or `start_audit_batch` queues anything, the client asks you to confirm — where the client can ask (MCP elicitation). Decline and nothing is queued. A client that can't ask shows these tools as ones that change data, and asks you for permission itself before it runs one.
- **`idempotencyKey`** is a value the client picks for each new request. The client can repeat a call with the same key and arguments safely: it gets the same operation back, and nothing starts twice.
- **What the client gets back** is an operation: follow it with `get_operation`, then the audit itself with `get_audit` — an audit runs for several minutes. A draft and a recommendation's new state are written before the tool answers.
- **Who it acts as.** An audit the client starts runs as you, and the audit shows you started it. A draft or a recommendation's change records you and the client.
- **Your role.** Every role can start audits, write drafts and change a recommendation's state, as in the app. The grant must also let the client read recommendations to change one. Publishing a draft stays in the app.
- A draft written this way waits in Apptonomy's listing editor, like any other draft, until someone reviews and publishes it.

A typical session, as a client's tool log shows it:

| Step | Tool | Arguments |
|---|---|---|
| Which organizations this connection reaches, your role in each, and whether this client is granted there. | `list_organizations` | `{}` |
| The organization's projects. | `list_projects` | `{"orgId":"<ORG_ID>"}` |
| The project's latest completed audit. | `list_audits` | `{"projectId":"<PROJECT_ID>","status":"completed","limit":1}` |
| That audit's open recommendations. | `list_recommendations` | `{"projectId":"<PROJECT_ID>","auditId":"<AUDIT_ID>","status":"open"}` |
| One recommendation with its provenance. | `get_recommendation` | `{"projectId":"<PROJECT_ID>","recommendationId":"<RECOMMENDATION_ID>"}` |

Every tool result and every refusal from Apptonomy includes a `requestId` (an argument the client sent in the wrong shape is refused by the MCP layer before it reaches Apptonomy, and has none). Recommendations, scores and impact results carry **provenance**: which statements were measured, which were derived, which are AI interpretations, and the sources behind each — so you can check what the client tells you against where it came from. Ask the client to show its sources.
