# `update_goal`

Patches the wording, private details, or audience of a goal you own. Saving starts no search. Ending is a separate action.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

## When to use it

Use only when asked to edit a goal's fields or sharing. To create one, use [`create_goal`](/docs/mcp/tools/create_goal). To end one, use [`end_goal`](/docs/mcp/tools/end_goal), or [`batch_end_goals`](/docs/mcp/tools/batch_end_goals) for several. Resolve the exact goal and explain the audience for sharing changes.

An edit supplies only the fields the member wants changed. Omitted fields stay unchanged. Read the goal first and copy its opaque `version` unchanged as `expectedVersion`. Wording, private details, selected-group, visibility, and lifecycle changes invalidate older versions.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `goalId` | yes | string | The exact owned goal ID. |
| `text` | no | string | Nonblank new wording, up to 2,000 characters. Omit to preserve wording. Empty or whitespace-only text is rejected and never ends a goal. |
| `audience` | no | list of objects | Complete replacement selection and visibility, up to 100 distinct authorized groups. Each entry requires `groupPublicId` and `visibility` (`visible` or `hidden`). Omit to preserve it; `[]` makes it private. |
| `additionalContext` | no | string | Complete replacement private details, up to 4,000 characters. Omit to preserve them; `""` clears them. |
| `expectedVersion` | yes | string | Opaque `version` copied unchanged from `get_goal`. |

Supply at least one of `text`, `additionalContext`, or `audience`. `visible` lets a group's members read the goal; `hidden` keeps that group's network selected for searches without showing the goal in that group. Keep confidential details in `additionalContext`, outside shared `text`. Goals for a fixed beneficiary remain private and their beneficiary cannot change. See [Goals and audiences](/docs/mcp/concepts/goals).

## What each change does

- Wording, private context, and selected-group changes advance `scopeVersion` and cancel this goal's obsolete search. Other goals' searches continue.
- Visibility-only changes save immediately without changing matching inputs or stopping a search.
- Saving starts no replacement search. Call [`start_goal_search`](/docs/mcp/tools/start_goal_search) separately for an authorized search.

All supplied fields commit together. Validation, access, and version failures leave them unchanged. Obsolete workers cannot publish further results as current after the edit commits. Existing conversations remain attached to the goal.

## Returns

Success returns `status`, `outcome`, `message`, the canonical owned `goal`, and `cancelledSearchIds`. MCP also adds the goal's exact Gravity `link`. Saving starts no search. Read search state through [`get_goal_search`](/docs/mcp/tools/get_goal_search), match summaries through [`list_goal_matches`](/docs/mcp/tools/list_goal_matches), and a selected assessment through [`get_goal_match`](/docs/mcp/tools/get_goal_match).

| Outcome | Meaning |
| --- | --- |
| `saved` | The requested changes were committed. |
| `no_change` | All supplied changes already match current state; the goal was unchanged and no search started. |

`goal` has the base owned fields of [`get_goal`](/docs/mcp/tools/get_goal), excluding Full’s `matches` page, captured inside the save transaction, including owner, private details, audience, beneficiary identity, authorship, lifecycle fields, and the committed opaque `version`. Authorship identifies the member who supplied a received goal; it never includes their private source goal. `cancelledSearchIds` identifies the obsolete searches cancelled by this edit. The receipt contains no search state, matches, or available groups. Later changes do not replace the committed receipt; a later read may show a newer revision.

Every save compares the supplied fields with current state. If they already match, the result is `no_change`, even when a supplied version is old, so repeating an edit is safe. A stale whole-goal version rejects an edit that would change state, including a visibility edit. An identical patch retains the current version.

Errors use the [common contract](/docs/mcp/errors-and-limits). For a conflict, explain that the goal changed since the edit was prepared, inspect `currentState`, and prepare a new action only within the member's intent.

## Examples

Change only wording:

```json update_goal
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "text": "Find design partners",
  "expectedVersion": "00000000-0000-4000-8000-000000000901"
}
```

Example response (synthetic data):

```json result:update_goal
{
  "status": "success",
  "outcome": "saved",
  "message": "Goal saved.",
  "goal": {
    "id": "00000000-0000-4000-a000-000000000001",
    "beneficiary": null,
    "text": "Find design partners",
    "additionalContext": "Synthetic private details",
    "clarificationQuestion": null,
    "scopeVersion": 2,
    "suggestedByGravity": false,
    "retiredAt": null,
    "createdAt": "2026-10-09T00:00:00.000Z",
    "endReason": null,
    "authorship": null,
    "version": "00000000-0000-4000-8000-000000000902",
    "owner": {
      "memberId": "00000000-0000-4000-a000-000000000003",
      "name": "Synthetic member"
    },
    "isOwner": true,
    "audience": [
      {
        "groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "name": "Synthetic founders",
        "visibility": "hidden"
      }
    ]
  },
  "cancelledSearchIds": [],
  "link": "https://www.meetgravity.ai/dashboard/goals/00000000-0000-4000-a000-000000000001"
}
```

## Related

- [Goal editing workflow](/docs/mcp/agent-guides/create-and-edit-goals)
- [Errors and limits](/docs/mcp/errors-and-limits)
