Browse docsstart_goal_search
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
expectedScopeVersionconstrains that snapshot. - Don't start one while
run.statusfromget_goal_searchisrunningorqueuedBySetupis 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 |
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, 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 (run):
running: still going.progressshows how far along it is.complete: read the matches. IffailedNetworkCountis positive, offer afailed-networksretry.failed: say the search couldn't be completed, and offer afailed-networksretry.- 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#
{
"goalId": "00000000-0000-4000-a000-000000000001",
"mode": "new-members",
"expectedScopeVersion": 2
}
Result (synthetic data):
{
"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 explains searches for members.
- Matching workflow shows the whole tool flow.