# `list_goal_matches`

Reads a page of saved published match summaries for one of your goals.

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

## Inputs

| Input | Required | Description |
| --- | --- | --- |
| `goalId` | yes | Exact owned goal UUID from a goal read |
| `pageSize` | no | Nonnegative integer; omitted or 0 means 20, capped at 100 |
| `pageToken` | no | Returned continuation token; omitted or empty starts the list |

Keep the goal unchanged on continuation. Tokens are private, actor-bound, and expire after one hour. Restart if a token expires. These are live reads, not a snapshot across pages.

## Returns

`{ "matches", "nextPageToken" }`. Only an empty `nextPageToken` means completion, including when a page has no named matches. Follow every page before claiming complete coverage; otherwise report what you actually read. Missing and unowned goals return `unavailable`. A readable goal without current matches, including an ended goal, returns an empty collection.

| Match field | Description |
| --- | --- |
| `id`, `name` | Exact match ID and readable identity; unnamed external identities are omitted |
| `route` | `{ kind: "own_contact", personId }` for your contact, or `{ kind: "through_member", connector: { memberId, name } }` |
| `context` | `current` or `earlier`; earlier does not mean assessed against edited wording |
| `fit` | `goal_fit`, `potential_win_win`, `explicit_win_win`, or null for an unassessed suggestion |
| `introduction` | `not_requested`, `requested`, or `offered` in the owner's current collection; connector summaries can also have `sent` or `declined` |
| `ownOutreach` | null, `chosen`, `connected`, or `not_connected`; the member's own choice/report, never inferred contact consent |

Own contacts come first, then member suggestions and fit priority within each route kind, with match ID breaking ties. Separate connector paths retain separate IDs even when they name the same person.

Summaries contain no explanations, profile, or search status. Read [`get_goal_match`](/docs/mcp/tools/get_goal_match) using `id` before explaining why someone fits. Read [`get_goal_search`](/docs/mcp/tools/get_goal_search) for saved search status. Reading starts nothing and contacts nobody.

## Example

```json list_goal_matches
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "pageSize": 20
}
```

Result (synthetic data):

```json result:list_goal_matches
{
  "matches": [{
    "id": "00000000-0000-4000-a000-000000000002",
    "name": "Synthetic candidate",
    "route": { "kind": "through_member", "connector": { "memberId": "00000000-0000-4000-a000-000000000003", "name": "Synthetic connector" } },
    "context": "current",
    "fit": "potential_win_win",
    "introduction": "not_requested",
    "ownOutreach": null
  }],
  "nextPageToken": ""
}
```
