list_revisions
Every version of a revisable artefact, newest first, with who wrote it, why, and the diff from the version before.
Return the versions of one artefact, newest first: for each, the version number, the reason it was written (created, edit, ai_assist, import, transition, restore, approval, baseline or manual), who wrote it and through what, a one-line summary, the columns it changed, the diff from the version before and the full snapshot. Read it to see how a record changed before you change it again, to find who last touched a field, and to find the revision_id a restore needs.
Takes artefact_type (epic today; the planning families join as they land) and artefact_id. Needs activity:read and the artefact's own view ability; a guest token is refused, because the versions are the drafts behind the agreed record.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Annotations
It reads and never changes anything.
Arguments
artefact_type*stringThe artefact family the versions belong to.
epicwork-itemrequirementbusiness-ruleuse-caseraid-itemdecisionglossary-termdata-entitypersonastakeholderbaselinechange-requestgenerated-documentsprintartefact_id*stringUUID of the artefact whose versions to list.
limitintegeroptionalVersions per page (1..100, default 25).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a0b", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "revisable_type": "epic", "revisable_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", "version": 3, "reason": "edit", "actor_kind": "human", "author_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "author_name": "Nimal Fernando", "ai_feature": null, "restored_from_id": null, "restored_from_version": null, "summary": "Edited: Priority, Due on", "changed_fields": ["priority", "due_on"], "diff": { "priority": { "from": "should", "to": "must" }, "due_on": { "from": null, "to": "2027-03-31" } }, "snapshot": { "title": "Loyalty tiers", "summary": null, "goal": "Reward the top fifth of members so they keep buying from the client.", "business_value": null, "hypothesis": null, "success_metrics": null, "owner_id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "priority": "must", "status": "draft", "starts_on": null, "due_on": "2027-03-31", "color": null }, "created_at": "2026-10-29T10:15:00+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 3, "has_more": false }}How it fails
VALIDATION_FAILEDartefact_type is not a revisable family.
RESOURCE_NOT_FOUNDunknown artefact_id, or an artefact outside the token's scope or the person's visibility.
FORBIDDENthe token is a guest's, or its holder's role on the project does not carry the artefact's view permission.
TOKEN_MISSING_ABILITYtoken lacks activity:read.
How is this guide?
Last updated on