Skip to content
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 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#

InputRequiredTypeDescription
goalIdyesstringUUID of a goal you own
expectedScopeVersionnointegerscopeVersion from your latest get_goal_search
modenostringnew-members (the default), full, or failed-networks

Modes#

ModeSearchesExisting matches
new-membersNetworks 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
fullEvery 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-networksOnly networks left unfinished by a failed searchKept

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.

ResultMeaning
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_conflictThe goal changed since the read. Nothing started; read its current scope version.
clarification_requiredThe goal needs an answer before searching. Nothing started; read and clarify the goal.
unavailableThe goal is ended, missing, or inaccessible. Nothing started; resolve from current owned goals.
request_rejectedThe requested mode is not applicable. Nothing started; inspect current goal/search state.
operation_failedSearch 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.

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. 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
{
  "goalId": "00000000-0000-4000-a000-000000000001",
  "mode": "new-members",
  "expectedScopeVersion": 2
}

Result (synthetic data):

json
{
  "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
}