start_brief_import
Hands a whole brief to Heimdall's reader, so a document pasted into the conversation lands on the review queue as a scaffold of drafts.
Start a brief import on a project: project_id, title and text (the brief as plain text or Markdown, 40 to 60,000 characters) are required; source is pasted_text by default or meeting_notes. Heimdall reads the brief on the queue and drafts epics, stories, requirements, rules, glossary terms, personas, use cases, risks, decisions and stakeholders into the review queue; nothing reaches the record until a person accepts a row. The batch is written through the same action the Brief Import page runs and import.started goes out.
Use it for a document; for a few lines, write the records directly with the create tools. Poll get_import_batch until the status is ready or failed, then read the suggestions and point the person at the queue. The call spends the team's AI budget. A staff token with import:create on the project is needed.
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.
Annotations
A client that honours annotations asks a person before running it.
Arguments
project_id*stringUUID of the project the brief is about.
title*stringWhat the batch is called on the list, up to 160 characters.
text*stringThe brief, as plain text or Markdown, 40 to 60,000 characters.
sourcestringoptionalWhere the words came from; pasted_text by default.
pasted_textmeeting_notesWhat it returns
{ "data": { "id": "f2a3b4c5-d6e7-4f8a-8b9c-0d1e2f3a4b5c", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "source": "pasted_text", "status": "queued", "title": "Laundry shop brief", "excerpt": "An informational website for a laundry shop with order placement, tracking, payment and appointment scheduling…", "suggestion_count": 0, "provider": null, "model": null, "usage_id": null, "failure_reason": null, "created_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "creator_name": "Bea Analyst", "started_at": null, "finished_at": null, "created_at": "2026-10-28T11:20:00+00:00", "updated_at": "2026-10-28T11:20:00+00:00" }}How it fails
VALIDATION_FAILEDtitle or text missing, a text shorter than 40 or longer than 60,000 characters, or a source outside the two.
RESOURCE_NOT_FOUNDunknown project_id, or a project outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, the holder's role on the project does not carry import:create, or the project's assists are off.
TOKEN_MISSING_ABILITYtoken lacks import:create.
How is this guide?
Last updated on