Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

decide_suggestion

Decides one row of the review queue on the person's word, after they confirm; accepting writes the record, rejecting settles the row.

Decide a suggestion of a brief import or a research sweep: suggestion_id and verdict (accept or reject) are required; payload, an object of the record's fields, replaces the drafted fields on an accept so a person's edits are written rather than the draft. Accepting a suggestion that drafts a record writes it as a draft through the ordinary action, stamped as Heimdall's and accepted by the person; a suggestion that drafts nothing, such as an improvement or a research finding, is kept on the queue as accepted for the project to read. Rejecting settles the row as rejected, or as dismissed for an idea that drafts no record, and the idea is not proposed again.

The review queue exists so that a person decides, so the tool is destructive in the MCP sense: a Heimdall turn pauses for the person's confirmation and an MCP client asks before sending. Never decide a suggestion the person did not ask you to. A staff token with import:update on the project is needed.

Requires ability

import:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same actions as

POST/v1/suggestions/{suggestion}/acceptPOST/v1/suggestions/{suggestion}/reject

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires events

import.suggestion_acceptedimport.suggestion_rejected

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

suggestion_id*string

UUID of the suggestion.

verdict*string

accept to write the record, reject to settle the row without one.

acceptreject
payloadobjectoptional

On an accept, the record's fields as the person wants them written, replacing the drafted fields; omit to accept the draft as it is.

What it returns

{  "data": {    "id": "b4c5d6e7-f8a9-4b0c-8d1e-2f3a4b5c6d7e",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "batch_id": "f2a3b4c5-d6e7-4f8a-8b9c-0d1e2f3a4b5c",    "kind": "epic",    "position": 1,    "parent_id": null,    "title": "Order placement",    "payload": {      "title": "Order placement",      "goal": "A customer books a wash in under two minutes."    },    "confidence": 0.92,    "rationale": "The brief names ordering as the first thing the site must do.",    "source_quote": "customers place laundry orders online",    "source_span": { "start": 58, "end": 95 },    "voice": null,    "status": "accepted",    "duplicate_type": null,    "duplicate_id": null,    "created_type": "epic",    "created_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",    "decided_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",    "decider_name": "Bea Analyst",    "decided_at": "2026-10-28T11:40:00+00:00",    "created_at": "2026-10-28T11:21:40+00:00"  }}

How it fails

VALIDATION_FAILED

a verdict other than accept or reject, a payload that is not an object or has more than 40 keys, a suggestion already decided, or a batch no longer ready.

RESOURCE_NOT_FOUND

unknown suggestion_id, or a suggestion outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry import:update.

TOKEN_MISSING_ABILITY

token lacks import:update.

Related

get_import_batchthe rows with their ids and payloads.decide_council_findingthe same decision on a council finding.Imports APIthe accept, reject and merge doors over REST.

How is this guide?

Last updated on