# 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

Use [`list_groups`](/docs/mcp/tools/list_groups) to resolve groups the member named. Ask only when the requested audience is ambiguous. 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. Save the requested action

Show the wording and audience. A clear request authorizes that action; ask only for a missing consequential choice. 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 no search. Call `start_goal_matching` separately when the member asked to search.

If the call times out without a result, retry once with the original `requestId` and identical arguments. This returns `no_change` if the requested state is already present, or `version_conflict` with current state if the goal has changed. Then read the goal, whose ID is the original request ID. Follow [Errors and limits](/docs/mcp/errors-and-limits).

## 4. Edit it later

1. Resolve the exact owned goal. Read `get_goal` when you need its current wording, audience, private details, or a version precondition.
2. Supply only fields the member asked to change and a new `requestId`. Omitted fields stay unchanged; a supplied audience is the complete replacement list.
3. An optional `expectedVersion` constrains the edit to the complete state you read. Optional scope/context versions constrain matching inputs. No prior read is universally required.

```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"
}
```

For `version_conflict`, the edit changed nothing. Read the goal again, explain any relevant concurrent change, and prepare a revised action with current versions and a new `requestId`. Ask only if the revised action needs a consequential choice the member has not authorized.

## 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

`goal.version` is an opaque token for complete editable state, including visibility. `scopeVersion` changes when matching inputs change; `contextRevisionId` identifies wording/private details. These serve optional preconditions and describe search inputs.

On retry, matching supplied fields return `no_change`; an already-applied request whose desired state now differs returns `version_conflict` and current state. Explain the present state and reconcile the member's intent before preparing a new action. Use a new request ID for changed arguments. See [Errors and limits](/docs/mcp/errors-and-limits).

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.