# `start_goal_search`

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:

- Resolve the exact goal. Gravity captures its current matching inputs when accepting the search. Optional `expectedScopeVersion` constrains that snapshot.
- Don't start one while `run.status` from `get_goal_search` is `running` or `queuedBySetup` is true.
- Saving starts no search. Call this separately when the member asked to search.

## Inputs

| Input | Required | Type | Description |
| --- | --- | --- | --- |
| `goalId` | yes | string | UUID of a goal you own |
| `expectedScopeVersion` | no | integer | `scopeVersion` from your latest [`get_goal_search`](/docs/mcp/tools/get_goal_search) |
| `mode` | no | string | `new-members` (the default), `full`, or `failed-networks` |

## Modes

| Mode | Searches | Existing matches |
| --- | --- | --- |
| `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 |
| `full` | Every searchable network the goal's audience covers, including yours. Use it only when the member asks to search everything again. | If the goal was searched before, matches nobody has acted on are replaced. Requested, dismissed, and connector-suggested matches stay. |
| `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. After it completes, another explicit full search is allowed.

## Returns

`{ "status", "outcome", "message", "matchingRunId", "goalId", "goalScopeVersion" }`. The returned scope version identifies the inputs captured by that search. Success means the request was accepted or an existing run was returned, not that it finished. `outcome` is `accepted` for newly accepted work, `already_running` for running work that was reused, or `already_accepted` for a previously accepted run that is no longer running. Read saved status for completion and results. Errors use the [common error contract](/docs/mcp/errors-and-limits), with a specific code and any known `matchingRunId`. A changed goal returns `version_conflict` and owned content with authorized selected groups in `currentState`. This rejection snapshot has no search state; read `get_goal_search` for the search before retrying. A stopped search is reported without silently restarting it.

| Result | Meaning |
| --- | --- |
| `outcome: "accepted"` | New work was accepted. It may still be running. |
| `outcome: "already_running"` | The existing running search was returned. No new search started. |
| `outcome: "already_accepted"` | Previously accepted work was returned. Read its saved status and results. |
| `version_conflict` | The goal changed since the read. Nothing started; read its current scope version. |
| `clarification_required` | The goal needs an answer before searching. Nothing started; read and clarify the goal. |
| `unavailable` | The goal is ended, missing, or inaccessible. Nothing started; resolve from current owned goals. |
| `request_rejected` | The requested mode is not applicable. Nothing started; inspect current goal/search state. |
| `operation_failed` | Search acceptance could not be confirmed. Read the current search before trying again; a search that is running is returned rather than started twice. |

This MCP tool creates a new request identity for each call. It does not offer a caller-supplied retry key or guarantee replay after completion. Read `get_goal_search` after an uncertain response before calling again; a later call may start new work. Agent confirmations retain their command identity and reviewed mode for retries. Both interfaces use the application default `new-members`.

## Checking on the search

The search runs in the background. Don't wait or poll for it: report the returned acceptance outcome and include the goal's Gravity link. When the member asks how it went, read [`get_goal_search`](/docs/mcp/tools/get_goal_search) (`run`):

- `running`: still going. `progress` shows how far along it is.
- `complete`: read the matches. If `failedNetworkCount` is positive, offer a `failed-networks` retry.
- `failed`: say the search couldn't be completed, and offer a `failed-networks` retry.
- No current-scope run (`null`): no saved run is available for these current inputs. The goal may have changed; this does not establish that no earlier search occurred.

Do not claim the search completed or start a retry without a request.

## Example

```json start_goal_search
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "mode": "new-members",
  "expectedScopeVersion": 2
}
```

Result (synthetic data):

```json result:start_goal_search
{
  "status": "success",
  "outcome": "accepted",
  "message": "Your search was accepted. Open your goal to check its progress.",
  "matchingRunId": "00000000-0000-4000-a000-000000000002",
  "goalId": "00000000-0000-4000-a000-000000000001",
  "goalScopeVersion": 2
}
```

## Related

- [Matches and searches](/docs/mcp/concepts/matches) explains searches for members.
- [Matching workflow](/docs/mcp/agent-guides/find-matches) shows the whole tool flow.
