# `get_goal_matches`

Reads the saved matches for one of your goals.

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

## When to use it

When you're asked who Gravity found for a goal. It reads matches that already exist. It starts no search and contacts nobody.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `goalId` | yes | string | UUID of a goal you own |

## Returns

`{ "goal", "search", "matches" }`:

| Field | Type | Description |
| --- | --- | --- |
| `goal` | object or null | `{ id, text }`. Null when you don't own the goal, it doesn't exist, or the ID is malformed. |
| `search` | object or null | `{ runId, status, searchedMemberCount, groupMemberCount }` for the search of the goal's current version. Null if the goal changed since it was last searched, or has ended. |
| `matches` | list | Your own contacts first, then matches through each connector, strongest first |

Each match has:

| Field | Type | Description |
| --- | --- | --- |
| `proposalId` | string | Match ID |
| `name` | string | The person's name. For your own contact without a saved name, their email address. Through a connector, "Potential connection" when no reliable name is known. |
| `route` | string | `people_you_know` for your own contact, or `through_member` when a fellow member could introduce you |
| `connectorName` | string or null | The member who could introduce you. Null for your own contacts. |
| `personId` | string or null | The person's ID in your Rolodex, for your own contacts. Null otherwise. |
| `headline`, `currentRole`, `linkedInUrl` | string or null | Public LinkedIn information, for matches through a connector |
| `summary` | string or null | Who the person is |
| `howTheyCouldHelp` | string or null | Why they could help with your goal |
| `whatYouCouldOffer` | string or null | Why meeting could be useful to them |
| `valueToYou`, `valueToThem` | string or null | Fit in each direction: `borderline_yes`, `clear_yes`, or `strong_yes` |
| `fitTier` | string or null | `goal_fit`, `potential_win_win`, or `explicit_win_win` |
| `goalContextStatus` | string | `current`, or `earlier` when the match was found for a previous version of the goal. `assessedGoalText` then holds that version's wording. |
| `connectorSuggestion` | string or null | When a connector suggested this person themselves, their reason |
| `introductionRequested` | boolean | You've already asked the connector for this introduction |

A match through a connector never includes the person's contact details, the connector's relationship with them, or how the connector knows them.

## Example

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

Result:

```json
{
  "goal": { "id": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b", "text": "Meet seed investors who back developer tools." },
  "search": { "runId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "status": "complete", "searchedMemberCount": 5, "groupMemberCount": 6 },
  "matches": [
    {
      "proposalId": "8e7d6c5b-4a39-4281-9f0e-1d2c3b4a5968",
      "goalContextStatus": "current",
      "assessedGoalText": "Meet seed investors who back developer tools.",
      "name": "Jordan Example",
      "route": "through_member",
      "connectorName": "Sam Rivera",
      "personId": null,
      "headline": "Partner at an early-stage fund",
      "currentRole": "Partner",
      "linkedInUrl": "https://www.linkedin.com/in/jordan-example",
      "summary": "Early-stage investor focused on infrastructure software.",
      "howTheyCouldHelp": "Leads seed rounds in developer tools.",
      "whatYouCouldOffer": "An early look at a growing developer-tools company.",
      "valueToYou": "strong_yes",
      "valueToThem": "clear_yes",
      "fitTier": "explicit_win_win",
      "connectorSuggestion": null,
      "introductionRequested": false
    }
  ]
}
```

When presenting a match, say what it is: "Gravity found a possible match through Sam." Don't say Sam can introduce you or that Jordan wants to meet. To ask for an introduction, open the goal in Gravity.

## Related

- [Matches and searches](/docs/mcp/concepts/matches) explains routes and searches.
- [`start_goal_matching`](/docs/mcp/tools/start_goal_matching) starts a new search.