# Create and edit a goal

Create a goal with the right audience and private details, then change it safely. Do this only when you're asked to.

This is the agent workflow. The [member guide](/docs/mcp/guides/create-and-edit-goals) gives examples of what to ask.

## 1. Choose the audience

Call [`list_groups`](/docs/mcp/tools/list_groups) and ask which groups should read the goal. The default is none, which keeps the goal private.

Say plainly who will read it before saving. For example: "Founders dinner's 7 members will see this goal."

## 2. Write the two parts

- **`text`** is the goal the selected groups read: the outcome and the kind of person who could help, in words the member is comfortable sharing with those groups.
- **`additionalContext`** is the private details: confidential specifics that help Gravity find matches, read only by the member.

Don't invent details, and don't repeat the goal in the private details. See [Goals and audiences](/docs/mcp/concepts/goals).

## 3. Confirm, then save

Show both parts and the audience. When the member agrees, call [`save_goal`](/docs/mcp/tools/save_goal) with `goalId: null`, `expectedScopeVersion: null`, and a new `requestId`.

```json save_goal
{
  "goalId": null,
  "text": "Meet seed investors who back developer tools.",
  "selectedGroupPublicIds": ["3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b"],
  "expectedScopeVersion": null,
  "additionalContext": "Raising $2M at a $12M cap. 40 paying teams, $18k monthly revenue. Two angels committed.",
  "requestId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}
```

Saving starts a search. You don't need to start one.

If the call times out without a result, retry once with the same `requestId` and identical arguments. You'll get the original result back, not a second goal.

## 4. Edit it later

1. Call [`get_goal`](/docs/mcp/tools/get_goal) to get the current `scopeVersion`, `contextRevisionId`, and selected groups.
2. Call [`save_goal`](/docs/mcp/tools/save_goal) with the goal's ID, its current `scopeVersion`, the complete group list, and a new `requestId`.
3. To change private details, pass all of them in `additionalContext`, plus `expectedContextRevisionId`. To keep them, leave both out.

```json save_goal
{
  "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
  "text": "Meet Series A investors who back developer tools.",
  "selectedGroupPublicIds": ["3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b"],
  "expectedScopeVersion": 3,
  "requestId": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f"
}
```

If the result is "This goal or its audience changed or is unavailable", the goal changed since you read it. Read it again, show the member what changed, and ask before saving with a new `requestId`.

## Keep private details private

Never copy `additionalContext` into the goal's `text`, a message to a group, or a note to a connector, unless the member asks for that exact detail to be shared.

## Version checks and retries

Every goal has two version values. `scopeVersion` changes when its wording, private details, or selected groups change. `contextRevisionId` changes when its wording or private details change. Read the exact goal before a write and again afterward; pass the values from the latest read so a concurrent change is rejected rather than overwritten.

Use a new UUID `requestId` for each requested action. Retry only the identical action with its original ID and identical arguments. If you reread a changed goal and prepare a revised action, confirm the change with the member and use a new request ID. See [Errors and limits](/docs/mcp/errors-and-limits) for partial saves and transport failures.

An explicitly empty `text` ends a goal and archives its introduction chats. Never send empty or whitespace-only wording for an ordinary edit. Ending is irreversible and requires the member's explicit request; the goal can't be reopened.