pi_send

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

With no annotations, the description carries the full behavioral burden, and it delivers real value: the worker's Pi process — or its saved session after 30 idle minutes — retains prior context, and the caller should send only the new instruction. It does not disclose the consequence of calling while the worker is running, nor whether the send blocks or returns immediately.

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 front-loaded sentences with no filler; the purpose and the re-spawn contrast come first. The parenthetical about the 30-minute saved session is dense but earns its place by explaining the retention guarantee.

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?

No output schema and no annotations, so the description must stand alone — it covers purpose, precondition, context retention, and message framing. It omits the failure behavior when the worker is running and what the call returns, which are the remaining operational gaps.

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?

Schema coverage is 75% and already documents id, effort, and maxMinutes. The description adds genuine meaning for the undocumented 'message' parameter — 'Send only the new instruction; it already has the background' — telling the caller not to restate context.

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?

States a specific verb (send a follow-up message) and resource (a finished worker), and explicitly contrasts with the sibling pi_spawn ('instead of re-spawning'). An agent can route between pi_send and pi_spawn without opening either schema.

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?

Names the alternative ('instead of re-spawning') and the conditions that select this tool: 'for fixes and for the next task in the same area'. It also states the precondition plainly — 'The worker must not be running.'

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