spawn_workers

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

With no annotations present, the description carries the full behavioral burden. It discloses the asynchronous execution model, side effect of creating WORKER nodes, and the fact that caps/unknown providers surface as 'refused' rather than errors. This is strong, though it does not cover every edge case such as idempotency or retry behavior.

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

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

Three tight sentences front-load the core action and then layer critical constraints. Every sentence contributes essential information: what happens, how it happens asynchronously, and what token/error behaviors to expect.

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

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

Given no output schema and no annotations, the description plus the detailed input schema gives an agent enough to invoke the tool correctly. It explains the async result routing and token requirements, though it remains silent on the immediate return shape and how to later consume the recorded STRUCTURED_RESULTs.

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

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

The description adds meaning around token exclusivity, which is useful because the schema does not mark the tokens as mutually exclusive. However, it does not explain the workers array structure, workflow_id role, or binding_token semantics beyond what the schema already provides, and schema coverage is moderate at 67%.

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

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

The description opens with a specific verb and target ('Fan out to configured local providers') and further clarifies it creates WORKER nodes in spawn_state='requested'. This clearly distinguishes it from sibling tools like register_worker or list_spawned by focusing on the asynchronous fan-out action.

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

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

It gives clear context: this tool spawns workers asynchronously, and it states the token prerequisite ('Requires exactly one of spawn_token or child_token'). It does not explicitly name alternative tools or when-not-to-use conditions, but the behavior is specific enough that an agent can infer when to select it.

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