Skip to main content
Glama
TimWongUp

AgentNave

by TimWongUp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Cancel a subagent invocation

cancel_agent
DestructiveIdempotent

Stop a running agent task by its invocation ID to free up resources or regain control. Returns the final result (cancelled or already finished) without undoing any side effects already applied.

Instructions

Stop a task by invocation_id; use wait_agent to observe without stopping.

Returns the cancelled or already-finished result. Does not undo prior CLI side effects.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
invocation_idYesInvocation ID returned by start_agent.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNo
outputNo
reasonYes
statusYes
activityNo
elapsed_msYes
session_idNo
invocation_idYes
output_age_msNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.0
    • changedOutput schema / properties / status / enum
      Previous value: -[
-  "running",
-  "succeeded",
-  "failed",
-  "blocked",
-  "cancelled",
-  "timed_out"
-]New value: +[
+  "running",
+  "succeeded",
+  "failed",
+  "blocked",
+  "cancelled"
+]
  2. Changed19 schema fields changedv0.7.0
    • 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 / 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 / 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 / state
      Removed value: -{
-  "const": "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",
-  "result"
-]New value: +[
+  "invocation_id",
+  "status",
+  "reason",
+  "elapsed_ms"
+]
    • changedOutput schema / title
      Previous value: -"CancelAgentPayload"New value: +"InvocationPayload"
  3. Changed1 schema field changedv0.3.0
    • changedOutput schema / $defs / ProviderName / enum
      Previous value: -[
-  "antigravity",
-  "claude",
-  "codebuddy",
-  "grok"
-]New value: +[
+  "antigravity",
+  "claude",
+  "codebuddy",
+  "codex",
+  "grok"
+]
  4. First observedv0.2.0

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already mark the tool destructive and idempotent. The description adds meaningful context beyond that: it returns the cancelled result even if already finished and clarifies that prior CLI side effects are not rolled back. This goes beyond the annotation flags and exposes the real behavioral contract.

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?

Every sentence earns its place: the first states the action and distinguishing alternative, the second covers return behavior and side-effect scope. It is short, front-loaded, and free of filler.

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 one-parameter tool with a full input schema, an output schema, and annotations, the description covers the action, the key alternative, return behavior, and a critical side-effect limitation. Nothing needed to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, and the only parameter, invocation_id, is already documented as the ID returned by start_agent. The description mentions 'by invocation_id' but adds no extra semantic detail beyond the schema. Baseline 3 is appropriate because the schema carries the full burden.

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 opens with a specific verb and resource: 'Stop a task by invocation_id.' It directly names the sibling it is not ('use wait_agent to observe without stopping'), so an agent can clearly distinguish cancellation from observation without inspecting other tools.

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

Usage Guidelines5/5

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

The description explicitly tells the agent when to use this tool versus the main alternative: use wait_agent 'to observe without stopping.' It also adds a decision-relevant constraint, 'Does not undo prior CLI side effects,' which helps the agent choose appropriately.

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

Deploy Server

Other Tools