convene_council
Convenes Heimdall's council on a brief import, a work item, a requirement, a business rule or a change request with the voices named, and answers with the sitting queued; spends the team's AI budget within the council's share.
Convene Heimdall's council on one record and get the sitting back queued. Each seated voice (Odin for architecture, Thor for testing, Loki for security, Týr for rigour and compliance, Frigg for planning, Baldur for the people who use the product, Hel for production) reads the record and the project through its own lens, with the read-only tools the token's holder may use, and leaves findings. The voices research the ground before they read, answer one another over the rounds of the exchange and refine the plan Heimdall drafts from what they said; then Heimdall rules with the plan the council agreed. Poll the sitting with get_council_session until its status is ready or failed, then read the plan and the ranked findings.
The record is named by project_id, moment (intake_scaffold on a brief import or on the project itself once Heimdall scaffolded it in conversation, requirement_review on a work item, a requirement or a business rule, change_impact on a change request against a baseline; the other moments open with their modules), subject_type (import-batch or project, work-item, requirement, business-rule or change-request) and subject_id. voices names the voices to summon by key; omit it for every voice the project seats on the moment, name one to ask one lens alone. Only voices the project seats on the moment sit; one sitting per record at a time. On the change impact moment the voices read the same brief Heimdall's impact analyst reads (the request, the impact written, the baseline and every record named with what links to it) and the verdict ranks what the change really touches, costs and risks. The call spends the team's monthly AI budget within the council's share of it, a call per voice per round plus Heimdall's plan and verdict, so read list_council_sessions before convening again on a record the council already sat on. It needs ai:use, a staff token and the project's assists on. Deciding a finding is a person's act: in the application, over REST, or through decide_council_finding on their word.
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.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Arguments
project_id*stringUUID of the project.
moment*stringThe moment the council sits on.
intake_scaffoldrequirement_reviewchange_impactsubject_type*stringThe record's alias: import-batch or project for the intake scaffold; work-item, requirement or business-rule for the requirement review.
subject_id*stringUUID of the record the council reads.
voicesstring[]optionalThe voices to summon, by key; omit for every voice the project seats on the moment.
What it returns
{ "data": { "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "moment": "requirement_review", "subject_type": "work-item", "subject_id": "0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f", "subject_title": "Apply a voucher at checkout", "status": "queued", "voices": ["thor", "loki"], "round": 0, "phase": "research", "summary": null, "plan": null, "ranked": null, "disagreements": null, "finding_count": 0, "cost_micros": 0, "cost": "$0.0000", "failure_reason": null, "requested_by": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f", "requester_name": "Jane Doe", "started_at": null, "finished_at": null, "created_at": "2026-10-28T15:00:00+00:00", "turns": [ { "id": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c03", "session_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70", "voice": "thor", "voice_name": "Thor", "lens": "Testing, verification and defects", "round": 0, "kind": "research", "status": "queued", "stance": null, "sources": null, "finding_count": 0, "failure_reason": null, "started_at": null, "finished_at": null }, { "id": "b8c9d0e1-f2a3-4b4c-8d5e-6f7a8b9c0d14", "session_id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70", "voice": "loki", "voice_name": "Loki", "lens": "Security, abuse cases and data exposure", "round": 0, "kind": "research", "status": "queued", "stance": null, "sources": null, "finding_count": 0, "failure_reason": null, "started_at": null, "finished_at": null } ] }}How it fails
VALIDATION_FAILEDthe moment is not open (the response lists the open ones), no voice the project seats on the moment was named, the council is already sitting on the record, or the council's share of the month's budget is spent; nothing was written.
RESOURCE_NOT_FOUNDunknown project_id, or a subject_type and subject_id that do not name a visible record fitting the moment (the response lists the aliases that fit).
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