Browse docscreate_goal
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 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.
For your own goal, omit beneficiaryPersonId. For someone else, use 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 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.
Call 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. 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, 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. Errors use the common contract.
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 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:
{
"text": "Find design partners",
"additionalContext": "Synthetic private details"
}
Example response (synthetic data):
{
"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):
{
"text": "Find experienced startup advisors",
"beneficiaryPersonId": "00000000-0000-4000-a000-000000000004",
"audience": []
}