AgentNave

Overview Schema Source Related Servers Discussions Admin

Wait for a subagent invocation

wait_agent

Read-onlyIdempotent

Wait for an agent invocation to complete or hit an execution blocker, returning early with the latest reply and its age. Continue waiting by calling again with the same ID.

Instructions

Wait for a fixed window of five minutes; completion or an explicit CLI execution blocker returns early.

Running responses include the latest public reply tail (at most 1000 characters) and its age. execution_blocked leaves the CLI running: continue waiting or cancel with the same ID. Each blocker category wakes once per invocation. Ordinary tool failures, transient retries, and silence are not proof the task cannot proceed. Finished responses contain the final reply. Wait expiry leaves the invocation running. Call again with the same ID to continue. This is request/response waiting, not a background notification subscription.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`invocation_id`	Yes	Invocation ID returned by start_agent.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`error`	No
`output`	No
`reason`	Yes
`status`	Yes
`activity`	No
`elapsed_ms`	Yes
`session_id`	No
`invocation_id`	Yes
`output_age_ms`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.9.0Sep 10, 2026

removedInput schema / properties / wait_timeout_seconds

Removed value: -{
-  "default": 600,
-  "description": "Seconds to wait for this response; expiry leaves the invocation running.",
-  "exclusiveMinimum": 0,
-  "maximum": 600,
-  "title": "Wait Timeout Seconds",
-  "type": "number"
-}

changedOutput schema / properties / status / enum

Previous value: -[
-  "running",
-  "succeeded",
-  "failed",
-  "blocked",
-  "cancelled",
-  "timed_out"
-]New value: +[
+  "running",
+  "succeeded",
+  "failed",
+  "blocked",
+  "cancelled"
+]

Changed24 schema fields changedv0.7.0Sep 9, 2026

changedInput schema / properties / wait_timeout_seconds / default
```
Previous value: -30New value: +600
```
changedInput schema / properties / wait_timeout_seconds / maximum
```
Previous value: -300New value: +600
```

addedOutput schema / $defs / ActivityPayload

Added value: +{
+  "properties": {
+    "age_ms": {
+      "title": "Age Ms",
+      "type": "integer"
+    },
+    "kind": {
+      "title": "Kind",
+      "type": "string"
+    },
+    "state": {
+      "title": "State",
+      "type": "string"
+    },
+    "tool_name": {
+      "title": "Tool Name",
+      "type": "string"
+    }
+  },
+  "required": [
+    "kind"
+  ],
+  "title": "ActivityPayload",
+  "type": "object"
+}

removedOutput schema / $defs / InvocationErrorPayload / properties / details

Removed value: -{
-  "anyOf": [
-    {
-      "type": "string"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "title": "Details"
-}

changedOutput schema / $defs / InvocationErrorPayload / required

Previous value: -[
-  "code",
-  "message",
-  "details"
-]New value: +[
+  "code",
+  "message"
+]

removedOutput schema / $defs / InvocationPhaseName

Removed value: -{
-  "enum": [
-    "preparing",
-    "running",
-    "stopping"
-  ],
-  "type": "string"
-}

removedOutput schema / $defs / InvocationResultPayload

Removed value: -{
-  "properties": {
-    "duration_ms": {
-      "title": "Duration Ms",
-      "type": "integer"
-    },
-    "error": {
-      "anyOf": [
-        {
-          "$ref": "#/$defs/InvocationErrorPayload"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
-    "output": {
-      "title": "Output",
-      "type": "string"
-    },
-    "provider": {
-      "$ref": "#/$defs/ProviderName"
-    },
-    "provider_usage": {
-      "$ref": "#/$defs/ProviderUsagePayload"
-    },
-    "session_id": {
-      "anyOf": [
-        {
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "title": "Session Id"
-    },
-    "status": {
-      "$ref": "#/$defs/InvocationStatusName"
-    }
-  },
-  "required": [
-    "status",
-    "provider",
-    "output",
-    "session_id",
-    "provider_usage",
-    "duration_ms",
-    "error"
-  ],
-  "title": "InvocationResultPayload",
-  "type": "object"
-}

removedOutput schema / $defs / InvocationSnapshotPayload

Removed value: -{
-  "properties": {
-    "elapsed_ms": {
-      "title": "Elapsed Ms",
-      "type": "integer"
-    },
-    "last_event_age_ms": {
-      "anyOf": [
-        {
-          "type": "integer"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "title": "Last Event Age Ms"
-    },
-    "phase": {
-      "$ref": "#/$defs/InvocationPhaseName"
-    }
-  },
-  "required": [
-    "phase",
-    "elapsed_ms",
-    "last_event_age_ms"
-  ],
-  "title": "InvocationSnapshotPayload",
-  "type": "object"
-}

removedOutput schema / $defs / InvocationStatusName

Removed value: -{
-  "enum": [
-    "succeeded",
-    "failed",
-    "blocked",
-    "cancelled",
-    "timed_out"
-  ],
-  "type": "string"
-}

removedOutput schema / $defs / ProviderName

Removed value: -{
-  "enum": [
-    "antigravity",
-    "claude",
-    "codebuddy",
-    "codex",
-    "grok"
-  ],
-  "type": "string"
-}

removedOutput schema / $defs / ProviderUsagePayload

Removed value: -{
-  "properties": {
-    "num_turns": {
-      "title": "Num Turns",
-      "type": "integer"
-    },
-    "total_cost_usd": {
-      "title": "Total Cost Usd",
-      "type": "number"
-    }
-  },
-  "title": "ProviderUsagePayload",
-  "type": "object"
-}

addedOutput schema / properties / activity

Added value: +{
+  "$ref": "#/$defs/ActivityPayload"
+}

addedOutput schema / properties / elapsed_ms

Added value: +{
+  "title": "Elapsed Ms",
+  "type": "integer"
+}

addedOutput schema / properties / error

Added value: +{
+  "$ref": "#/$defs/InvocationErrorPayload"
+}

addedOutput schema / properties / output

Added value: +{
+  "title": "Output",
+  "type": "string"
+}

addedOutput schema / properties / output_age_ms

Added value: +{
+  "title": "Output Age Ms",
+  "type": "integer"
+}

addedOutput schema / properties / reason

Added value: +{
+  "enum": [
+    "started",
+    "wait_elapsed",
+    "execution_blocked",
+    "finished"
+  ],
+  "title": "Reason",
+  "type": "string"
+}

removedOutput schema / properties / result

Removed value: -{
-  "$ref": "#/$defs/InvocationResultPayload"
-}

addedOutput schema / properties / session_id

Added value: +{
+  "title": "Session Id",
+  "type": "string"
+}

removedOutput schema / properties / snapshot

Removed value: -{
-  "$ref": "#/$defs/InvocationSnapshotPayload"
-}

removedOutput schema / properties / state

Removed value: -{
-  "enum": [
-    "running",
-    "finished"
-  ],
-  "title": "State",
-  "type": "string"
-}

addedOutput schema / properties / status

Added value: +{
+  "enum": [
+    "running",
+    "succeeded",
+    "failed",
+    "blocked",
+    "cancelled",
+    "timed_out"
+  ],
+  "title": "Status",
+  "type": "string"
+}

changedOutput schema / required

Previous value: -[
-  "invocation_id",
-  "state"
-]New value: +[
+  "invocation_id",
+  "status",
+  "reason",
+  "elapsed_ms"
+]

changedOutput schema / title

Previous value: -"WaitAgentPayload"New value: +"InvocationPayload"

Changed1 schema field changedv0.5.0Sep 6, 2026

changedInput schema / properties / wait_timeout_seconds / description

Previous value: -"Maximum time to wait during this call, in seconds."New value: +"Seconds to wait for this response; expiry leaves the invocation running."

Changed1 schema field changedv0.3.0Sep 3, 2026

changedOutput schema / $defs / ProviderName / enum

Previous value: -[
-  "antigravity",
-  "claude",
-  "codebuddy",
-  "grok"
-]New value: +[
+  "antigravity",
+  "claude",
+  "codebuddy",
+  "codex",
+  "grok"
+]

First observedv0.2.0Aug 31, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the annotations, disclosing the five-minute window, early-return conditions, response contents (reply tail and age), wait-expiry behavior, continuation semantics, and the fact that ordinary failures/retries/silence are not proof of failure. It also clarifies the interaction model, which is valuable non-obvious behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but every sentence carries necessary behavioral guidance. The most important facts are front-loaded: wait window, early return, and continuation behavior. There is no filler or redundant repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a wait/polling tool with one parameter, an output schema, and safety annotations, the description fully covers invocation lifecycle, return semantics, continuations, cancellation, and failure interpretation. The presence of an output schema means return values need not be enumerated in prose, and the description supplies all missing context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with the single parameter clearly described as the ID returned by start_agent. The description adds further semantics by emphasizing that the same ID is reused for continued waiting and cancellation, reinforcing that invocation_id is a stable handle across operations.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Wait'), a fixed resource ('a subagent invocation'), and a concrete duration ('five minutes'), making the tool's role unmistakable. It also distinguishes itself from sibling tools by clarifying this is 'request/response waiting' rather than a background notification subscription.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational context: call again with the same ID after expiry, continue waiting or cancel when execution_blocked, and expect early returns on completion or blockers. It does not explicitly name start_agent or cancel_agent as alternatives, though it references cancellation with the same ID, so the guidance is clear but not fully explicit about sibling routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server