# `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 | `{ id, text, beneficiary? }`. A missing or unowned goal returns the common `unavailable` error. |
| `search` | object or null | `{ runId, status, stage, activities, searchProgress, searchedMemberCount, groupMemberCount, incomplete }` 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 |

`incomplete` identifies unfinished networks; `stage`, `activities`, and `searchProgress` describe the last saved progress. A readable goal with no matches returns `matches: []`; that is distinct from `unavailable`.

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 someone added this person by hand, their reason: the connector on a route through them, or you for your own contact on a goal for someone else |
| `introductionRequested` | boolean | You've already asked the connector for this introduction |
| `introductionOffered` | boolean | The connector offered an introduction that awaits your decision in Gravity |

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": "00000000-0000-4000-a000-000000000001"
}
```

Result (synthetic data):

```json result:get_goal_matches
{
  "goal": {
    "id": "00000000-0000-4000-a000-000000000001",
    "text": "Find design partners",
    "beneficiary": null
  },
  "search": {
    "status": "running",
    "stage": "searching",
    "activities": [
      "researching"
    ],
    "searchProgress": {
      "estimatedPercent": 50,
      "completedNetworks": 1,
      "totalNetworks": 2,
      "completedTurns": 3
    },
    "runId": "00000000-0000-4000-a000-000000000002",
    "searchedMemberCount": 1,
    "groupMemberCount": 2,
    "incomplete": false
  },
  "matches": [
    {
      "proposalId": "00000000-0000-4000-a000-000000000002",
      "goalContextStatus": "current",
      "assessedGoalText": "Find design partners",
      "name": "Synthetic candidate",
      "route": "through_member",
      "connectorName": "Synthetic connector",
      "personId": null,
      "headline": "Public headline",
      "currentRole": "Public role",
      "linkedInUrl": null,
      "summary": "Possible design partner",
      "howTheyCouldHelp": "Could discuss the product",
      "whatYouCouldOffer": null,
      "valueToYou": "clear_yes",
      "valueToThem": null,
      "fitTier": "goal_fit",
      "connectorSuggestion": null,
      "introductionRequested": false,
      "introductionOffered": 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.