# update_proposal

Rewrite parts of a proposal this connection filed, while nobody has agreed to it yet. Name only the fields you are changing; everything you leave out is kept exactly as it stands. Refused once a named person has agreed to, rejected, or merged the proposal, and refused outright on a proposal a different connection filed: agreed meaning changes only through a revision that person signs off. Clarify material changes with the person before writing, and incorporate their answer in the meaning and cases. Outstanding questions and question retraction are retired; do not send them.

Reviewed 2026-10-01. Read the [current operating instructions](https://app.balladeer.ai/agent) and the [tool index](/docs/mcp-reference.md). This reference does not authorize the action.

## Parameters

```json
{
  "type": "object",
  "properties": {
    "proposalId": {
      "description": "The proposal this connection filed, from propose_promise.",
      "type": "string",
      "pattern": "^cand_[a-z0-9]{8,64}$"
    },
    "reason": {
      "description": "Why you are changing it, in the person's own words where they gave you any. It is recorded on the proposal and read by whoever decides it. Name nobody in it: Balladeer records who connected you as the person behind this act, and a name from git, a commit or a file is not the person in the conversation. Say \"the person\" or quote their words.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "explicitIntent": {
      "description": "The actual request or the precise agent-worded offer and literal human acceptance, attributed separately. Replaces the stored intent; never invent a human quote.",
      "type": "string",
      "minLength": 1,
      "maxLength": 8000
    },
    "meaning": {
      "description": "The whole meaning replaces the stored object: omitted nested fields are not kept. Read get_proposal's complete meaning, copy it, and change only what the person asked to change. Retain every unchanged field, including original claim and case saidWords; do not rebuild from presentation fields. When a correction makes an existing quote misleading, replace it with an exact contiguous span from one actual human message supporting the corrected claim or case. Never stitch separate spans, paraphrase inside saidWords, or silently drop quotes while rewriting cases. For a newly derived or corrected case with no literal supporting human span, omit its optional quote rather than invent one, and preserve the confirmed interpretation and acceptance in explicitIntent. Do not drop unchanged quotes. Existing absent quotes on historical or noncapture meanings need not be invented. For a title-only edit, change only meaning.title in the complete copied object; keep every other field exactly. This field does not change consent or approval.",
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "oneSentenceOutcome": {
          "description": "The whole promise in one sentence a person could say to a customer, at most 160 characters. Write it in their words, and never as a restatement of the name.",
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "beneficiary": {
          "description": "Who relies on this behavior, named the way a teammate would: a buyer, a promise owner, a person who installed the CLI.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "trigger": {
          "description": "The situation that sets this behavior off, in plain words a teammate would use for the work that meets it, such as 'a buyer edits an approved order'. Later work finds this promise by its trigger and beneficiary: name the situation in the software, not the product.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "preconditions": {
          "description": "What must be true for this behavior to apply, one condition each: which customers, accounts or plans; which role or actor; which environment, region or locale; which feature flag or rollout stage; which versions; from or until when. Write only limits the person stated or the work plainly shows. Never invent one, and leave the list empty when the behavior applies to everyone.",
          "maxItems": 24,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "observableOutcome": {
          "type": "string",
          "minLength": 1,
          "maxLength": 8000
        },
        "allowedVariations": {
          "maxItems": 24,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "nonGoals": {
          "description": "Who and what this promise does not cover, one each: the customers, roles, environments or situations a reader might wrongly assume are included. Later work is ruled in or out by these.",
          "maxItems": 24,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "passingExamples": {
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "setup": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "expectedOutcome": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "saidWords": {
                "description": "The person's own sentence this case was drawn from, quoted exactly. Leave it out rather than composing one.",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "label",
              "setup",
              "expectedOutcome"
            ],
            "additionalProperties": false
          }
        },
        "failingExamples": {
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "setup": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "expectedOutcome": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "saidWords": {
                "description": "The person's own sentence this case was drawn from, quoted exactly. Leave it out rather than composing one.",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "label",
              "setup",
              "expectedOutcome"
            ],
            "additionalProperties": false
          }
        },
        "refactorExamples": {
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "setup": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "expectedOutcome": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "saidWords": {
                "description": "The person's own sentence this case was drawn from, quoted exactly. Leave it out rather than composing one.",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "label",
              "setup",
              "expectedOutcome"
            ],
            "additionalProperties": false
          }
        },
        "saidWords": {
          "description": "The person's own sentence the claim was drawn from, quoted exactly. Never a paraphrase, and never composed.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "scope": {
          "type": "object",
          "properties": {
            "repositoryId": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "surfaces": {
              "description": "One or more real repository-relative paths or one-token capability markers. Reuse an existing marker when known. For a new capability the person named, format its words as a hyphenated marker yourself: for example, supplier import becomes supplier-import. This is a descriptive marker, not a registered identifier; do not ask the person to supply its format. Use a file path only when you know it exists in this repository. Never invent paths or repository IDs; get the repositoryId from get_promise_setup.",
              "minItems": 1,
              "maxItems": 24,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 96,
                "pattern": "^[A-Za-z0-9_:.@/[\\]-]+$"
              }
            },
            "labels": {
              "default": [],
              "maxItems": 24,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 96,
                "pattern": "^[A-Za-z0-9_:.@/[\\]-]+$"
              }
            }
          },
          "required": [
            "repositoryId",
            "surfaces"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "title",
        "beneficiary",
        "trigger",
        "preconditions",
        "observableOutcome",
        "allowedVariations",
        "nonGoals",
        "passingExamples",
        "failingExamples",
        "scope"
      ],
      "additionalProperties": false
    },
    "unresolvedQuestions": {
      "description": "Retired. Omit this field; legacy callers may send an empty array.",
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 2000
      }
    },
    "retractQuestions": {
      "description": "Balladeer no longer stores outstanding questions. Before writing, ask the person only about ambiguity that changes the commitment, then put their answer in the meaning and cases. Do not invent an answer or change agreed meaning. Nothing was recorded; refresh your Balladeer instructions before retrying.",
      "minItems": 1,
      "maxItems": 8,
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 32
      }
    },
    "retractReason": {
      "description": "Balladeer no longer stores outstanding questions. Before writing, ask the person only about ambiguity that changes the commitment, then put their answer in the meaning and cases. Do not invent an answer or change agreed meaning. Nothing was recorded; refresh your Balladeer instructions before retrying.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "proposedOwnerId": {
      "description": "A different person to ask, from the members list on get_promise_setup. A name that is not on that list is refused and the refusal says who is. Refused once a person has routed this proposal to somebody: handing it on is then theirs.",
      "type": "string",
      "maxLength": 2000
    },
    "confidence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1
    }
  },
  "required": [
    "proposalId",
    "reason"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}
```

## Effect annotations

```json
{
  "readOnlyHint": false,
  "destructiveHint": true,
  "idempotentHint": false,
  "openWorldHint": false
}
```