list_use_cases
A project's use cases in the project's order, with reference, title, actor, other actors, goal, trigger, conditions, frequency, priority and status, narrowed for a guest token; the steps come with get_use_case.
Return the use cases of one project: how each actor reaches a goal with the system, each with its reference (such as CRM-UC-4), title, the persona who acts and the other actors in the room, the goal, the trigger, what must be true before and after, how often it happens, its MoSCoW priority and its status. Read it to find the journey a story or a requirement belongs to before you implement or test it, and name use cases by their reference when you report. The steps are left out of the list and come with get_use_case.
Optional filters narrow the page to one status, one priority, the use cases one persona_id acts in, or the use cases whose reference, title or goal contain search. A guest token reads the approved use cases only.
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
project_id*stringUUID of the project whose use cases to list.
statusstringoptionalNarrow to one status.
draftin_reviewapproveddeprecatedprioritystringoptionalNarrow to one MoSCoW priority.
mustshouldcouldwontpersona_idstringoptionalNarrow to the use cases one persona acts in, by persona UUID.
searchstringoptionalWords the reference, the title or the goal must contain.
limitintegeroptionalUse cases per page (1..100, default 25).
1max100pageintegeroptional1-indexed page number.
1What it returns
{ "data": [ { "id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "number": 4, "reference": "CRM-UC-4", "title": "Redeem a voucher at checkout", "actor_persona_id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a81", "actor_persona_name": "Nadeesha, the returning shopper", "secondary_actors": ["Payment provider"], "goal": "Pay less for the basket with a voucher the member holds", "trigger": "The member opens the checkout with a voucher in their wallet", "preconditions": "<p>The member is signed in and the basket is not empty.</p>", "postconditions": "<p>The voucher is marked used and the order carries the discount.</p>", "frequency": "A few hundred times a day in a campaign week", "priority": "must", "status": "approved", "steps": [], "position": 3, "version": 0, "approved_at": "2026-11-05T15:00:00+00:00", "approved_revision_id": null, "created_at": "2026-10-28T09:20:00+00:00", "updated_at": "2026-11-05T15:00:00+00:00" } ], "meta": { "page": 1, "limit": 25, "total": 1, "has_more": false }}How it fails
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
VALIDATION_FAILEDstatus or priority is not one of its values.
TOKEN_MISSING_ABILITYtoken lacks use-case:view-any.
How is this guide?
Last updated on