list_pending_approvals
Lists approval requests as the inbox shows them, waiting on the token holder by default, raised by them or everything they may see, with filters and paging.
Read the approvals inbox. scope picks the view: waiting (the default) is what still waits for the token holder's own decision, leaving out the rounds they already answered; raised is what they submitted; all is everything on the projects they may see. A guest token reads only the requests that name them. project_id narrows to one project, and status, kind, artefact_type and search narrow further. Each row carries the approvers the policy named and a tally of where the approvals stand.
Deciding is a person's act: there is no tool for it. Use this to explain to a person what waits on whom and why a record is still in review, then point them at the inbox.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same actions 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
scopestringoptionalWhich view: `waiting` (default) for what waits on the token holder, `raised` for what they submitted, `all` for everything they may see.
waitingraisedallproject_idstringoptionalUUID of a project to narrow to.
statusstringoptionalNarrow to one status.
pendingapprovedrejectedchanges_requestedwithdrawnexpiredkindstringoptionalNarrow to one kind of approval.
requirement_reviewclient_sign_offtest_plan_approvalbaseline_approvalchange_requestdeployment_promotionrelease_go_livepost_mortem_sign_offdocument_approvaltimesheet_approvalsprint_commitmentartefact_typestringoptionalNarrow to one family of record under approval.
epicwork-itemrequirementbusiness-ruleuse-caseraid-itemdecisionglossary-termdata-entitypersonastakeholderbaselinechange-requestgenerated-documentsprintsearchstringoptionalWords the reference or the title must contain.
limitintegeroptionalRequests per page (1..100, default 25).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "approvable_type": "requirement", "approvable_id": "a8b9c0d1-e2f3-4a4b-9c5d-6e7f8a9b0c13", "reference": "CRM-FR-12", "title": "Apply a voucher at checkout", "kind": "requirement_review", "status": "pending", "rule": "all", "quorum": 1, "round": 1, "approvers": [ { "user_id": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b", "name": "Pat Manager", "via": "role", "stakeholder_id": null }, { "user_id": "9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a", "name": "Gail of the Client", "via": "stakeholder", "stakeholder_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f" } ], "tally": { "approved": 1, "needed": 2, "total": 2 }, "requires_comment": true, "requested_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "requester_name": "Bea Analyst", "summary": "First cut of the voucher rules.", "revision_id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b", "due_at": "2026-10-31T09:20:00+00:00", "remind_at": "2026-10-29T09:20:00+00:00", "auto_approve_at": null, "reminded_at": null, "escalated_at": null, "decided_at": null, "auto_approved": false, "created_at": "2026-10-28T09:20:00+00:00", "updated_at": "2026-10-28T11:05:00+00:00" } ], "meta": { "page": 1, "per_page": 25, "total": 1 }}How it fails
VALIDATION_FAILEDunknown scope, status, kind or artefact_type.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
FORBIDDENthe holder's role on the project named does not carry approval:view-any.
TOKEN_MISSING_ABILITYtoken lacks approval:view-any.
How is this guide?
Last updated on