WRITE

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*string

UUID of the project.

moment*string

The moment the council sits on.

intake_scaffoldrequirement_reviewchange_impact
subject_type*string

The record's alias: import-batch or project for the intake scaffold; work-item, requirement or business-rule for the requirement review.

subject_id*string

UUID of the record the council reads.

voicesstring[]optional

The 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_FAILED

the 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_FOUND

unknown 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).

FORBIDDEN

the token is a client guest's, the holder's role does not carry ai:use, or the project's assists are off.

AI_BUDGET_EXHAUSTED

the team's monthly AI budget has no room; a team admin raises it under Settings → AI.

TOKEN_MISSING_ABILITY

token lacks ai:use.

How is this guide?

Last updated on