# `start_goal_matching`

Starts a background search for one of your goals.

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

## When to use it

Only when you're asked to search. Before starting:

- Read the goal with [`get_goal`](/docs/mcp/tools/get_goal) and pass its versions.
- Don't start one while `matching.run.status` is `running` or `searchQueued` is true.
- Don't start one right after [`save_goal`](/docs/mcp/tools/save_goal). Saving already starts a search when it's needed.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `goalId` | yes | string | UUID of a goal you own |
| `goalScopeVersion` | yes | integer | `goal.scopeVersion` from your latest [`get_goal`](/docs/mcp/tools/get_goal) |
| `goalContextRevisionId` | yes | string | `goal.contextRevisionId` from your latest [`get_goal`](/docs/mcp/tools/get_goal) |
| `mode` | no | string | `full` (the default), `new-members`, or `failed-networks` |
| `requestId` | yes | string | A new UUID for this action. Reuse it only to retry this exact call. |

## Modes

| Mode | Searches | Existing matches |
| --- | --- | --- |
| `full` | Every searchable network the goal's audience covers, including yours | If the goal was searched before, matches nobody has acted on are replaced. Requested, dismissed, and connector-suggested matches stay. |
| `new-members` | Networks not yet searched for this version of the goal, networks with new information, and networks whose last search failed. With none, it completes at once with nothing new. | Matches nobody has acted on from those networks are replaced |
| `failed-networks` | Only networks left unfinished by a failed search | Kept |

If the goal's latest search failed, any mode retries the unfinished networks. If a search is already running for this version, you get that search's ID and nothing new starts.

## Returns

`{ "status", "message", "matchingRunId" }`. Success means the search started, not that it finished.

| Message | Status | Meaning |
| --- | --- | --- |
| "The search is available in your goal." | `success` | The search started, or was already running. Follow it as described below. |
| "The search is available in your goal." | `error` | This `requestId` belongs to a search that failed. Read the goal to see what failed. |
| "This goal changed or is unavailable. Read it again before searching." | `error` | Nothing started. The goal changed since you read it, it ended or isn't yours, it has an open clarification question, or `failed-networks` found nothing to retry. |
| "The search could not be started. Retry it in your goal." | `error` | The search couldn't start, or this `requestId` belongs to a different goal. Read the goal before retrying. |
| "A current goal is required." | `error` | The arguments didn't validate. |

## Following the search

Check every 30 to 60 seconds with [`get_goal`](/docs/mcp/tools/get_goal) (`matching.run`) or [`get_goal_matches`](/docs/mcp/tools/get_goal_matches) (`search`):

- `running`: still going. `searchProgress` shows how far along it is.
- `complete`: read the matches. If `failedMembers` isn't empty, offer a `failed-networks` retry.
- `failed`: say the search couldn't be completed, and offer a `failed-networks` retry.
- No search (`null`): the goal changed since you started. Read it again.

If it still shows `running` and its progress hasn't moved for about 15 minutes, stop checking and let the member know they can follow it on the goal in Gravity.

## Example

```json start_goal_matching
{
  "goalId": "6f1c2a3e-4b5d-4e6f-8a7b-9c0d1e2f3a4b",
  "goalScopeVersion": 3,
  "goalContextRevisionId": "c2d3e4f5-a6b7-4c8d-b9e0-f1a2b3c4d5e6",
  "mode": "new-members",
  "requestId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"
}
```

Result:

```json
{ "status": "success", "message": "The search is available in your goal.", "matchingRunId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a" }
```

## Related

- [Matches and searches](/docs/mcp/concepts/matches) explains modes and statuses.
- [Find matches and search again](/docs/mcp/guides/find-matches) shows the whole flow.