pi_reply

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

With no annotations provided, the description carries the full behavioral burden and meets it well: it discloses session survival across timeout/cancellation, that pi retains prior turns but 'never this conversation', and that sessions survive server restarts. The schema's transport and timeout_ms descriptions add durability semantics (killed runs still return a session id and are resumable). Minor deduction for not covering what happens when a session id is invalid or expired, though the schema's reference to pi_sessions partially mitigates this.

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?

Four sentences, zero filler, and the core purpose plus most critical edge case are front-loaded in the first sentence. Each subsequent sentence earns its place: context retention, persistence, and sibling routing. Nothing is redundant with the schema.

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?

For a stateful tool with 7 parameters, no annotations, and no output schema, the definition is complete. It covers how to obtain a session id (via schema references to pi_sessions and the [session: <id>] prefix), what the timeout behavior is (resumable, returns session id), when the call returns before the turn completes (transport semantics), and how to distinguish siblings. The essential return-value behavior is disclosed through the timeout_ms description.

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 100%, so the baseline is 3; the description adds genuine parameter-level value on top. It clarifies the session parameter's semantics (timed-out/cancelled sessions are still valid targets) and the prompt parameter's expected style ('so the follow-up can be short'). The schema parameter descriptions themselves are unusually rich, cross-referencing pi_models, pi_sessions, and pi_send, which justifies above-baseline scoring.

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 states a specific verb and resource — 'Send a new turn to an existing pi session' — with a precise scope condition ('that is not executing right now'). It actively distinguishes itself from siblings by naming both alternatives: 'resume it here instead of restarting with `pi`' and 'use pi_send instead.' An agent can tell exactly what this tool does without opening any sibling 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?

Explicit when-to-use and when-not-to-use guidance is present. It covers valid edge cases ('including one that timed out or was cancelled'), gives the exclusion condition ('For a turn still running under "rpc", use pi_send instead'), and names the restart alternative (`pi`). The persistence guarantee ('Survives restarts of this server') further informs whether resuming is safe.

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