Skip to content
Browse docsget_goal

get_goal

Reads an authorized goal in Basic or Full view. Basic contains content and audience; Full adds match assessments. Reading changes nothing.

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

When to use it#

Read an exact goal when it has not already been supplied by a goal list. Use view: "full" when match reasons are needed; otherwise use Basic, the default. List and Get share the same goal resource and view choices. Search diagnostics, available groups, and offer controls remain separate reads.

Inputs#

InputRequiredTypeDescription
viewnostringbasic (default) or full
goalIdyesstringExact goal UUID from an authorized list or retained reference

Returns#

The goal directly: id, text, owner (memberId, nullable name), beneficiary, authorship, version, scopeVersion, suggestedByGravity, audience, createdAt, retiredAt, isOwner, additionalContext, clarificationQuestion, and endReason. MCP also adds its exact Gravity link.

audience contains authorized groupPublicId, name, and visibility (visible or hidden) pairs. Only the owner receives hidden visibility and private context. Other viewers receive null for version, additionalContext, clarificationQuestion, and endReason. Audience names follow current group membership and visibility; a direct conversation does not reveal unrelated groups.

authorship, when present, contains the drafting member's memberId, name, and a threadId only for participants. Ownership does not establish authorship. No author's private source goal is returned.

version is the owner-only opaque precondition for edits and ending. Copy it unchanged as expectedVersion. It changes with content, audience visibility, beneficiary reconciliation, and lifecycle, but not display names or search progress. scopeVersion remains the numeric matching-input revision; visibility-only edits leave it unchanged. Create/Update success receipts contain the base owned goal content under goal, captured inside the save transaction; they do not fetch matches or search diagnostics. Known write rejections can still include a separate currentState snapshot.

Missing and inaccessible goals return unavailable. The owner can read ended history. A shared ended goal requires both current visibility authorization and an existing goal conversation. Reading never loads a workspace, reconciles a search, or schedules work.

Full adds matches: { matches: [...], nextPageToken }, with up to 20 currently authorized assessments in the same shape as get_goal_match. Owned goals include the owner's published matches; another member's goal includes only your own connections. Ended goals have an empty match page. Basic omits matches entirely and performs no matching reads.

A nonempty match token continues with list_goal_matches for an owned goal or list_goal_connections for another member's goal. Those continuation pages contain summaries; read get_goal_match for their reasons. Only an empty token establishes completion, including after an empty page.

Use get_goal_search for saved search status and coverage. Use list_groups and get_group for audience options. Reading a goal never reads a workspace, network previews, or setup workflow state.

Example#

json
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "view": "full"
}

Result (synthetic data):

json
{
  "id": "00000000-0000-4000-a000-000000000001",
  "text": "Find design partners",
  "beneficiary": null,
  "authorship": null,
  "owner": {
    "memberId": "00000000-0000-4000-a000-000000000003",
    "name": "Synthetic member"
  },
  "additionalContext": "Synthetic private details",
  "clarificationQuestion": null,
  "scopeVersion": 2,
  "version": "00000000-0000-4000-8000-000000000901",
  "suggestedByGravity": false,
  "retiredAt": null,
  "endReason": null,
  "createdAt": "2026-10-09T00:00:00.000Z",
  "isOwner": true,
  "audience": [
    {
      "groupPublicId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "name": "Synthetic founders",
      "visibility": "hidden"
    }
  ],
  "matches": {
    "matches": [],
    "nextPageToken": ""
  }
}