hive

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

Annotations already declare destructive=true and idempotent=true, and the description goes well beyond them: the scan is global rather than caller-scoped with an explanation of the misclassification risk, actors with agent_state_log rows are retained, execution is immediate and permanent with no dry-run, and the lock guard is disclosed.

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 the deletion criteria, and the ordering/lock guidance follows. The long FK-column enumeration is dense but load-bearing for a store-wide sweep, so little is wasted, though the prose could be tightened slightly.

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, so return values need not be explained. For a destructive, zero-param, whole-store operation the description supplies scope, retention rules, ordering with project_prune, lock behavior, and irreversibility — everything an agent needs.

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 takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a 0-param tool applies. No syntax or format gaps exist.

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 (Delete) plus a precisely bounded resource (actors owning no rows anywhere and inactive for one minute), and enumerates every FK column scanned. It is unmistakable against siblings such as project_prune and agent_close.

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?

Explicitly states when to run it (after project_prune when sweeping the store), when it refuses (HIVE_PROJECT_LOCK=1), and what it never touches (the caller's own actor). It names the sibling alternative project_prune and the ordering between them.

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?

Goes well beyond the destructiveHint/idempotentHint annotations: terminal output is not retained, handoffs must be captured first, live lead panes are refused, dead ones retired, and row_only is refused when a live pane is provably owned or tmux could not be probed. These are non-obvious behavioral guards an agent could not infer from annotations alone.

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 the critical handoff warning before the guard clauses. Dense and semicolon-heavy, but nearly every clause carries operational information; only slight trimming would be possible.

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 destructive, multi-guard tool, the description covers the mutation, the irreversible loss (terminal output), the permission model (leads vs workers), and the edge-case escape hatch (row_only). An output schema exists, so return values need no elaboration.

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 80%, so the baseline is 3, but the description adds real semantic meaning for row_only (the exact refusal conditions) and confirm_self (required only when closing yourself), plus the precedence rule that agent_id wins over name.

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: kill an agent's tmux window and mark it closed, addressed by name or agent_id. This is clearly distinguishable from siblings like agent_park, agent_resume, and agent_spawn.

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/when-not guidance: capture handoffs before closing, confirm_self=true required to close yourself, refuses a live lead target but retires a dead one, and a worker may never close a lead. row_only usage is scoped precisely to human or peer leads.

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?

Annotations declare idempotentHint=true and destructiveHint=false, so safety is partly covered; the description adds real behavioral detail the annotations don't — result ordering (newest first), the limit bound (default 20, max 100) and the cursor-based paging via next_before_id/before_id. It does not explain why readOnlyHint=false on what reads as a list operation, which is the one unexplained behavioral gap.

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 the purpose, then layers the include_closed variants and paging in one dense but well-ordered passage. Every clause earns its place; it is slightly compressed but not padded.

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, the description compensates by describing the receipts and the next_before_id cursor, so an agent knows how to page and what ordering to expect. Combined with tested conditional behavior for include_closed and limit, it is nearly sufficient for correct invocation.

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 the description reinforces the include_closed conditional, the limit default/max, and — beyond the schema — the pagination contract of feeding the receipt's next_before_id back as before_id. The only parameter not touched in prose is project_id, which the schema documents fully.

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 this project's agents") plus scope ("with live status" and "this project's"), which cleanly separates it from single-agent tools like agent_status. It never names a sibling explicitly, so differentiation must be inferred from the scope phrasing 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?

Gives concrete when-to-use guidance for include_closed ("Without include_closed, this is every running agent... With include_closed, it is every agent") and an explicit when-not for project_id ("Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope"). It stops short of routing the agent to alternatives such as agent_status or wake_list.

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?

The description itself is behaviorally rich: it discloses the 7-day pruning window, the fact that a pruned-id lookup reports pruning rather than a missing record, and the delivery-state fields returned (delivery_status, delivery_method, socket_attempt_at, confirmed_at, fallback_claimed_at, typed_at, delivery_note). However, it frames the operation purely as 'Read' while annotations set readOnlyHint=false, so the description and the structured safety signal disagree about whether this call mutates anything. Per the rubric this contradiction caps the score; the compensation is that the remaining behavioral content is well above average.

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?

The purpose and the id source are front-loaded in the first clause, and every sentence carries non-redundant information (storage trigger, alternative path, pruning, error semantics, returned state). It is dense and the parenthetical field list makes the middle sentence run long, but there is 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?

With no output schema, the description carries the return-value burden and largely meets it by naming the delivery-state fields, and it also covers the error path for pruned ids. Given the tool's complexity, an agent has enough to call it correctly. What is missing is any statement about the message body's own format and whether the read itself affects delivery state (relevant given readOnlyHint=false).

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 50%: project_id is documented in the schema, message_id is not. The description compensates for the undocumented parameter by explaining exactly where the id comes from — a '[hive:worker NAME] [message #N ...]' pointer line — which the schema's bare 'integer, exclusiveMinimum 0' does not convey. project_id's meaning and scoping rule are already handled by the schema text, so nothing is lost there.

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 ('Read one agent-to-lead message in full') plus the selection key (the id from a '[hive:worker NAME] [message #N ...]' pointer line). It is clearly not the same thing as question_get or agent_output, though it never names a sibling explicitly. The scope is unambiguous, which is what matters for an agent deciding whether to call it.

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 the exact conditions under which a readable message exists (a send over 300 characters from a non-lead to a lead, or any worker send to a Claude lead while quiet_messaging is on) and explicitly states the negative case: 'Every other send is typed with its sender tag and stores nothing, so there is no id to read.' That is strong when/when-not guidance; it simply stops short of naming an alternative tool for those other sends.

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?

Annotations already declare idempotentHint=true and destructiveHint=false, consistent with the 'read' framing. The description adds the line-window defaults and the 'verify real output before declaring done' workflow cue, but says nothing about what the rendered terminal contains or how it behaves when the agent has exited. readOnlyHint=false is conservative and sits in mild tension with 'Read', though destructiveHint=false and idempotentHint=true keep them reconcilable.

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, no filler, with the operation and its size bounds front-loaded before the usage cue. Every clause carries 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?

For a read tool with no output schema and well-annotated parameters, the description covers operation, addressing, and window size adequately. It would be complete at 5 if it hinted at the returned content (text lines) or the empty/partial-name edge case beyond what the schema says.

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%, so the schema already explains name/agent_id precedence and the project_id scoping rule. The description contributes the one thing the schema omits: the default line count of 50 against the schema's max of 200, plus the name-or-id addressing summary.

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 ('Read the rendered terminal of an agent') with concrete bounds (default 50 lines, max 200), which is far more specific than the bare name. It implicitly separates itself from agent_list/agent_status by being about output content, but it never names a sibling to differentiate against, so it stops short of a 5.

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 REAL output before declaring a worker done' gives a concrete trigger for use rather than relying on agent status alone. There is no explicit when-not-to-use or named alternative tool, so it is clear context without exclusions.

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?

Annotations declare destructiveHint=true and readOnlyHint=false, and the description adds real behavioral detail beyond them: it kills the pane (concrete destructive act), records a distinct PARKED state rather than closed, and captures the branch. It does not discuss permissions or idempotency/reversibility beyond the resume pointer, so a 4 rather than 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-loads the verb and its effects, then the routing guidance, then the resume pointer. Dense but every clause carries information; minor redundancy in restating PARKED vs closed.

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, so return values need not be explained, and the description covers the destructive effect, the state distinction, and the resume path. For a destructive mutation tool this is nearly complete, with only permissions/irreversibility left implicit.

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 the schema descriptions are rich (name partial-match rules, agent_id precedence, project_id scoping). The description adds no parameter-level syntax or meaning beyond what the schema already provides, so the 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 (park) and resource (claude/codex worker) and enumerates the concrete effects: kill the pane, mark the row PARKED, record the branch, return a board line plus the resume call. It explicitly distinguishes itself from the sibling agent_close.

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 an explicit when-to-use rule ('when the lane is paused, not finished') and names the alternative it replaces (agent_close), plus the follow-up path (agent_resume). Nothing is left to inference.

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?

Adds substantial behavior beyond the annotations: attribution of existing pad writes/todos/leases is preserved, a live claude worker receives an out-of-band retitle delivered as a user turn visible in its pane, and lead targets are rejected. These are consequences an agent could not infer from destructiveHint/readOnlyHint alone.

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 the core action, then packs the identity invariant, worker-side effect, timing advice and refusal rule into three dense sentences with no filler. Slightly long, but every clause carries operational 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?

With a full input schema and an output schema present, return values need no explanation; the description instead covers the risky edges (lead refusal, mid-task timing, session retitle side effect). Nothing essential to calling it correctly 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 description coverage is 100%, and the schema already documents name-vs-agent_id precedence, partial-name matching, uniqueness of new_name, and the project_id scope override. The description adds the actor_id format note but no further parameter detail, so 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+resource combination (change a worker's display name) and immediately clarifies the identity invariant (actor_id unchanged). An agent can distinguish this from siblings like agent_spawn or agent_park 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?

Gives concrete timing guidance ("rename between assignments rather than mid-task") and an explicit refusal condition ("Refuses a lead target outright"). It does not name an alternative sibling for renaming-adjacent needs, so it falls just short 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 annotations already declaring readOnlyHint=false, idempotentHint=false, and destructiveHint=false, the description adds useful behavior beyond the structured data: a fresh pane, the same actor_id, full prior context, and the fact that it does not send a follow-up instruction. It stops short of describing error or permission behavior, so it is not fully exhaustive.

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?

The description is front-loaded with the core action and is only three compact sentences. Each sentence carries necessary information: what is resumed, how it is addressed, and what to do after resuming.

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 the rich input schema, output schema, and annotations, the description supplies the remaining context an agent needs: the worker must be CLOSED, targeting uses name or agent_id among closed agents, and sending the next instruction is a separate tool call. Nothing essential for correct invocation appears to be 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 description coverage is 100%, so the schema already documents the parameters thoroughly. The description still adds meaning by specifying that the target must be addressed by name or agent_id among closed agents, and by pointing to agent_list(include_closed: true) for finding them.

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: 'Resume a CLOSED claude or codex worker from its recorded session id'. It also distinguishes the result from creating a new worker by noting 'a fresh pane, the same actor_id, and the worker's full prior context', so an agent can tell it apart from siblings like agent_spawn.

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 explicit conditions: resume a CLOSED worker, addressed by name or agent_id among closed agents, findable via agent_list(include_closed: true). It also names the alternative follow-up action: 'Send it its next instruction with agent_send once resumed - this tool does not.'

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?

Far exceeds what the annotations carry: sender-tag prefixing, bracketed-paste delivery, Enter-unless-submit=false, the 300-character lead-truncation exception, the quiet_messaging socket path with pending/confirmation and hive fallback, and two explicit refusal modes (unclassifiable screen, tmux copy mode) with recovery. These are exactly the mutation and failure semantics an agent needs before calling a destructive, non-idempotent tool.

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 primary action, which is good, but the body is a single dense run-on paragraph chaining exceptions, quiet_messaging state machine, and refusal modes. Almost every clause carries necessary content, yet the absence of any list or paragraph breaks makes it hard to parse and pushes size past what is needed.

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, the description correctly explains what receipts report (pointer vs full text, pending-until-confirmed), how failures behave, and how to recover from each refusal. For a 7-parameter destructive tool with complex routing, nothing an agent needs to call it correctly 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 71%, and the description fills the gaps: it characterizes text ('any shape', prefixed, pasted), submit=false, the keys tmux-name form, and repeats/confirms the wait_ms 250-10000 range. It adds real meaning over the schema for text and wait_ms, though it does not discuss project_id or agent_id/name precedence beyond what the schema already documents.

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?

Opens with a precise verb+resource ('Type into an agent's terminal, addressed by name (or agent_id)'), which is unambiguous and clearly distinct from siblings like agent_spawn, agent_output, and agent_message_get. The core action, addressing scheme, and the keys alternative are all stated up front without needing 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?

Gives explicit conditions and alternatives: use keys instead of text to send raw tmux keys, use agent_message_get to read the full text of a pointer, do not resend a pending send, and stay in current project scope. It does not, however, route the agent among other messaging siblings (e.g., question_ask) or state when not to use agent_send at all.

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?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), which only say this is a non-read, non-idempotent, non-destructive write. The description adds the auto-briefing behavior, the harness allow-list refusal rule, the classify/type-into restriction with brief_path in the receipt, read_only semantics, project locking, and the tmux attach watch command.

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-dense and front-loaded with the main action, but it is a single sprawling paragraph with heavily nested parentheticals ("A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not)..."), which hurts parseability. Every sentence carries content, but the structure is tangled.

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 complex 11-parameter spawn tool with an output schema present, the description covers the briefing model, refusal conditions, read_only mode, and project scoping without needing to explain return values. An agent has everything required to invoke it correctly.

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, but the description adds real meaning beyond the schema: the command-vs-harness precedence and refusal rule, the exact extra_args allow-list under read_only, and the project_id scope restriction. It clarifies the interplay among these parameters rather than merely restating them.

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?

Opens with a specific verb+resource ("Spawn a worker agent") and immediately names the default (claude, or the project's hive.yml agents: default). It is clearly distinguishable from siblings like agent_resume, agent_send, and agent_status, which it references by their distinct roles.

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 strong conditional guidance: claude workers are briefed automatically so "send it its assignment directly" (routing to agent_send), and it spells out when spawning is refused (unlisted known harness, unclassifiable harness). It cross-references agent_resume and agent_status but never explicitly frames when to choose spawn vs those alternatives, keeping it short 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?

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=false. The description adds real value by disclosing what the response contains (terminal tail, optional brief) and the non-obvious rationale that hive stores the brief because an appended system prompt appears in no transcript. However, readOnlyHint=false sits in mild tension with a description that portrays a pure inspection call, and pagination/return shape are not covered.

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, front-loaded with purpose and the addressing mechanism, zero filler. The second sentence drifts slightly into hive implementation trivia that an agent doesn't strictly need in order to call the tool, which keeps it out of the top band.

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 carries the return-shape burden; it does so adequately by naming the terminal tail and the optional full brief. Safety semantics are covered by annotations and the parameter surface is fully covered by the schema, so the remaining gaps (full return structure, empty-result behavior) are minor.

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 name/agent_id/project_id/include_brief are already fully documented in the schema. The description reinforces the name-or-agent_id selector and the meaning of include_brief=true, but adds no syntax, format, or priority detail beyond what the schema states (the 'agent_id wins' precedence lives in the schema, not here). Baseline 3 is appropriate.

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+resource pairing ('Detailed status for one agent') plus the selector (name/agent_id) and the distinctive return ('a short tail of its terminal'), which distinguishes it from list-style siblings like agent_list. It stops short of explicitly naming which sibling to use instead, so it lands just below the top band.

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 implied rather than stated: 'one agent, addressed by name' tells the agent this is the single-agent counterpart to agent_list, and include_brief is explained. There is no explicit when-to-use/when-not or mention of agent_output/agent_message_get as alternatives, so an agent must infer the routing.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing beyond that about the shape or length of the returned guidance, but with annotations carrying the behavioral burden a 3 is appropriate.

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 tight sentences with no filler, and the default behavior (omit for overview) is front-loaded ahead of the accepted values. 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?

For a read-only help tool with a single optional parameter, no output schema, and safety fully covered by annotations, nothing needed for correct invocation 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 description coverage is 0% and the schema declares no enum, so the description carries the entire burden for the single topic parameter. It does so by explicitly enumerating all valid values (workflow, profiles, agents, wakes, projects, identity, actors, pads, todos, kv, questions, leases) and stating the default behavior when omitted.

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 resource (Hive usage guidance) and precisely what the tool returns, enumerating the twelve topics it can cover. An agent immediately understands this is the documentation/help entry point and can distinguish it from every operational sibling like todo_list or agent_status.

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 clearly explains both invocation modes: omit topic for an overview, or pass one of the listed topics. It does not attempt to say when help is preferable to just calling the operational tool directly, but for a self-evidently scoped help tool that omission is minor.

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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured data. The description adds only the word "shared," hinting the value is cross-agent/cross-project scoped, but says nothing about behavior on a missing key or whether deletion is recoverable.

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 short sentence, front-loaded with the action. Nothing is wasted, though it is arguably too terse to be fully informative for a destructive operation.

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 and complete destructive/idempotent annotations reduce the burden, and for a two-parameter delete the description is barely sufficient. It still omits error behavior for a nonexistent key and the project-scoping default, leaving real gaps for a destructive tool.

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 50%: project_id carries rich inline guidance while key has none. The description's "by key" merely restates the required parameter name and adds no format, uniqueness, or lookup semantics, and it ignores project_id entirely — so it does not compensate for 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 ("Delete a shared value") and the selector ("by key"), which cleanly distinguishes it from siblings kv_get, kv_set, and kv_list. It stops short of explicitly naming those alternatives, so it is clear but not maximally differentiated.

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?

No when-to-use, when-not-to-use, or prerequisite guidance is given. It never mentions kv_set/kv_get as the paired operations or warns that deletion is permanent. The agent must infer everything from the name.

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?

Annotations declare readOnlyHint=false and destructiveHint=true, yet the description frames this as a plain read ('Get a shared JSON value'). Nothing in the text explains the destructive/non-read-only behavior, so the description actively misleads relative to the structured metadata.

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 short, front-loaded sentence with no waste. It is arguably too terse for the behavioral complexity implied by the annotations, but as prose it is efficient.

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 50% parameter coverage, the description needed to carry more weight, and it leaves the destructive/non-read-only nature of the operation completely unexplained. An agent could call this believing it is a safe read.

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%: project_id carries a strong, self-contained usage constraint, but the required 'key' parameter is undocumented. The description only adds 'by key,' which is already obvious from the schema, so it does not compensate 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 ('Get') and resource ('shared JSON value') and identifies the lookup key. It does not explicitly distinguish itself from siblings like kv_list or kv_delete, but the intent is unambiguous.

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?

No when-to-use guidance, no mention of alternatives such as kv_list or kv_delete, and no stated prerequisites. The agent has to infer that this is the single-key read path from the name alone.

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?

Annotations declare readOnlyHint=false and destructiveHint=true, yet the description presents this purely as a read/enumeration operation ('List shared values'). The description offers no acknowledgment of the surprising destructive/non-read-only behavior, leaving the contradiction unexplained.

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 the primary action first and the modifier second. Nothing is wasted and it is appropriately sized for a two-parameter list tool.

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 list tool with no output schema, the definition is minimally adequate, but the unexplained destructive annotation and the undocumented prefix param leave real gaps. An agent cannot fully predict the tool's side effects or filtering behavior.

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%: project_id carries a strong inline description, while prefix is undocumented in the schema and only implied by the description's 'filtered by key prefix'. The description compensates marginally for the prefix gap but adds no format or matching semantics (e.g. exact vs prefix match behavior).

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 ('shared values') with the optional prefix filter, so the agent knows it enumerates key-value entries. It does not explicitly distinguish itself from the sibling kv_get (single-value fetch), though 'List' vs 'Get' is fairly self-evident.

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?

The only guidance is 'optionally filtered by key prefix' — there is no statement of when to use this versus kv_get or the other kv_* siblings, and no mention of scope or prerequisites. The agent gets context only by inference.

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?

Annotations already declare this is a non-read-only, destructive write (overwrites), so the safety picture is partially covered. The description usefully adds cross-session visibility and TTL semantics, but does not clarify overwrite behavior, the meaning of 'small', or any key/value limits despite destructiveHint.

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 short sentences, front-loaded with the core action and followed by the optional modifier. No filler.

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?

Output schema exists and annotations cover the destructive/overwrite profile, so the description need not explain returns. Still, for a cross-session shared-value write tool it omits overwrite semantics and 'small' size expectations, leaving notable 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 50%; project_id is well documented in the schema while key and ttl_seconds are not. The description adds the unit for ttl_seconds ('in seconds'), a real gain, but says nothing about key naming rules or project scoping beyond what the schema provides.

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?

Specific verb+resource ('Set a small shared JSON value') with scope info ('other sessions can discover'), clearly distinct from kv_get/kv_delete by name and semantics. No explicit sibling differentiation, but the resource is unambiguous.

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?

The phrase 'other sessions can discover' hints at the cross-session sharing use case, but there is no explicit when-to-use, when-not, or reference to alternative tools. The agent must infer usage entirely from the name and sibling list.

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?

Adds genuinely useful traits beyond the annotations: non-blocking acquisition, re-acquiring your own lease extends it, and leases self-expire. The annotations only cover the safety profile, so the contention and expiry semantics are meaningful added context. What happens on a failed acquire (error vs. false return) is not stated.

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, front-loaded with the purpose, and the parenthetical placement of '(non-blocking)' is efficient. 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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers the acquisition/extension/expiry semantics an agent needs; only the failure mode and ttl meaning are left unstated.

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 never mentions key, ttl_seconds, or project_id. With schema coverage at only 67%, ttl_seconds in particular is undocumented in both the schema and the prose, so the description does nothing to compensate 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?

Specific verb ('take a named lease') plus resource and the kind of state it guards, with concrete examples (shared checkout, dev database, port). It is clearly the acquisition half of the lease pair, though it never names the sibling lease_release to sharpen the contrast.

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?

States the situation that calls for it (state another session could also change) and flags that it is non-blocking, so the agent knows it fails rather than queues. No explicit when-not-to-use or pointer to the alternative tool (lease_release, or a lock-free path).

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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds one genuinely non-structured fact — that the caller must own the lease — but says nothing about failure behavior for unowned keys, side effects on the leased resource, or error semantics.

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 short sentence with the action front-loaded and no wasted words. It is efficient, though the brevity borders on under-specification rather than disciplined conciseness.

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, so return values need not be explained. However, for a destructive, ownership-gated mutation, the description omits what happens on success, whether other holders are affected, and what error to expect when the lease is not owned — leaving real 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 50%: project_id carries a thorough description, but the required 'key' parameter has no schema description and the tool description does not explain it either. The description therefore does nothing to compensate for the undocumented 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+resource pair ('Release a lease'), which an agent can distinguish from the sibling lease_acquire without opening either schema. It stops short of explicitly naming the counterpart tool or the scope of the release, so it is clear but not fully differentiated.

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?

The phrase 'you own' implies a precondition but gives no explicit when/when-not guidance, no reference to lease_acquire or lease lifetimes, and no indication of what to do if ownership is unclear. Usage must be inferred entirely.

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?

Annotations already declare non-read-only, non-idempotent, non-destructive behavior, and the description usefully confirms the additive append semantics plus the concurrency angle. It stops short of saying what happens on an expected_revision mismatch (error vs. overwrite) or whether appends are atomic.

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 tight sentences, front-loaded with the operation and then the concurrency guard. No filler.

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 annotations and an output schema present, the description only needs to carry the mutation semantics, which it does. Adding the failure mode for a stale expected_revision would make it fully complete.

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 only 25%: only project_id is documented in the schema, and the description explains expected_revision's purpose (guarding concurrent writes), which the schema does not. pad_id and content remain undocumented, though their names are largely self-evident.

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 ('Append content to the end of a pad') plus the additive scope, which distinguishes it from siblings like pad_write and pad_edit. It does not name those siblings explicitly, so differentiation is inferred 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?

There is no explicit when-to-use guidance and no alternatives named, even though pad_write, pad_edit, and pad_read sit in the same family. 'Append' implies the intent, but an agent must infer when to append versus rewrite or edit.

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?

Annotations declare destructiveHint=true and readOnlyHint=false, so the description's job is to add context — and it does: the operation is reversible (unarchive) and content is preserved and still readable by pad_id. That materially softens the 'destructive' reading and tells the agent the effect is renameable rather than erased.

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, zero padding, with the primary action and its reversal front-loaded before the side-effect explanation. 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?

An output schema exists, so return values need no explanation, and the description covers the required parameter's effect plus reversibility. The only thin spot is the project_id scope override, which is left entirely to the schema.

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 67%, with archived and project_id already documented in the schema; pad_id is bare but self-evident. The description's 'unarchive with archived=false' merely restates the schema's default note, adding little syntax or format detail beyond it.

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 ('Archive a pad') and immediately covers the inverse operation ('unarchive with archived=false'). It also implicitly distinguishes itself from the sibling pad_delete by noting the old content stays readable, so an agent can tell the two apart 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 clear context for use ('Archiving frees the name for a new active pad') and the condition that flips behavior (archived=false). It does not explicitly name when to prefer it over pad_delete or note any prerequisites, so it stops short of full when/when-not guidance.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description reinforces irreversibility rather than contradicting. It adds real value beyond the annotations by disclosing the concurrency-guard purpose of expected_revision, though it doesn't say what happens on a revision mismatch (fail vs. ignore).

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, front-loaded with the destructive action and the safer alternative; every clause carries 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?

With an output schema present, return values need no explanation, and the description covers irreversibility, the archive alternative, and the revision guard. The only omission is the failure behavior when expected_revision doesn't match.

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%, so the description must compensate; it explains expected_revision ('guards against deleting a pad someone just updated') which is the non-obvious parameter. pad_id is self-evident and project_id is documented in the schema, leaving only minor gaps.

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 ('Permanently delete a pad') and immediately contrasts it with the safer sibling 'pad_archive', so an agent can distinguish it from the other pad_* tools without reading 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?

Explicitly names the preferred alternative ('prefer pad_archive') and gives the reason ('Irreversible'), which is exactly the when-to-use/when-not guidance needed for a destructive tool.

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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the agent knows this is a non-idempotent mutation. The description adds useful behavioral context: only one literal occurrence is replaced, and old_text must match exactly once. It does not explain concurrency behavior, error handling on multiple matches, or the role of expected_revision, so it adds only moderate value beyond the annotations.

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 tightly written sentences with no wasted words. The core operation and the critical old_text matching constraint are front-loaded and immediately actionable.

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, so return values need not be explained, and annotations cover the destructive safety profile. The description adequately covers the core edit behavior, but it omits expected_revision semantics entirely and does not mention pad_id or project_id behavior, leaving gaps for a mutation tool with five parameters.

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 only 20%, so the description must compensate, but it covers only old_text and new_text semantics. It does not explain pad_id or expected_revision, and expected_revision is a critical optional parameter for a destructive edit tool. Partial compensation leaves significant parameter gaps.

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: replace one literal occurrence of old_text with new_text in a pad. It is clear and unambiguous, but it does not distinguish itself from sibling tools like pad_write or pad_append, so it falls short of the top score.

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?

The description gives an important usage constraint — old_text must match exactly once, and surrounding context should be included to disambiguate — which implies when this tool is appropriate. However, it does not state when to use pad_edit instead of alternatives such as pad_write or pad_append, leaving alternative selection unaddressed.

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?

The description describes a pure listing operation ('List pads'), but the annotations declare readOnlyHint=false, i.e., the tool is not read-only. For a tool whose stated purpose is listing, the annotation asserting non-read-only behavior is directly at odds with the description's implication, and the description does nothing to reconcile it (e.g., explain side effects such as access tracking or logging).

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 tight sentences: purpose first, then filter semantics. No wasted words and the front-loading is correct, though the terseness borders on under-specification rather than optimal concision.

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 6 parameters, no output schema, and only safety-oriented annotations, the description should carry more load. It covers purpose and two filter parameters but omits pagination behavior (limit/offset defaults), archived-inclusion semantics, and the non-read-only behavior, leaving an agent with 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 only 17% (just project_id), so the description must compensate. It does add real semantics for query (matches names AND content, returns a snippet) and tags (matches any listed tag), but says nothing about limit, offset, or include_archived, leaving a substantial documentation 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 ('List pads') with a meaningful scope qualifier ('without full content') that implicitly distinguishes it from the full-content sibling pad_read. The purpose is clear, though it never names the sibling explicitly.

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?

The phrase 'without full content' implies when to prefer this over pad_read, and the query/tags clauses hint at filtering use cases. However, there is no explicit when-to-use/when-not-to-use statement or named alternative, so guidance is only implied.

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?

The description adds real behavioral context beyond the annotations: offset/limit are measured in UTF-16 code units, there is no default cap, an end cut inside a surrogate pair moves back one code unit (or forward if moving back yields nothing), and the result reports the effective offset. The unexplained tension is that annotations set readOnlyHint=false while the tool is described purely as a read; if readOnlyHint was set deliberately this would be an inconsistency, though false is also the MCP default for an unset hint.

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 sentences, no filler, and the purpose is front-loaded before the pagination mechanics. The surrogate-pair sentence is dense but every clause carries load-bearing semantics rather than restating the name.

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 paginated read with no output schema, the description adequately covers what is returned (content, revision, metadata) and how offset/limit behave at the edges. It omits error behavior, size limits, and whether revision must be supplied for consistency, but nothing essential for a correct first call 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 description coverage is 60%: limit and offset already carry nearly the same UTF-16/surrogate wording the description repeats, and project_id has its own detailed scope note. The description's only net-new parameter information is that either pad_id or name may be used as the identifier and that the effective offset is echoed back, so it does little more than the schema already does.

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 resource: 'Read a pad's content, revision, and metadata by pad_id or name.' That clearly distinguishes it from pad_write/pad_append/pad_edit/pad_delete and pad_list. It stops short of explicitly naming or contrasting those siblings, so it lands just below the top tier.

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 implied by the verb 'Read' and the accepted identifiers, but there is no explicit when-to-use guidance: it does not say when to prefer pad_id over name, when to reach for pad_read rather than pad_list, or what to do if the pad does not exist. The only scope guidance lives in the schema (project_id), not the description.

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?

Annotations already declare destructiveHint=true and idempotentHint=false; the description reinforces this by stating the operation 'fully overwrites' and that overwrite requires passing expected_revision (optimistic concurrency). It also discloses that pad names are unique per project, implying a duplicate-name failure. It does not say what happens if expected_revision is stale, which would round this out.

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, front-loaded with the create/overwrite distinction, followed by the uniqueness constraint and the alternative-tool routing. No filler; each sentence changes how the agent would call it.

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 and annotations cover the safety profile, so return values and destructiveness need not be restated. The description covers both modes, the concurrency contract, uniqueness, and siblings. The only material gap is behavior on revision mismatch and tag merge semantics.

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 only 33% (pad_id and project_id documented in-schema), so the description must compensate for name, tags, content, expected_revision. It adds meaning for pad_id+'expected_revision' and for name uniqueness, but says nothing about tags semantics (replace vs merge) or content format. Baseline 3 given partial coverage and 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+resource and distinguishes two modes: create a new pad, or 'fully overwrite one by passing pad_id plus expected_revision'. It also names the sibling pad_append/pad_edit as the lighter-weight alternatives, so an agent can separate this from neighboring pad tools without reading 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?

Explicitly routes the agent: 'Prefer pad_append/pad_edit for targeted changes', giving the condition that selects the alternative. It lacks an explicit when-not for this tool (e.g. don't use to add a single line), but the guidance is clear and actionable.

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?

Annotations already declare idempotentHint=true and destructiveHint=false. The description reinforces this with the concrete behavior 'returns the existing project if the path is already registered,' which is useful added context. It omits permissions/auth requirements, keeping it from 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?

Three short sentences, each earning its place: what it does, the path default, and duplicate behavior. Front-loaded and waste-free.

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 an output schema present, return values need not be explained, and annotations cover the safety profile. The one gap is the undocumented 'name' parameter, but otherwise the description is complete for a simple registration tool.

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% for 2 parameters, so the description must compensate. It explains the 'path' parameter's default (cwd) but says nothing about 'name', leaving half the parameters undocumented.

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 ('Register a directory as a project') and adds scope details (default path, duplicate handling). It does not differentiate from siblings like project_list or project_select, so it falls short of a 5.

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?

The default-to-cwd behavior and the 'returns existing project if already registered' note imply usage context, but there is no explicit when-to-use-this-vs-alternatives guidance and no mention of project_select or project_list.

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?

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, which is in tension with a verb ("List") that reads as a pure read. The description does nothing to resolve that: no mention of side effects, permissions, or why a listing operation is not flagged read-only. With annotations present the bar is lower, but it adds zero context beyond the annotations.

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 most important information — that this lists projects — is the first word.

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 zero-parameter read tool with no output schema, the description does state what is returned (the project list plus the current selection). It could say more about the return shape (names vs. IDs, how the selection is marked), but the core need is covered.

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?

Zero parameters and an empty properties object, so there is nothing for the description to disambiguate; the baseline for a no-param tool 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 (list) and resource (registered projects) plus an extra detail — the currently selected one — so the agent knows exactly what comes back. It sits clearly alongside project_add/project_select/project_prune in the sibling family, though it never names those siblings or distinguishes itself from them explicitly.

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?

No when/when-not guidance and no alternatives named. Usage is only implied: an agent can infer that this is the discovery call before project_select or project_prune, but the description never says so.

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?

Annotations already declare destructive=true and idempotent=true, and the description adds substantial context beyond them: snapshot-before-delete, single-transaction deletion, per-table count reporting, preservation of queen_audit rows and other projects' lead-idle subscriptions, live-pane refusal, and the lock refusal. Far exceeds the annotation bar.

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 primary sweep behavior and dense with content, but it is a long run-on paragraph with some repetition ('removes exactly that one project') and no structural breaks for the three modes. Every clause is arguably load-bearing, so waste is low.

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 destructive, multi-mode tool with an output schema and 0% param coverage, the description covers the refusal conditions, transaction semantics, side effects on related tables, and the lock constraint. Nothing an agent needs to call it safely 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 description coverage is 0%, so the description must carry the semantics. It explains project_id (single-project removal, only if empty) and confirm_name (exact name enabling forced removal), plus the edge case that confirm_name without project_id is refused. Strong coverage, though it does not restate the integer/exclusive-minimum type constraints.

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 (delete/prune), resource (registered projects owning no rows), and scope, then distinguishes three distinct operating modes (bare sweep, project_id, project_id+confirm_name). An agent can tell exactly what this does versus sibling project_list/project_add/project_select.

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?

Explicitly names when each mode applies, when the tool refuses (owns rows, live pane, HIVE_PROJECT_LOCK=1, confirm_name without project_id), and that there is no forced sweep or dry-run. This is detailed when/when-not guidance.

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?

Annotations declare this is a non-read-only, idempotent, non-destructive, closed-world operation. The description adds genuinely useful context beyond that: the effect is session-scoped state that mutates the behavior of subsequent tools. It does not cover what happens on an invalid or nonexistent project_id, nor whether the selection persists across sessions.

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 that carries the effect and the scope with zero filler. Nothing to trim.

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 tiny one-parameter session-state tool with no output schema and annotations covering the safety profile, the description conveys the essential behavior. Missing only edge-case behavior on invalid ids and persistence semantics.

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?

One parameter with 0% schema description coverage, so the schema gives only type and bounds (positive integer). The description's 'which project' implies the parameter is a project identifier but adds no format, source, or validation meaning beyond that.

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 ('Set') and the resource it affects ('which project later tools act on'), plus the scope ('in this session'). This clearly distinguishes it from project_add, project_list, and project_prune, though it never names those siblings explicitly.

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?

The phrase 'later tools act on' implies this should be called before project-scoped operations, giving indirect usage context. However, it does not state when-not to use it, what happens if a project is already selected, or point to any alternative.

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?

Annotations already declare read-only/idempotent/non-destructive, yet the description adds substantial context they do not cover: default 20 / max 100, 30-day retention with a 20,000 id-range backstop, the crash-consistency caveat about an unrecorded terminal send, and per-caller visibility scoping. This is exactly the behavioral context annotations cannot express.

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?

Six front-loaded sentences: purpose first, then refusal-row contents, visibility, limits, retention, and a caveat. Dense but each sentence carries non-obvious information; only the ordering/refusal details feel slightly compressed.

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, the description partially covers return shape ('refusal rows include outcome=refused and the problem', 'newest first') but not the full row structure. For a 2-parameter read tool the retention, scoping, and crash caveats make it largely complete.

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?

At 50% schema coverage only project_id is documented in-schema. The description compensates by explaining limit's default (20) and cap (100) and by restating the visibility rule that governs project_id ('queen may read all targets; other callers see only their own project'), adding meaning 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 (list) and a precisely scoped resource (confirmed queen writes and refused cross-project guard calls, newest first). No sibling shares this 'audit' surface, so the scope is unambiguous and an agent can tell exactly what it returns.

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?

The content and visibility rules imply an auditing/inspection use case, but there is no explicit when-to-use statement, no prerequisites, and no named alternative. Usage is left to inference rather than stated.

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?

Adds substantial behavior beyond the annotations: the answer update commits atomically with any wake, the answer remains readable via `question_get`, answered/withdrawn questions refuse with `QUESTION_STATE_CONFLICT`, and `wake_id` means queued not delivered. These are meaningful operational traits that the readOnly/destructive/idempotent hints do not convey.

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?

The purpose is front-loaded and the sentences carry real rules, but the wake-routing passage is dense and refers to fields absent from the schema, adding cognitive load without clarifying the actual call surface. Appropriately sized for a complex tool, but not tightly structured.

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, so return values need not be described, and the conflict/atomicity behavior is well covered. However the mismatch between the wake fields named in the description and the three-field input schema leaves the actual invocation surface incompletely aligned.

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%, so the description must carry the load. It explains `answer` well ('a picked option label or free text, including text outside the offered labels') but gives only a tautological gloss for `notes` and no meaning for `question_id`. It also references `wake_id`, `wake_skipped`, and `wake_rerouted_to`, which do not appear in the input schema and could mislead an agent into trying to pass them.

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: 'Record the human's answer to a pending or defaulted question in this project, plus optional notes.' The scope (pending or defaulted questions) is clear and it implicitly relates to `question_get` for readback, but it never explicitly differentiates itself from the sibling `question_update`.

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 conditional routing: when you are the asker skip the wake, otherwise queue a wake to the running asker, falling back to the project's running lead, and skip again if no lead runs. This is clear when-to-use guidance for the wake behavior, though it does not compare against alternative tools for recording answers.

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?

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), and the description adds rich behavior beyond them: the record is only stored and the agent must surface the question itself, the caller must be a wakeable session, an ordinary wake is queued on answer, and ref-with-pending-question updates rather than inserts. This is substantial disclosure.

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?

Dense and front-loaded with the core purpose, and almost every clause adds actionable information (dedupe, default_answer, wake-on-answer). It is long and clause-heavy, but there is little 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?

An output schema exists so return values need not be explained, and the description nonetheless covers the full lifecycle: creation, dedupe, human presentation, wake-on-answer, and follow-up read. Nothing material is missing for correct invocation.

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%, so the description must compensate, and it does: it defines kind=choice vs free_text, the 2-4 option shape with exactly one recommended, the 12-character header limit, default_answer semantics per kind, and ref as a dedupe key. It adds meaning over the schema's field descriptions.

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?

Opens with a specific verb+resource ('Record an open question for the human'), scoped to project and asker. It is clearly separable from siblings: question_update updates an existing row, question_get reads it, question_answer answers it. An agent can route correctly without opening other 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?

Gives concrete conditional guidance: use kind=choice vs free_text, pass ref to dedupe, and 'so you can question_update one instead' routes to an alternative. It also instructs the agent to put the question to the human itself and to read via question_get. Missing only explicit when-not-to-use framing, hence not 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered. The description adds that the question can be in 'any state' and returns its answer and notes once answered, which is modestly useful context about return content, but says nothing about error behavior for unknown ids or visibility rules.

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 waste; the verb, scope, and return-content hint are packed efficiently.

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 single-resource get with no output schema, the description covers the essential scope and indicates what comes back. It is nearly complete, missing only failure/edge-case behavior.

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?

There is one parameter (question_id) with 0% schema description coverage, so the description must carry the load. It says 'by id' and 'in this project', which tells the agent the id is project-scoped, but adds no format, range, or failure semantics beyond that.

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 (Read) and resource (question), scoped to 'one ... by id', which distinguishes it from the sibling question_list. It stops short of explicitly naming the alternative, but the singular-vs-list contrast is clear.

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?

The phrase 'by id' implies when to use this rather than question_list, but there is no explicit when-to-use/when-not guidance and no named alternative. Usage is inferable rather than stated.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the two-group segmentation, 'defaulted = acted on by default but still reversible', and oldest-first ordering within groups. It stops short of describing return shape or volume, so not 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?

Two tight sentences, front-loaded with the primary action and grouping, then exclusions and the sibling pointer. Every clause carries information; nothing is redundant.

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, the description usefully characterizes the return set (two ordered groups, exclusions applied). For a simple no-param list tool this is close to sufficient, though it omits any sense of result volume or per-item fields.

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 takes no parameters and schema coverage is reported at 100%, so there is nothing for the description to compensate for. Baseline for a zero-parameter tool is 4.

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 (this project's pending and defaulted questions) with explicit scope and grouping. It clearly distinguishes itself from question_get by naming that sibling for single-item reads.

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 explicit inclusion criteria (pending, then defaulted) and exclusions (answered and withdrawn are not listed), plus the alternative to use for reading an individual question. An agent needs no inference to decide when to call this.

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?

Annotations already cover read-only, destructive, idempotent, and open-world hints. The description adds substantial behavioral context beyond those: revalidation after edits, the state machine (defaulted can still be withdrawn), permission requirements for state changes, and immutable fields (ref, asker, wake target).

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?

The description is dense but front-loaded with the core action before moving into state semantics and constraints. Every sentence carries useful information, though the single long paragraph could be slightly more scannable.

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 the mutation tool's complexity, the available annotations, the input schema, and the presence of an output schema, the description supplies the missing state-machine rules, permissions, and immutability constraints. An agent has enough to invoke it correctly without needing return-value details in the 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?

With 0% top-level schema description coverage, the description compensates by naming the editable text fields (question, header, options, default_answer) and explaining the state parameter's two enum values and their meanings. It does not explicitly describe question_id, but the purpose sentence and required-field context make its role inferable.

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: edit a pending question's text or move it out of pending via state. It clearly distinguishes update from other question operations like ask/get/list/answer by focusing on pending-question modification and state transitions.

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 explicit when-to-use conditions (editing pending text, setting state=defaulted or withdrawn) and when-not constraints (answered or withdrawn questions cannot be changed; moving state needs the asking session or human). It does not name alternative sibling tools, so it falls short of a full 5 but provides strong contextual routing.

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?

Goes well beyond the annotations (destructiveHint, idempotentHint, readOnlyHint) by disclosing the visibility side effect: archived todos drop out of todo_list by default while todo_get still reaches them by id. It also states a hard precondition that causes refusal, which isn't derivable from the 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?

Three tight sentences with zero filler, front-loaded with the primary action and then the effects and refusal rule. Every clause carries information the 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?

An output schema exists, so return values need no explanation, and the description covers the mutation's effect, visibility semantics, and failure precondition. Nothing an agent needs to invoke this correctly 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 67% and both non-trivial parameters (archived, project_id) already carry their own descriptions. The description only restates the archived=false unarchive behavior and adds no syntax or constraint detail for project_id or todo_id, so it does little 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 ('Archive a todo') and immediately covers the inverse operation ('unarchive with archived=false'), which an agent can act on without opening the schema. It also distinguishes itself from siblings by explicitly referencing pad_archive, todo_list, and todo_get.

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 clear context for both modes of use and names the refusal precondition (todo still blocks an incomplete todo), which tells the agent when the call will fail. It stops short of naming an alternative for the delete-vs-archive decision, so it is not fully explicit about alternatives.

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?

Annotations already disclose the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description's job is to add what they cannot. It does exactly that by disclosing that cycles are rejected — a concrete failure mode an agent must anticipate before calling. It stops short of saying what happens on a duplicate blocker, whether cross-project blockers are permitted, or whether any permission is required.

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, no filler, and the operative definition of the argument roles is front-loaded ahead of the constraint. 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?

With an output schema present, return values need no explanation, and the annotations carry the mutation/idempotency profile. The description covers purpose, edge direction, and the cycle-rejection failure mode, which is enough to call it correctly; it is only slightly thin on the duplicate-edge and unblock-counterpart cases.

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%, with todo_id and blocker_id documented as bare positive integers, so the description must carry their meaning — and it does, by defining the direction of the edge (todo_id waits on blocker_id), which is the single most important semantic here and is not derivable from the schema. project_id is richly documented in the schema itself, so it needs no help from the description; the remaining gap is minor.

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 precise verb-plus-resource ('add a blocker') and defines the resulting semantic relation — todo_id cannot start until blocker_id completes — which is far more informative than the tool name alone. It does not, however, name its obvious counterpart sibling todo_unblock, so an agent must infer the reverse operation from the tool list.

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 implied rather than stated: an agent can infer this is the tool for expressing a dependency between two todos, and the sibling todo_unblock clearly reverses it. There is no explicit 'use when / do not use when' framing, no mention of todo_unblock, and no guidance on when a dependency should be modeled as a blocker versus some other mechanism.

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?

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the safety profile is covered. The description adds the handoff framing but says nothing about whether comments are append-only, editable, or ordered, so it adds modest value beyond the structured hints.

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 short sentences, action first, elaboration second, with zero filler. The purpose is front-loaded before the handoff guidance.

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, so return values need not be explained, and the tool is a simple 3-param write. However, the undocumented body/todo_id semantics leave an agent guessing about comment content constraints and todo_id validity given the 33% schema coverage.

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 33%: only project_id carries a description, while body and todo_id are bare in the schema and wholly unexplained in the description. With low coverage the description is expected to compensate, and it does not clarify comment length/format or what todo_id must reference.

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 ('Add a comment to a todo'), which is clearly distinct from the todo_get/todo_update/todo_complete siblings by action and artifact. It never explicitly names or contrasts a sibling, so it stops short of a 5.

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 concrete usage context ('Use for handoffs: changed files, tests run, decisions, remaining risk') so an agent knows what content belongs here. It offers no when-not-to-use guidance or named alternative (e.g. todo_update for field changes), keeping it below 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?

Annotations already disclose destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is largely covered. The description adds genuinely non-obvious side-effect information — that completion newly unblocks other todos and returns their ids — which an agent could not 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?

Two short sentences, front-loaded with the primary action and the flag behavior, with the return side effect last. No wasted words.

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 so return values need not be spelled out, and annotations carry the destructive/idempotency profile. The description covers the mutation, its inverse, and the unblocking side effect; only permission or scope prerequisites are unaddressed.

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 67%, and the description adds real meaning for the 'completed' flag beyond the schema's 'Defaults to true' by explaining that false reopens the todo. todo_id's semantics are left to inference, but the dual-mode explanation pushes past the baseline.

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 ('Mark a todo complete') plus the inverse operation ('reopen with completed=false'), which is more precise than the bare name. It does not explicitly differentiate itself from siblings like todo_update or todo_archive, so it falls short of the top score.

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?

Explicitly tells the agent how to reopen (completed=false), which is a real usage condition, and the schema's project_id guidance covers the scope question. There is still no when-not guidance or named alternative for general todo edits, so it is clear context rather than full routing.

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?

Annotations already declare the safety profile (non-readOnly, non-destructive, non-idempotent), so the description carries a lower burden. It adds downstream behavioral context — where the slug renders and that truncation happens in the dashboard — plus 'Returns a slim receipt'. It does not state authorization requirements or any side effects beyond rendering.

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 dense sentences, front-loaded with the core action, then parameter behavior, then the return. No filler. Slightly over-weighed toward the slug's rendering surface relative to the remaining six parameters.

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, so the return value needn't be explained ('slim receipt' suffices), and annotations cover safety. However, with 7 parameters and sub-50% schema coverage, the description leaves tags, priority, and title semantics to inference, which is thin for a creation tool with an ordering feature.

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 43%, so the description should compensate. It explains the slug rendering contract and blocked_by ordering semantics, but body, tags, title, and priority receive no description-level explanation, and the slug/blocked_by detail largely duplicates what the schema already documents.

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?

Opens with a specific verb+resource+scope: 'Create a project-scoped todo.' This clearly distinguishes creation from the sibling mutation tools (todo_update, todo_archive, todo_complete). It stops short of explicitly naming which sibling to prefer, but the operation is unambiguous.

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 conditional usage for two parameters: when to pass a slug (optional, rendering effect) and when to pass project_id ('Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope'). This is real guidance, but it is parameter-scoped rather than tool-scoped — there is no statement of when to create a todo vs. use another tool.

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?

The description says the tool 'Read[s]' a todo, but the annotations declare readOnlyHint=false, meaning the operation is not read-only. Nothing in the description explains this discrepancy or any side effect. This is an annotation contradiction.

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 returned fields are enumerated compactly right after the verb and resource.

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, the description usefully enumerates the return payload, which partially compensates. However, it leaves the annotation contradiction unexplained and does not document two of three parameters, so an agent lacks full context for correct invocation.

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%: todo_id and include_comments have no schema descriptions. The description's 'optionally comments' loosely maps to include_comments, but it says nothing about todo_id or the sensitive project_id override parameter, so it does not compensate for 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 (read) and resource (one todo) and enumerates the returned content: body, blockers, blocked-by, comments. It is clearly distinguishable from the sibling todo_list by scoping to a single item, though it doesn't name the sibling explicitly.

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?

There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as todo_list. The single-item scope hints at usage, but nothing tells the agent when this is preferable to listing or updating.

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?

Adds real behavior beyond the schema: archived todos are excluded by default (a default the schema's optional include_archived boolean cannot express), and query matches title, body, and slug rather than just title. Worth noting: the annotations set readOnlyHint=false while the description presents a purely read/retrieve operation, but the description never claims a mutation, so this reads as an imprecise annotation rather than a misleading description.

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 clauses, front-loaded with the core action and then the highest-value filters, with no padding or repetition. The clause-per-parameter style is slightly telegraphic but every sentence 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?

There is no output schema, nine parameters at 11% coverage, and no mention of pagination behavior (limit/offset defaults) or tags filtering, which an agent needs to page or narrow results correctly. The defaults it does cover (archived exclusion, dispatchable work) are the most important ones, so the definition is adequate but not complete.

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 only 11% (only project_id is documented), so the description carries most of the burden and it explains three of nine parameters: query (which fields it matches), is_blocked, and include_archived. tags, limit, offset, status, and priority are left to the schema's bare enum/type declarations, including the pagination defaults that a list tool should state.

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 todo summaries") and immediately qualifies the scope with filter semantics, which is more than a restatement of the name. It does not, however, name or contrast itself with the obvious sibling todo_get or the other todo_* tools, so the agent must infer the list-vs-single distinction from the name alone.

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 selection cues: is_blocked=false "finds dispatchable work" and include_archived=true is the only way to see archived items. Both are when-to-use conditions an agent can act on. It stops short of naming an alternative tool or stating when not to use this one (e.g., use todo_get for a single todo).

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?

Annotations already declare destructiveHint=true, idempotentHint=false, so the agent knows this mutates state and repeated calls differ. The description adds essentially nothing beyond that—it doesn't say whether the blocker record is deleted or just the link, nor whether the blocker_id must pre-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 tight sentence that is front-loaded with the core operation. Efficient, though it could have spent a few more words on parameter/behavior clarity.

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 an output schema and annotations already covering safety, the description needn't explain returns. However, for a destructive two-required-param mutation it leaves the identity of todo_id vs blocker_id and the required relationship state unclear.

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 only 33%: todo_id and blocker_id are undocumented in both schema and description. The description never clarifies which todo is the blocked one versus the blocker, or the parameter meanings, leaving the two required params ambiguous.

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 ('Remove') and resource ('blocker relationship from a todo'), which clearly distinguishes it from the inverse sibling todo_block. It does not, however, explicitly name or contrast itself with the sibling, keeping it short of a 5.

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?

The description offers no when-to-use guidance, no prerequisites (e.g. that the relationship must exist), and does not reference the related todo_block or alternative tools. An agent must infer all usage context.

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?

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false, so the safety profile is covered. The description usefully adds that omitted fields are preserved (partial update, not full replace) and that it returns a slim receipt, but does not explain what 'destructive' entails here — e.g., whether passing empty values clears 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?

Three short front-loaded sentences with no filler. "Returns a slim receipt" is slightly redundant since an output schema exists, but it is cheap and does no harm.

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 mutation tool with annotations and an output schema, the safety and return concerns are largely handled elsewhere. Still, the undocumented parameters and the unstated meaning of its destructive hint leave the definition thinner than the tool's complexity warrants.

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 only 25% — six of eight parameters (body, tags, title, status, priority, todo_id) carry no schema description, and the tool description adds no per-parameter meaning at all. It fails to compensate for the low coverage.

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 (update todo fields), which is clear on its own. However, it offers no differentiation from sibling mutators like todo_complete, todo_block, or todo_archive, so an agent can't tell from the description why it would pick this over those.

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?

"Omitted fields are preserved" conveys partial-update semantics, which implies when the tool is appropriate (patch-style edits). But it never states when to prefer it over todo_complete/todo_archive for terminal states, nor any prerequisites, leaving routing to inference.

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?

Beyond the annotations (destructive=true, idempotent=true), the description discloses rich side-effect semantics: cancelling a wake also cancels its hold notices, cancelling a standing watch cancels undelivered FINISH notices, but deliberately does NOT cancel a watch's per-worker block notice. This is exactly the kind of non-obvious behavior an agent needs.

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 the core purpose well, but the back half is a dense, comma-heavy exposition of notice semantics that is far longer than needed to convey the key point (which notices are and aren't cancelled). Several clauses could be tightened without losing 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 so return values need not be explained, and the description thoroughly covers ownership, scope, and side effects. The main gap is the undocumented wake_id parameter, but overall an agent has enough to invoke it correctly.

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%; project_id is documented in the schema, but wake_id has no description. The description touches on project scope ('any pending wake-up in this project') yet does not clarify what wake_id refers to or its format beyond the schema's integer constraint. Baseline 3 is appropriate given partial coverage.

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 ('cancel') and resource ('pending wake-up') with an explicit scope rule: own wakes, or any project wake if you are a running lead. This clearly distinguishes it from siblings like wake_set, wake_get, and wake_update.

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?

The ownership/lead-permission condition is clear implicit guidance for who may call it, and the project_id description in the schema reinforces staying in current scope. It does not, however, explicitly contrast with alternatives such as wake_update or state when cancellation is preferable to updating.

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?

The description presents a pure retrieval operation ('Read one wake-up by id') while the annotations declare readOnlyHint=false, so the definition and the structured metadata disagree about whether calling it can mutate state. This is an annotation contradiction; the otherwise rich detail about delivery_method/delivered_by/socket_attempt_at does not resolve the conflict.

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?

The key differentiator (untruncated body, vs wake_list) is front-loaded in the first sentence, and the remaining bulk documents return fields that no output schema covers, so it largely earns its space. The delivery-state sentence is a dense run-on enumerating several fields, which 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?

With no output schema, the description usefully documents the returned delivery state (delivery_method, delivered_by, socket_attempt_at, fire_count, delivered_by_note), which is the main completeness need. It does not cover failure behavior for a missing id or acknowledge any side effects, which is a residual gap.

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 50% (project_id documented, wake_id not). The description reinforces scope ('by id, in this project') but adds no format or behavioral detail beyond the schema, and does not touch the project-override rule that the schema already carries. Baseline 3 is appropriate at this coverage.

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 opening sentence gives a specific verb (Read), a specific resource (one wake-up by id), scope (in this project), and a distinguishing property (UNTRUNCATED body). It explicitly contrasts itself with the sibling wake_list, so an agent can route between them 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 states exactly when to use this over the alternative: wake_list truncates the body at 120 chars, so use this to see the full text or to verify what wake_update just changed. That is an explicit use-case plus a named alternative and the condition selecting it.

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?

The description frames a pure retrieval operation ('List pending wake-ups', 'where to check') with no side effects, but the annotations declare readOnlyHint=false, i.e. it is explicitly NOT a read-only tool, and no mutation or side effect is disclosed anywhere in the text. This is a direct inconsistency with the annotations, so per the rubric it scores 1. (The description does otherwise add useful lifecycle detail, but the contradiction governs.)

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 ('List pending wake-ups in this project'), then layers the secondary payload detail. The parenthetical field list is dense but earns its place since there is no output schema to document the return shape.

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, the description correctly compensates by enumerating the returned delivery-state fields (typed_at, held_at/held_reason, confirmation, delivery_method, delivered_by, socket_attempt_at) and explaining the pending-vs-delivered lifecycle. The one missing piece is any disclosure of the non-read-only behavior implied by the annotations.

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?

There is a single parameter and schema description coverage is 100%: the schema already explains the project_id scope override in detail. The description only echoes this with 'in this project', so the baseline of 3 applies — the schema carries the semantic load.

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 pending wake-ups in this project') plus the secondary collection ('recently_delivered'), which is concrete enough to separate it from wake_get/wake_cancel. It does not explicitly name a sibling to contrast against, so it stops short of a 5.

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?

'recently_delivered is where to check whether it was actually typed and, if its target has a confirmation channel, acknowledged' tells the agent when to consult this tool's second collection, and the note that a one-shot wake leaves the pending list the moment it fires explains why a now-missing wake should be looked up here. No explicit when-not or named alternatives, so 4.

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?

Annotations cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds real mechanism the annotations cannot: the body is injected as a fresh user turn into a terminal, tagged with a wake counter, and defaults to THIS session. It omits failure/expiry behavior and how the wake can be cancelled (wake_cancel exists), which keeps it below 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 operation, then defaults, then the body-authoring guidance. Every sentence carries information, though the body-writing advice in the final sentence is somewhat verbose for the delivery it provides.

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?

Output schema exists so return values need not be described, and the definition covers the injection mechanism, the default target, and how to author the body. The remaining gap is repeat_every_seconds semantics and the wake lifecycle (cancellation/update) relative to its wake_* siblings.

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 40%; deliver_to and project_id carry schema descriptions, and the description usefully explains delay_seconds' effect and prescribes what body should contain. However repeat_every_seconds is left entirely undocumented in both schema and description, leaving a real 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+resource (schedule a wake-up) and goes further by explaining the delivery mechanism: after delay_seconds the body is typed into the target session's terminal as a fresh user turn, prefixed [hive wake #N]. This is enough to distinguish it from wake_when_idle, wake_get, and wake_cancel without opening their 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?

"Use instead of polling" is an explicit when-to-use directive, and the closing sentence gives conditional guidance for the own-lead-pane case. It stops short of naming the sibling alternatives (wake_when_idle, agent_send) or stating when not to use it, so it is clear context rather than a full routing rule.

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?

Goes well beyond the annotations (destructiveHint=true, idempotentHint=false, readOnlyHint=false) by disclosing subtle runtime semantics: delay_seconds is relative to NOW, repeat_every_seconds only affects firings after the current one and does not move the next fire time by itself, and idle wakes accept only body. These are non-obvious mutation effects an agent could 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?

Front-loaded with the core action, then the caveats, with no filler sentences. It is information-dense but runs long, and the repeat/delay interplay takes two passes to parse fully.

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 5-param mutation tool with an output schema (no need to describe returns), the description covers the pending-only constraint, field applicability per wake type, and the relative timing semantics. Nothing material is missing for correct invocation.

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 only 20%, so the description must compensate, and it does for delay_seconds, repeat_every_seconds and body with precise relative-vs-absolute semantics. wake_id and the project_id override are left to the schema (project_id has its own description), a minor remaining 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+resource (edit a pending wake-up) and the key differentiator from wake_set: in-place edit without minting a new id. An agent can separate it from the create/cancel siblings immediately.

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?

Explicitly scopes usage: 'Only a still-pending wake can be edited', and spells out which fields apply to a delay wake vs an idle wake from wake_when_idle. It even names wake_get as the read-back alternative, so alternatives are covered.

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