# `create_goal`

Creates a new goal you own, for yourself or someone in your Rolodex. Saving starts no search.

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

## When to use it

Only when asked to create a goal. Before suggesting a new goal, check relevant existing goals with [`list_goals`](/docs/mcp/tools/list_goals) and their saved matches to avoid duplicates. An explicit request for a fresh goal does not require surveying unrelated goals. To change an existing goal, use [`update_goal`](/docs/mcp/tools/update_goal).

For your own goal, omit `beneficiaryPersonId`. For someone else, use [`list_people`](/docs/mcp/tools/list_people) filtered by the supplied name or email to resolve the exact person in your own Rolodex, then pass their `personId` as `beneficiaryPersonId`. Clarify ambiguous matches. If no entry matches the name as given, offer to create their profile with [`create_person`](/docs/mcp/tools/create_person) first; once authorized and saved, use its returned `personId`. Never choose a similar name or silently create a goal for yourself instead.

You own the goal in either case, and whom it is for stays fixed after creation. The beneficiary need not be a Gravity member. Creating the goal sends nothing and creates no goal in their account.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `text` | yes | string | Nonblank shared wording, up to 2,000 characters. |
| `audience` | no | list of objects | Up to 100 distinct authorized groups, each with `groupPublicId` and `visibility` (`visible` or `hidden`). Omit or use `[]` to keep it private. |
| `additionalContext` | no | string | Private details only you and Gravity see, up to 4,000 characters. |
| `beneficiaryPersonId` | no | string | Exact UUID of a named, available person in your own Rolodex. Omit for yourself. Fixed after creation; goals for someone else require an empty or omitted audience. |

Write `text` as the outcome and the kind of person who could help, keeping confidential matching details in `additionalContext`. For someone else, state their desired outcome in the imperative without naming them or using pronouns for them, such as "Find experienced startup advisors." Matching loads their background from your Rolodex, so do not paste their profile into private details.

Your own goal defaults private; include only groups you chose in `audience`. `visible` lets the selected group's members read the wording, while `hidden` includes its network in an authorized search without showing the goal in that group. State who will read the wording before sharing it. A goal for someone else always stays private and searches only your network, so omit `audience` or use `[]`. See [Goals and audiences](/docs/mcp/concepts/goals).

Call [`start_goal_search`](/docs/mcp/tools/start_goal_search) separately when the member asks for a search.

## Returns

Success returns `status`, `outcome`, `message`, the canonical owned `goal`, and `cancelledSearchIds`, the same shape as [`update_goal`](/docs/mcp/tools/update_goal). MCP also adds the goal's exact Gravity `link`. Creation returns `outcome: "saved"` and an empty `cancelledSearchIds` array. The `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 its opaque `version`, numeric `scopeVersion`, private details, and audience. The receipt contains no search state or matches.

If you already have an active goal for the same beneficiary (yourself when omitted) with the same wording, ignoring case and spacing, nothing is created. The result is a `request_rejected` error whose `currentState` contains that goal and its authorized selected groups; change it with [`update_goal`](/docs/mcp/tools/update_goal). Errors use the [common contract](/docs/mcp/errors-and-limits).

Each MCP call gets a fresh request identity. No caller retry key or replay guarantee is exposed. After a timeout or another uncertain response, read [`list_goals`](/docs/mcp/tools/list_goals) and the relevant `get_goal` before considering another create. Duplicate-wording rejection does not guarantee a safe retry if the earlier goal has since changed or ended.

## Examples

Create a private goal:

```json create_goal
{
  "text": "Find design partners",
  "additionalContext": "Synthetic private details"
}
```

Example response (synthetic data):

```json result:create_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": 1,
    "suggestedByGravity": false,
    "retiredAt": null,
    "createdAt": "2026-10-09T00:00:00.000Z",
    "endReason": null,
    "authorship": null,
    "version": "00000000-0000-4000-8000-000000000901",
    "owner": {
      "memberId": "00000000-0000-4000-a000-000000000003",
      "name": "Synthetic member"
    },
    "isOwner": true,
    "audience": []
  },
  "cancelledSearchIds": [],
  "link": "https://www.meetgravity.ai/dashboard/goals/00000000-0000-4000-a000-000000000001"
}
```

Create a goal for the exact person resolved from your Rolodex (synthetic ID):

```json create_goal
{
  "text": "Find experienced startup advisors",
  "beneficiaryPersonId": "00000000-0000-4000-a000-000000000004",
  "audience": []
}
```

## Related

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