Vigile
SearchContents

DocumentationOperations

create_decision

Record a standalone decision. Choose proposed or active explicitly. A project supplies only an ID prefix; it does not determine what the decision affects.

The operation's own description: what an agent reads to decide whether and how to call it.
It
Changes the plan, as one step that is stored whole or not at all.
Who may call it
Every user.
Version
Takes no version: it is carried out on the plan as it is at that moment. What it creates starts at version 1.
Answers with
The decision in short. Its fields: kind, id, title, status, version, affects, and sometimes deleted_at. Not in it: description, why, links, timeline, created_at, created_by, updated_at and unchanged_since. get has those.
MCP tool
create_decision
HTTP
POST /api/create-decision
Command
vigile create-decision

Input

FieldTakesWhat it is
titlestring
1 to 500 characters
required
descriptionstring
at most 4000 characters
required
status"proposed" | "active"required
projectstringoptional
whystring
1 to 1000 characters
optionalWhy this work matters. Give at least one reason; add more if there are several. Optional, but it helps whoever picks the task up decide and prioritise.

A field that is not listed here is refused, as invalid_input. On the command line each field is an option, with hyphens for underscores: --title.

Example

The same call three ways, as agent1. It was made on the demo plan the pictures of this site show. Over HTTP and MCP, a call without a key acts as agent1 on a new instance.

Command line

vigile create-decision \
  --title "Show gross prices" \
  --description "Include tax in displayed prices." \
  --status proposed \
  --as agent1

HTTP

curl -s http://127.0.0.1:8700/api/create-decision \
  -H 'content-type: application/json' \
  -d '{"title":"Show gross prices","description":"Include tax in displayed prices.","status":"proposed"}'

MCP tool call

{
  "name": "create_decision",
  "arguments": {
    "title": "Show gross prices",
    "description": "Include tax in displayed prices.",
    "status": "proposed"
  }
}

The answer

{
  "kind": "decision",
  "id": "018",
  "title": "Show gross prices",
  "status": "proposed",
  "version": 1,
  "affects": []
}

This is what a service answered when this page was built. Over HTTP it is the body of the response, over MCP the text of the tool result, and the command line prints it in words unless given --json.

A call that is refused

vigile create-decision \
  --title "Show gross prices" \
  --description "Include tax in displayed prices." \
  --as agent1
{
  "error": {
    "code": "invalid_input",
    "message": "The input for create_decision is not valid. status: Invalid option: expected one of \"proposed\"|\"active\".",
    "actions": ["Correct the input described in the message, then send the request again."]
  }
}

What it answers

The recorded decision's ID, title, explicit state and version.

Rules

A decision needs no task or container. Choose proposed or active at creation. A project may supply the ID prefix without creating an impact link.

Errors

invalid_input means a required field is missing or invalid. not_found means the project does not exist.