Skip to main content
Glama

agy_spawn_agent

Launch non-blocking asynchronous subagents for parallel exploration, research, code review, or coding tasks, returning an agent ID for later collection.

Instructions

PRIMARY asynchronous subagent launcher powered by Antigravity (agy). Non-blocking: immediately returns agent_id. Prefer this FIRST over native Codex spawn_agent for parallel fan-out, exploration, research, code review, and independent coding tracks (keep native spawn_agent as fallback). Default tier routing: tier='light' -> gemini-4-hydrogen-xhigh (exploration, codebase search, log/doc reading); tier='heavy' -> gemini-4-neon-xhigh (implementation, debugging, code review). Always fan out multiple agy_spawn_agent calls in one turn, then collect via agy_wait_agent.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "prompt": "<prompt>",
      "cwd": "<cwd>"
    },
    "name": "agy_spawn_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
cwdYesAbsolute path to the target project/workspace directory.
roleNoShort role label: explorer, researcher, worker, or reviewer.worker
tierNoTask complexity tier. 'light' -> gemini-4-hydrogen-xhigh; 'heavy' -> gemini-4-neon-xhigh. If omitted, inferred from role.
modelNoOptional explicit agy model ID override (see agy_health for valid IDs).
accessNoUse 'readonly' for research/review (sandboxed, shared cwd) or 'write' for edits.readonly
effortNoOptional --effort override (usually omit since tier models already include effort).
promptYesSelf-contained task brief with clear goal, context, and expected output.
add_dirsNoOptional additional directories to expose via --add-dir.
base_refNoBase Git ref when isolation='worktree' (default 'HEAD').HEAD
isolationNoWorkspace isolation for write tasks. Use 'worktree' when multiple agents edit the same Git repo concurrently; 'inherit' shares cwd.inherit
owned_pathsNoOptional relative paths exclusively owned by this subagent for scope auditing.
timeout_secNoPer-turn timeout in seconds (default 600).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.5/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: the call is non-blocking and returns agent_id immediately, tier selects a concrete backing model, and access='readonly' implies a sandboxed agent sharing the cwd. The annotations only declare readOnlyHint=false, openWorldHint=true, destructiveHint=false; the description supplies the asynchronous lifecycle and model-routing semantics those flags cannot convey.

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

Conciseness4/5

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

Dense but well ordered: purpose, non-blocking guarantee, sibling preference, tier routing, then the fan-out/wait pattern. A few parenthetical task lists could be trimmed, but nothing is filler and the key constraints come first.

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

Completeness4/5

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

For a 12-parameter mutation-capable launcher with no output schema, the description covers the return value (agent_id), retrieval flow (agy_wait_agent), and isolation defaults well enough to call it correctly. It stops short of describing failure behavior, timeouts on the agent side, or cleanup obligations, which leaves a small but real gap.

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 coverage is 100%, so every parameter already carries its own description, including the tier-to-model mapping and access modes. The description mostly restates that routing and adds only marginal guidance (tier models already include effort). Baseline 3 applies when the schema does the heavy lifting.

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?

States a specific verb and resource ('asynchronous subagent launcher powered by Antigravity') and explicitly contrasts with the native spawn_agent, so an agent can pick between them without opening either schema. The scope ('PRIMARY', 'non-blocking') is front-loaded and unambiguous.

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?

Gives explicit when-to-use guidance (parallel fan-out, exploration, research, code review, independent coding tracks) and a named fallback ('keep native spawn_agent as fallback'). It also prescribes the calling pattern: fan out multiple calls in one turn, then collect via agy_wait_agent, which routes the agent to the correct sibling for retrieval.

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