# `end_goal`

Ends one goal you own, stops its searches, and archives its introduction chats as read-only. History is retained. Ending cannot be undone.

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

## When to use it

Use only when the member explicitly asks to end a goal. Resolve its exact identity and current opaque version with [`list_goals`](/docs/mcp/tools/list_goals) or [`get_goal`](/docs/mcp/tools/get_goal). Goals the member owns for other people are eligible. A goal owned by someone else is unavailable.

Explain the consequences before acting: searches stop, introduction chats become read-only, and the goal cannot be reopened. The member's chat request authorizes execution; do not require a Gravity UI visit or another confirmation. Clarify only an ambiguous goal or another consequential choice. For several goals, use [`batch_end_goals`](/docs/mcp/tools/batch_end_goals).

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `goalId` | yes | string | Exact owned goal UUID. |
| `expectedVersion` | yes | string | Opaque `version` copied unchanged from the goal you read. |
| `endReason` | no | string | `achieved` only when the member says they got what they needed; `no_longer_needed` only when they say they no longer need it. Otherwise omit it. |

Never infer a reason from a generic ending request, and do not require one to finish. Ending does not by itself mark the goal achieved or an introduction successful.

## Effects and retries

An active goal's version must match. Ending advances it once, cancels live searches, withdraws pending context proposals, and archives the goal's shared introduction chats. Their history remains readable through authorized links; private Gravity conversations remain available. Other goals are unchanged, including any separate goal a recipient received from an offer.

Ending an already-ended owned goal returns `no_change`, even with an older supplied version. Its saved reason, retirement time, and version remain unchanged. Ending cannot correct an earlier reason or reopen the goal. A missing or inaccessible goal returns `unavailable`.

## Returns

Success returns `status`, `message`, `outcome` (`ended` or `no_change`), `goal`, `cancelledMatchingRunIds`, and a presentation `link`. The goal contains its lifecycle fields: `id`, original `text`, current `version` and `scopeVersion`, `retiredAt`, and saved `endReason` (null when unstated). Read `get_goal` for full goal details.

Errors use the [common error contract](/docs/mcp/errors-and-limits). A version conflict ends nothing. Read the current goal and reconcile the member's intent before another write. After an unconfirmed outcome, read before retrying and never claim success.

## Example

```json end_goal
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "expectedVersion": "00000000-0000-4000-8000-000000000901"
}
```

Example response (synthetic data):

```json result:end_goal
{
  "status": "success",
  "message": "Goal ended.",
  "outcome": "ended",
  "goal": {
    "id": "00000000-0000-4000-a000-000000000001",
    "text": "Find design partners",
    "scopeVersion": 3,
    "retiredAt": "2026-10-20T00:00:00.000Z",
    "endReason": null,
    "version": "00000000-0000-4000-8000-000000000901"
  },
  "cancelledMatchingRunIds": [
    "00000000-0000-4000-a000-000000000002"
  ]
}
```

## Related

- [Goal editing and ending workflow](/docs/mcp/agent-guides/create-and-edit-goals)
- [`update_goal`](/docs/mcp/tools/update_goal) edits fields and never ends a goal.
