# `batch_end_goals`

Ends an exact set of owned goals in one atomic operation. Searches stop and introduction chats become read-only; history is retained. Ending cannot be undone.

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

## When to use it

Use when the member explicitly asks to end several goals or all their goals. For “all,” read every page of a fresh [`list_goals`](/docs/mcp/tools/list_goals) until `nextPageToken` is empty and pass that exact set, including private goals and owned goals for other people. If the selection is incomplete or exceeds 100 goals, end none and explain the limit; never silently split the request. Lists are live, so report the selected count and actual outcomes without claiming to include later additions. For a subset, resolve its exact identities and versions from `list_goals` or [`get_goal`](/docs/mcp/tools/get_goal). An empty list needs no ending call.

Explain before acting that ending stops searches, archives introduction chats as read-only, and cannot be undone. The chat request authorizes immediate execution without a Gravity UI confirmation. Do not require a reason or infer achievement.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `requests` | yes | list of objects | Between 1 and 100 exact ending requests. Each goal may appear only once. |

Each request has the same fields as [`end_goal`](/docs/mcp/tools/end_goal): required `goalId` and `expectedVersion`, and optional `endReason`. Supply `achieved` only for a stated successful outcome or `no_longer_needed` for a stated abandoned need. Omit the reason when unstated. Reasons can differ between goals.

## Atomicity and retries

Every goal must belong to the member. Every selected active goal must still have its supplied version. The application locks the complete set and checks all preconditions before changing any goal, search, or pending proposal. A validation, ownership, or version failure ends none. A database failure rolls back the entire transaction.

Already-ended owned goals count as `no_change`, regardless of the supplied version, and keep their saved reason and retirement time. They do not prevent other selected active goals from ending. Repeating a successful batch changes nothing further. Results follow request order.

After a conflict, read the selected goals and reconcile the request. Never silently remove a conflicting goal and retry a smaller set. After an unconfirmed outcome, read before retrying; do not claim that nothing changed. The atomic guarantee covers stored lifecycle changes; notification or response failures after commit can leave the reported outcome unconfirmed.

A call accepts at most 100 goals. A larger request requires several batches, each atomic independently; explain that limit before proceeding. This tool accepts explicit identities, with no filter or “all” selector that could sweep in newly created goals.

## Returns

Success returns `status`, `message`, and `results`. Each result contains the same `outcome`, lifecycle `goal`, and `cancelledMatchingRunIds` as `end_goal`, plus its exact presentation `link`. `message` counts newly ended goals; `no_change` entries are not counted as newly ended. Full goal details remain available through `get_goal`. Errors use the [common contract](/docs/mcp/errors-and-limits), with no partial-success result.

## Example

```json batch_end_goals
{
  "requests": [
    {
      "goalId": "00000000-0000-4000-a000-000000000001",
      "expectedVersion": "00000000-0000-4000-8000-000000000901"
    }
  ]
}
```

Example response (synthetic data):

```json result:batch_end_goals
{
  "status": "success",
  "message": "Ended 1 goal.",
  "results": [
    {
      "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

- [`end_goal`](/docs/mcp/tools/end_goal) ends one owned goal.
- [Goal editing and ending workflow](/docs/mcp/agent-guides/create-and-edit-goals)
