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

With no annotations, the description carries the full burden and does so well: it states the call 'Returns identity/status immediately,' 'Restores released sessions after MCP restart,' 'rejects running agents,' and 'never imports arbitrary Pi CLI sessions.' These are non-obvious behavioral traits. It stops short of describing error/response shape, which slightly holds it below 5.

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?

Front-loaded with purpose, then conditional parameter rules, return behavior, sibling routing and constraints in dense but non-redundant clauses. The final routing sentence packs several ideas together, but every sentence contributes information an agent needs.

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 annotations and no output schema means the description must carry behavior and returns, which it does: immediacy of return, restart recovery, rejection of running agents and CLI-session exclusion are all covered. A brief note on the response contents would make it fully self-sufficient, but it is close.

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 only 33% (model alone is documented), so the description must compensate. It explains task semantics well ('pass the answer' for needs_input, otherwise the next assignment) and confirms session_id is a 'registered agent by explicit ID,' while model guidance matches the schema. This largely fills the coverage gap.

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 and resource: 'Continue a registered agent by explicit ID, retaining its Pi conversation/tool context,' which clearly separates it from spawning a new agent. It names pi_wait_agent, pi_poll_agent and pi_get_result, but never distinguishes itself from the confusable pi_followup_agent or pi_steer_agent, leaving some sibling ambiguity.

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?

Gives concrete when-to-use rules: 'For needs_input, pass the answer as task; otherwise pass the next assignment' and 'Do independent work or use pi_wait_agent when idle.' It routes to three alternatives with their roles, but does not address when NOT to use this versus pi_followup_agent or pi_steer_agent.

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

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

With no annotations, the description carries the full burden, and it does disclose the key trait: the message is queued and only delivered after all work completes. However, it says nothing about failure modes (invalid/terminated session_id), whether the call blocks, or what happens if the agent never finishes.

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 short sentences, no filler, with the core behavior and the non-interrupting condition front-loaded. Every sentence adds distinct information.

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 simple two-parameter tool with no output schema this is close, but the absence of any guidance on obtaining a valid session_id, error behavior, or interaction with pi_wait_agent/pi_get_result (which the agent likely needs to retrieve the eventual result) leaves 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 description coverage is 0%, so the description must compensate, and it only partially does. It implies 'message' is the follow-up text and 'session_id' identifies the target agent, but gives no format, sourcing (where a session_id comes from), or constraints for either required parameter.

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 ('Queue') and resource ('follow-up message for a spawned Pi agent'), plus a scope-defining behavior ('delivered only after the agent finishes all work'). This lets an agent distinguish it from pi_steer_agent, which implies interrupting the agent mid-run.

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?

'Use this when you do not want to interrupt the agent at all' is an explicit usage condition that implicitly routes away from pi_steer_agent. It stops short of naming the alternative sibling or stating exclusions (e.g., what to do if the agent has already finished).

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

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

With no annotations, the description carries the full burden and delivers: the differing return body per terminal state, the exact non-final payload ({ready:false,reason,next}), the guarantee that no progress/question body is ever returned, the side effect that reading acknowledges the unread event, and persistence across release or MCP restart. That is genuinely non-obvious lifecycle and side-effect context.

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?

Purpose is front-loaded in the first clause and every subsequent clause adds a distinct fact (state bodies, non-final shape, routing to pi_poll_agent, ack side effect, retention). The middle is dense with chained clauses, which slightly hurts readability but not information density.

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?

With no output schema and no annotations, the description does the heavy lifting by spelling out the JSON bodies for each state and the durability guarantee. It stops short of covering failure modes (e.g. unknown or released session_id) and full field semantics of the done payload, which an agent would still have to discover.

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 description coverage is 0% and the description never mentions session_id or its expected format, so it adds nothing over the schema's single required string. The parameter name is self-explanatory for a session-scoped call, which keeps this at a minimum-viable 3 rather than lower.

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+resource ('Read final delivery') and immediately defines its semantics for each terminal state (done / error / interrupted), which distinguishes it from the sibling family. It also names pi_poll_agent as the tool for the not-yet-final case, so an agent can route without opening any 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?

'Read final delivery, without waiting' plus 'Before final delivery exists... use pi_poll_agent' gives an explicit when-to-use and a named alternative. It does not mention pi_wait_agent or when blocking would be preferable, so the exclusion set is incomplete.

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

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

With no annotations, the description carries the full burden and does so unusually well: it discloses a side effect ('Listed agents become eligible for this connection's unread event reminders') and an explicit non-effect ('Does not refresh idle timers'), plus the scope limit of unloaded-but-recoverable agents. This is exactly the behavioral context an agent cannot infer from structured fields.

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?

Front-loads scope and return shape in the first two clauses, then adds operational detail, so nothing is buried. It is dense and slightly run-on across semicolons, but each clause carries distinct, non-redundant information.

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 exists, so the description correctly specifies return content ('compact identity/status metadata, no transcript'). It covers the state model and side effects, but is silent on result size, ordering, or whether the status filter matches exactly one state.

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 50%: cwd is self-documented in the schema, and the description explains the meaning of two enum values (active, needs_input) that the schema leaves bare. The remaining three status values (done, error, interrupted) are undefined in both places, and no filtering/combination semantics are given, so it adds only partial compensation.

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 and resource ('List only this MCP registry') and immediately scopes it against the sibling set by naming what is included (unloaded recoverable agents) and what is not returned (transcript). An agent can distinguish this from pi_list_models and the poll/wait/get_result family without opening a 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?

Gives concrete workflow routing for the needs_input state: 'poll it, then continue the same ID with an answer,' which names the downstream tools to use. It does not present explicit when-not-to-use guidance or contrast itself against pi_poll_agent/pi_wait_agent for the general case, so it falls short of full alternative mapping.

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

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

No annotations are provided, so the description carries the full disclosure burden. It usefully reveals the response content (tier labels) and scopes results to the current session, but says nothing about read-only nature, ordering, errors, or whether a session must already exist.

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?

A single front-loaded sentence with no filler. The verb and resource come first, followed by the scope and the useful output detail.

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 trivial zero-argument read tool with no output schema, the description covers what is returned and the scope of 'available.' Minor omissions only (ordering, whether models are session-bound or global) keep it short of perfect.

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 tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description correctly adds nothing extraneous about inputs.

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 (List) and resource (Pi models) plus the scope ('available for this session') and the return content (tier labels fast/balanced/frontier). The resource is wholly distinct from every sibling, which all manage agents, so an agent can route to it unambiguously.

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?

Usage is only implied: the agent can infer this is a discovery call for picking a model, presumably before pi_spawn_agent. There is no explicit when-to-use statement, no note that it takes no arguments, and no pointer to the sibling that consumes the result.

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

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

With no annotations, the description carries the full burden and does substantial work: output can stay unchanged while Pi thinks, activity reports latest phase/tool and update time, reading a question acknowledges its reminder while polling does not acknowledge final delivery. It omits error behavior, session validity, and rate-limit concerns.

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?

Information is dense and front-loaded: what is returned, what is excluded, then the two behavioral edge cases and the sibling routing. It is telegraphic but each clause carries meaning; minor terseness ('activity shows the latest phase/tool') slightly hurts readability.

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 one-parameter polling tool with no annotations or output schema, the description covers return semantics, polling/acknowledgement behavior, and alternative routing well. The remaining gap is the undefined session_id, which no other structured field supplies.

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 single session_id parameter has 0% schema description coverage and the description never defines it — it only alludes to 'the same ID' in the context of pi_continue_agent. With one undocumented parameter, the description does not compensate for the schema gap.

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 ('read') and enumerates the resource precisely: latest assistant text, compact activity metadata, pending question, while explicitly excluding reasoning text and raw tool records. It names sibling pi_wait_agent, so an agent can distinguish it without opening the 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?

It gives a clear routing rule ('When idle, use pi_wait_agent instead of repeatedly polling') and prescribes a follow-up path for the needs_input case ('answer via pi_continue_agent on the same ID'). It lacks guidance on frequency/backoff outside the idle case, so it stops short of full when/when-not coverage.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mutating act (releasing the write lease), the precondition (busy agents are rejected), and the reversibility profile (name, description, results and session retained). It stops short of covering failure modes, permissions, or how the agent becomes active again.

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-loaded with the core action, then the precondition, then the non-destructive guarantee. No filler or repetition.

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 one-parameter mutation with no output schema and no annotations, the description covers the important behavioral facts: what is released, what is preserved, and the idle precondition. Only minor gaps (no return/error behavior) remain.

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 description coverage is 0% and the description never mentions session_id, so it adds no meaning beyond the bare schema. The single parameter is largely self-evident, keeping this at a minimum-viable 3 rather than lower.

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 gives a specific verb and resource ('unload an idle agent runtime and release its write lease') and explicitly delineates what it does NOT do ('Does not delete the agent or its context'), which separates it from the pi_terminate_agent sibling. An agent can identify the operation without opening schemas.

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 states a clear precondition ('Rejects busy agents') and an implicit context (retaining state 'for later continuation', i.e., when you want to free a runtime without ending the agent). It does not explicitly name alternatives like pi_terminate_agent or pi_continue_agent, so it lacks the direct when/when-not routing of a 5.

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

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

With no annotations, the description carries the full burden and does so well: asynchronous execution, that the response is identity/status rather than a result, that there are no live notifications, that unread events may ride along with any tool response, and how model defaulting behaves. It does not discuss permissions, concurrency limits, or cost, so it falls short of a 5.

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?

Front-loaded with the core action and return semantics, then lifecycle routing. It is dense and largely earn-your-place, though the telegraphic style (semicolon-joined fragments) makes it slightly harder to parse than it needs to be.

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 explain return shape and follow-up path — it does both. Given the 11-tool sibling set and 5-param schema, the definition gives an agent enough to spawn and drive an agent to completion; only auth/limits context is absent.

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 description coverage is 100%, so the schema already documents all five parameters including cwd, name, model format, and description. The one added line ('Omit model to follow Pi settings') restates what the model param description already says, so there is no real value beyond the schema. Baseline 3 applies.

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 and resource ('Start a named Pi agent asynchronously') and immediately bounds the outcome ('Returns identity/status, not a completed result'), which is exactly the ambiguity an agent faces with a spawn tool. It also implicitly separates itself from pi_followup_agent/pi_list_agents by directing reuse to pi_list_agents.

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: continue independent work, call pi_wait_agent when idle rather than repeatedly polling, use pi_poll_agent for progress or needs_input, answer via pi_continue_agent, read final delivery with pi_get_result, and use pi_list_agents for reuse. Every sibling in the lifecycle is routed by condition.

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

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

With no annotations, the description carries the full burden and delivers: it discloses that 'queued' is an acceptance receipt, not delivery; that delivery occurs only after the current turn's tool calls; and that rejection covers unknown session, non-running session, or a refusal. That async, non-interrupting semantics is exactly the context an agent would otherwise get wrong.

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?

Purpose and routing come first, and the return-shape documentation is needed because there is no output schema. The status tuples are dense but each clause carries information; slight redundancy in restating ok/message/status fields keeps it from a 5.

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 two-parameter tool with no annotations and no output schema, the description covers purpose, alternative routing, success semantics, and all known failure modes. The remaining hole is parameter meaning and any note on ordering when multiple steers are queued.

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 description coverage is 0%, so the description must supply meaning for session_id and message, and it supplies none. Both names are largely self-evident, which softens the gap, but the description does not say where session_id comes from (e.g., a pi_spawn_agent result) or any constraints on message content/length.

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 first sentence states a specific verb (queue), resource (steering message), and precondition (for a running Pi agent). It explicitly names the sibling pi_followup_agent and the condition that distinguishes the two, so an agent can route correctly 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?

It gives a clear routing rule: use pi_followup_agent 'to queue a message for after all work is finished,' implying this tool is for mid-run steering. The when-to-use is strongly implied by 'running Pi agent' plus the contrast, but no explicit statement of when steering is inappropriate (e.g., agent idle or nearly done) is given.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mutation (task stopped), the state transition (marked interrupted), what is preserved (registered agent and context), and what is returned (partial latest reply). It omits idempotency, permission requirements, and whether a stopped agent can be resumed only via continuation.

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?

Two sentences with no filler; the action and its side effects come first, and the sibling-routing clause follows. Every clause earns its place.

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 or annotations exist, so the description must explain effects and returns; it does cover both, plus continuation semantics. The only material gap is the undocumented session_id parameter.

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 description coverage is 0% and the description never mentions session_id, so the single parameter's meaning is left entirely to the caller's inference. The name is suggestive but the definition adds no semantics beyond the schema.

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+resource ('Stop the current task') and enumerates the observable effects (marks it interrupted, returns partial latest reply). It explicitly contrasts itself with the sibling pi_release_agent, so an agent can pick between the two without reading 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?

Gives a clear when-not rule: use pi_release_agent to unload an idle runtime instead of terminating. It also states the continuation path (the agent/context is retained). No guidance is offered relative to pi_steer_agent or pi_followup_agent, but the primary discriminator is present.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: the wait calls no model, progress changes alone do not wake it, the return shape is {status,timed_out,next} with no body or acknowledgement, and timeout/cancellation leave Pi running. These are exactly the non-obvious traits an agent could not infer from the schema.

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?

Purpose and guardrail lead the text, followed by return shape and recovery guidance; every sentence adds operational value. It is dense and slightly run-on, but there is essentially no filler to cut.

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?

Despite having no output schema and no annotations, the description discloses the return shape, the blocking semantics, and the timeout/cancel behavior an agent needs. Nothing required to call this correctly or interpret the result is missing.

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 50%: timeout_ms is well documented in-schema, while session_id is undocumented in both places. The description reinforces timeout semantics ('On timeout Pi keeps running: wait again or inspect progress') but adds nothing about identifying the session, so it neither under- nor over-compensates for the gap.

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 (wait) on a specific resource (this agent) with the exact conditions that end the wait: need input, finish, fail, or be interrupted. It also scopes when the tool is appropriate ('when no independent work remains'), which cleanly separates it from the polling and result siblings.

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 timing guidance ('When no independent work remains'), an edge-case rule ('Already actionable states return immediately'), and named alternatives with their distinct roles: pi_poll_agent for questions, pi_get_result for final delivery. An agent knows exactly when to reach for this versus a sibling.

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