conversation

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 that status never returns goal or message text (no payload, no secrets), that cancel does not roll back already-produced side effects, that repeating the current state is an idempotent no-op, and that a conflicting terminal state is rejected so the two agents cannot fight over the outcome. Those are exactly the side-effect, idempotency, and failure-mode facts an agent needs before mutating.

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 purpose sentence followed by one dense clause per action, so the agent can jump straight to the relevant mode. The 'never the goal text, never message text (no payload, no secrets)' line is slightly redundant, and the unexplained 'outcome a'/'outcome c' shorthand spends words without transferring meaning.

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?

An output schema exists, yet the description still usefully previews what status returns (state, turn_count/max_turns, expiry, recent transitions, in-flight message), and terminal-state semantics are fully covered. Remaining gaps are the undefined outcome taxonomy and the absence of any note on identity/auth requirements or invalid-conversation_id behavior for a tool whose whole premise is agent-scoped access.

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 0% and the action parameter has no enum, so the description is the only place the valid action values and their meanings appear — the four 'status/cancel/complete/needs_human' labels plus per-action state constraints. conversation_id gets only indirect semantics ('a conversation only its two agents belong to'), and the list is never explicitly declared exhaustive, so it nearly but does not fully compensate.

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 concrete verb pair ('Inspect or steer') and resource ('a conversation'), then enumerates four distinct operations (status, cancel, complete, needs_human) with their effects. The scope constraint 'only its two agents belong to' signals the ownership boundary. It never names a sibling tool, so differentiation from send_message/start_conversation is left to inference rather than stated.

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?

Each action carries its own applicability condition: cancel is 'allowed from active/blocked/needs_human', complete and needs_human are 'only from active'. That is genuine when-to-use guidance. It stops short of naming alternatives or saying when not to call this at all, and the '(the review worker's outcome a)' / '(outcome c)' references point at an undefined taxonomy the agent cannot resolve.

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