# `get_goal`

Reads one goal: its wording, versions, audience, and search state.

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

## When to use it

- Before any write, to get the current `scopeVersion` and `contextRevisionId`.
- To see which groups a goal is shared with, and whether it's hidden from any.
- To follow a search: `matching.run` shows its status and progress.
- To read a fellow member's goal shared with one of your groups, using its ID from [`get_group_details`](/docs/mcp/tools/get_group_details).

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `goalId` | yes | string | Goal UUID from [`list_goals`](/docs/mcp/tools/list_goals), [`get_group_details`](/docs/mcp/tools/get_group_details), or an earlier result |

## Returns

`{ "workspace": ... }`:

| Field | Type | Description |
| --- | --- | --- |
| `goal` | object | The goal, with the [`list_goals`](/docs/mcp/tools/list_goals) fields. On someone else's goal, `additionalContext` is empty and `clarificationQuestion` is null. |
| `isOwner` | boolean | You own this goal |
| `selectedGroups` | list | `{ publicId, name, hidden }` for each selected group you belong to. `hidden` is only ever true for the owner. |
| `availableGroups` | list | Owner only: every group the goal could be shared with |
| `growthGroups` | list | Owner only: your groups, each with whether the goal is shared there (`isShared`), how many more networks sharing would add (`addedNetworkCount`), and who moderates it |
| `matching` | object | Owner only: `run`, the current search, plus `requesterMatches` and `ownNetworkMatches`. On someone else's goal, `run` is null and both lists are empty. |
| `searchQueued` | boolean | Owner only: Gravity will search this goal on its own shortly. Don't start a search while it's true. |
| `brokerableGoals` | list | On someone else's goal: people in your own Rolodex who could help with it |
| `chatThreadId` | string or null | On someone else's goal: your conversation with its owner about it, if there is one |

`matching.run` describes the search for the goal's current version. It's `null` if the goal changed and hasn't been searched since.

| Field | Description |
| --- | --- |
| `runId` | Search ID |
| `status` | `running`, `complete`, `failed`, or, rarely, `cancelled` |
| `stage` | `planning`, `searching`, or null |
| `searchProgress` | While running: `estimatedPercent` (at most 99), `completedNetworks`, and `totalNetworks`. Otherwise null. |
| `coverage` | `searchedMemberCount` and `groupMemberCount` |
| `eligibleMembers` | Members whose networks are new or updated since the last search. A `new-members` search covers them. |
| `failedMembers` | Members whose networks couldn't be searched last time. A `failed-networks` search retries them. |
| `fitPeopleCount` | How many people the search found |
| `error` | "The introduction search could not be completed." when the search failed, otherwise null |
| `startedAt`, `completedAt`, `updatedAt` | ISO 8601 timestamps |
| `goalScopeVersion`, `goalContextRevisionId` | The goal version this search covered |

`matching.requesterMatches` and `matching.ownNetworkMatches` include email addresses for connectors and for your own contacts. To show matches, use [`get_goal_matches`](/docs/mcp/tools/get_goal_matches), which returns a narrower view.

`workspace` is `null` when the goal doesn't exist, you can't read it, or the ID is malformed. You can read your own ended goal by its ID. Someone else's ended goal is readable only if you already have a conversation about it.

## Example

```json get_goal
{ "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b" }
```

Trimmed result:

```json
{
  "workspace": {
    "goal": {
      "id": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
      "text": "Meet seed investors who back developer tools.",
      "additionalContext": "Raising $2M. 40 paying teams.",
      "contextRevisionId": "c2d3e4f5-a6b7-4c8d-b9e0-f1a2b3c4d5e6",
      "scopeVersion": 3,
      "clarificationQuestion": null,
      "isOwner": true
    },
    "isOwner": true,
    "selectedGroups": [
      { "publicId": "3a9f0c6e1b2d4e5f8a7b6c5d4e3f2a1b", "name": "Founders dinner", "hidden": false }
    ],
    "matching": {
      "run": {
        "runId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
        "status": "running",
        "stage": "searching",
        "searchProgress": { "estimatedPercent": 40, "completedNetworks": 2, "totalNetworks": 5 },
        "eligibleMembers": [],
        "failedMembers": []
      }
    },
    "searchQueued": false
  }
}
```

## Related

- [`save_goal`](/docs/mcp/tools/save_goal) uses the versions this tool returns.
- [Matches and searches](/docs/mcp/concepts/matches) explains search statuses.