review_quality
Asks Heimdall to review one work item, requirement or business rule and keeps the review, with its score, band, summary and findings; spends the team's AI budget.
Ask Heimdall for a fresh quality review of one record and keep it on the record. A story is read against INVEST, its acceptance criteria, the project's business rules and its sibling stories; a requirement for one testable statement, a rationale, a measure and a fitting verification method; a business rule for its condition, action, exceptions, worked examples and authority, and for conflicts and overlaps with the project's other rules. The answer carries a score from 0 to 100 (100 less 25 per high, 10 per medium and 4 per low finding), its band (ready at 80 and above, needs_work from 50, not_ready below), a summary and the findings, each with a code, a severity, the words concerned and a suggestion in the record's own words.
Nothing on the record changes: the findings are for a person to act on. The record is named by artefact_type (work-item, requirement or business-rule) and artefact_id. The call spends the team's monthly AI budget, so read the latest review with list_quality_reviews first and ask again only when the record changed or was never reviewed, never in a loop. It needs ai:use, a staff token and the project's assists on.
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.
Delivered to every endpoint subscribed to it once the change is made.
Arguments
artefact_type*stringThe record's type: a work item, a requirement or a business rule.
work-itemrequirementbusiness-ruleartefact_id*stringUUID of the record to review.
What it returns
{ "data": { "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d01", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "artefact_type": "work-item", "artefact_id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f", "version": 3, "score": 71, "band": "needs_work", "summary": "A clear story with a measurable goal; one criterion cannot be verified as written and one word leaves the scope open.", "findings": [ { "code": "testable", "severity": "high", "message": "The criterion \"the basket updates quickly\" cannot pass or fail: \"quickly\" has no limit.", "suggestion": "Then the basket total updates within 1 second of the voucher being applied.", "field": "criteria" }, { "code": "ambiguous", "severity": "low", "message": "\"Some vouchers\" leaves open which vouchers apply.", "suggestion": "Name the voucher kinds: percentage, fixed amount and free delivery.", "field": "description" } ], "findings_count": 2, "provider": "anthropic", "model": "the model the quality role is configured with", "usage_id": "c9d0e1f2-a3b4-4c5d-8e6f-7a8b9c0d1e23", "reviewed_by": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "reviewer_name": "Jane Doe", "reviewed_at": "2026-10-28T11:00:00+00:00", "created_at": "2026-10-28T11:00:00+00:00" }}How it fails
VALIDATION_FAILEDartefact_type is not work-item, requirement or business-rule (the response lists them), or Heimdall could not reach its model; nothing was filed or written, and a retry a moment later is safe.
RESOURCE_NOT_FOUNDunknown artefact_id, or a record of a project outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, the holder's role does not carry ai:use, or the project's assists are off.
AI_BUDGET_EXHAUSTEDthe team's monthly AI budget has no room; a team admin raises it under Settings → AI.
TOKEN_MISSING_ABILITYtoken lacks ai:use.
Related
How is this guide?
Last updated on