hive

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

With no annotations, the description carries the full burden. It discloses global scope (never scoped to caller's project), the reason a project-scoped scan would be unsafe, that the caller's own actor is never pruned, the lock refusal, and that deletion is immediate and permanent with no dry-run mode.

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?

Although not short, the description is information-dense and every sentence contributes: scope, safety, lock behavior, ordering, and permanence. The most important action and criteria are front-loaded, and the length is justified because no annotations exist to cover destructive behavior otherwise.

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 global operation with zero parameters and no annotations, the description covers prerequisites, exclusions, broader context, and safety. An output schema exists, so not describing return values is acceptable. Nothing needed for correct invocation or risk awareness 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?

The tool has zero parameters and a vacuous schema, so the baseline of 4 applies; there is no parameter meaning left undocumented. The description's listed tables and field-by-field coverage add operational criteria rather than parameter details, which is appropriate here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence uses a precise verb ('Delete') and resource ('actor') and defines the exact pruning condition (owns no rows in listed tables and inactive for a minute). It also ties this to sibling project_prune, making its role in store sweeping 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?

It explicitly instructs when to run it ('after project_prune when sweeping the store'), explains why the order is safe today and in the future, and states that it refuses under HIVE_PROJECT_LOCK=1. This gives the agent clear selection and sequencing guidance relative to its sibling.

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

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

With no annotations, the description carries the full burden and does so exceptionally. It discloses side effects (terminal output not retained), prerequisites (capture handoffs), a confirmation requirement (confirm_self=true), and refusal/retirement conditions for lead targets. This is rich, honest behavioral 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?

The description is three sentences, front-loaded with the core action, and each sentence adds crucial information (side effect warning, self-close requirement, lead restrictions) without redundancy. It is efficient and well-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?

For a mutation tool with no annotations and an output schema present, the description covers the essential behavioral aspects: the action, side effects, prerequisites, and refusal conditions. It is sufficiently complete for an agent to invoke it correctly, with return values handled by the separate output 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 coverage is 75%, so baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies that name and agent_id are alternative addressing methods and that confirm_self is specifically for closing yourself. This provides useful usage context for parameters.

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 clearly states the action ('Kill an agent's tmux window and mark it closed') and the target addressing ('by name (or agent_id)'). It is specific enough to distinguish from siblings like agent_park or agent_status, though it does not explicitly name alternatives.

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 operational constraints (capture handoffs before closing, confirm_self for self-close, lead restrictions) but does not explicitly state when to use this tool versus alternatives like agent_park or agent_resume. It lacks explicit when-to-use/when-not-to-use 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?

With no annotations, the description carries the full behavioral burden. It discloses inclusion semantics (running vs closed/parked), ordering (newest first for include_closed), limit bounds, and pagination via next_before_id/before_id. It does not describe response fields or the sort order for the running-only mode, but the core behavior is well 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?

The description is compact and front-loaded with purpose. Each clause adds meaningful detail about modes, defaults, bounds, or pagination, with no filler or repetition of schema content.

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 list tool with no output schema, it explains scope, filtering, ordering, limits, and pagination clearly. The main missing piece is what fields each agent row contains, though 'with live status' gives a reasonable expectation. Overall, it is complete enough 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 already documents limit, before_id, and project_id. The description adds relational semantics: include_closed toggles which agents are included, limit applies only in that mode, and before_id acts as the pagination cursor. This goes beyond merely repeating 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?

The description opens with a specific verb and resource: 'List this project's agents with live status.' This clearly identifies the operation and scope, and it is distinct from sibling tools like agent_status (single-agent status) or agent_close (mutation).

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 the two modes (without include_closed vs with include_closed) and when to use before_id for pagination. However, it does not explicitly name an alternative tool or state when not to use agent_list, so it stops short of full exclusion 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?

With no annotations, the description carries the behavioral burden and does well: it explains storage-only-for-shortened-messages, pruning after 7 days, and the distinct pruned-id error behavior. It stops short of stating permissions or read-only assurances, but 'Read' plus the lookup semantics make the operation clear.

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 then gives necessary contextual details. Each sentence adds useful information about storage, id availability, or pruning; it is slightly dense but not wasteful.

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 lookup with no output schema, the description provides the critical operational context: id source, when records exist, and pruning behavior. It does not describe the return value shape, but the phrase 'in full' plus the tool name make it sufficiently clear 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%, and the description compensates for the undocumented message_id by explaining that it comes from a specific pointer line format. The project_id parameter is already documented in the schema with a clear override rule, so no additional description is needed 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 opens with a specific verb and resource: 'Read one agent-to-lead message in full, by the id'. It clearly differentiates this tool from generic read or list tools by explaining exactly what kind of message it reads and how the id is sourced.

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: only for shortened messages stored by hive, identified by a pointer line. It also states an exclusion: every other send stores nothing and has no id to read, so the agent knows not to attempt this tool in those cases.

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

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

No annotations are provided, so the description carries the full burden. It discloses useful behavioral details: default 50 lines, max 200, and addressing by name or agent_id. However, it does not describe error behavior, what happens when no name/agent_id is passed, whether output is plain text, or how the rendered terminal is returned. Adequate but incomplete.

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 with no filler. The core action is front-loaded, key defaults are included, and the practical usage instruction is appended in a tight, memorable way. Every word 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 simple read tool with no output schema and no annotations, the description gives the essential purpose and one key usage rule, but leaves gaps around return format, error conditions, and invocation without any address. It is workable but not fully self-sufficient.

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 75%, and the schema already documents name, agent_id, and project_id. The description adds the default line count and the 'name or agent_id' addressing concept, which supplements the schema for the 'lines' parameter. This is useful but not extensive, so a 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?

The description opens with a specific verb and resource: 'Read the rendered terminal of an agent,' which clearly identifies the tool's core function. The additional phrase 'addressed by name or agent_id' clarifies the addressing modes. It does not explicitly name a sibling alternative, but the purpose is distinct from nearby tools like agent_status or pad_read.

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 instruction 'Read REAL output before declaring a worker done' gives an explicit when-to-use context that would help an agent know this is the verification step. It does not mention exclusions or alternatives, so it stops short of a 5, but the context 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?

With no annotations, the description carries the full transparency burden. It discloses the destructive action ('kill its pane'), the state distinction ('PARKED rather than plain closed'), a side effect ('record the branch'), and the return content ('board line plus the one call that brings it back'). This goes well beyond a generic 'parks a worker' statement, though it could mention preconditions like privileges or failure effects.

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 with zero waste: the first delivers the action, the second the decision rule versus agent_close, and the third names the resume counterpart. The key scoping distinction is front-loaded.

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?

The tool has meaningful side effects and a distinctive return ('board line plus the one call that brings it back'), all covered. The output schema exists so return details need not be repeated. The only gap is confirm_self semantics, which even the schema leaves blank, but this is minor given the overall guidance.

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 75% and the schema already provides rich guidance for name, agent_id, and project_id. The description adds no parameter-specific details and leaves confirm_self undocumented, but the schema handles most of the burden, so a baseline score of 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?

The description states a specific verb and resource with concrete outcomes: 'Park a claude or codex worker... kill its pane, mark the row PARKED rather than plain closed, record the branch, and hand back a board line plus the one call that brings it back.' It clearly differentiates from agent_close by the paused-vs-finished criterion.

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 gives the when-to-use rule: 'Use this instead of agent_close when the lane is paused, not finished,' and names the complementary tool: 'Resume it with agent_resume.' No ambiguity about when to pick this 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?

With no annotations to fall back on, the description fully discloses the operation's consequences: actor_id persistence and attribution retention, the live-worker retitle side effect that appears as a user turn, and the refusal of lead targets. This exceeds typical descriptions and leaves little hidden behavior.

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 dense sentences front-load the core action and then deliver high-value specifics (identity, side effect, timing, refusal) without redundancy. Every clause earns its place; there is 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?

The description covers the action, when to use it, behavioral consequences, and parameter nuances. An output schema exists, so return values need no explanation. For a mutation tool with no annotations, this is a complete and self-contained definition.

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?

Although schema coverage is 100%, the description adds meaningful clarifications beyond the schema: the preferred use of `name` over `agent_id`, precedence rules when both are given, partial-name matching behavior, and the 'override only when explicitly asked' rule for `project_id`. These nuances help an agent choose parameters correctly.

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: 'Change a worker's display name.' It clarifies that the actor_id remains unchanged, which distinguishes it from any sibling that might imply identity replacement. This precision is more than adequate for an agent to select 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?

Provides explicit timing guidance — 'rename between assignments rather than mid-task' — and discloses a refusal case ('Refuses a lead target outright'). It does not name alternative tools, but the uniqueness of the operation makes that unnecessary; the caution about mid-task use is valuable 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?

No annotations are provided, so the description carries the full burden, and it delivers: it discloses prerequisites (agent must be closed), the exact effects (fresh pane, same actor_id, full context restored), and a key limitation (does not send instructions). With zero annotation coverage, this is well above average, though it omits the failure behavior for calls on a running worker.

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 purpose, and every sentence earns its place: effects, addressing rule, and the agent_send follow-up. The claude/codex parenthetical adds cross-tool clarity without bloat. It is dense but compact—no filler, though it slightly crams multiple clauses into the opening sentence.

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?

Comprehensive for a moderate tool: purpose, addressing, post-conditions, and follow-up action are all covered, and the presence of an output schema means return values need no duplication. The only gap is the absence of any explicit error-state behavior (e.g., 'errors if the agent is already running'), but the CLOSED qualifier conveys the intent.

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%, with detailed per-parameter guidance (prefer name, agent_id wins on conflict, project_id only on explicit request), so the baseline of 3 applies. The description adds only marginal context—'addressed by name or agent_id among closed agents'—which confirms rather than extends the schema's already thorough semantics.

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 (Resume) + resource (a CLOSED claude or codex worker), with concrete effects spelled out: fresh pane, same actor_id, full prior context. The claude --resume / codex resume analogy reinforces the concept. Clearly distinguishable from siblings like agent_spawn (creates a new worker) and agent_park/agent_close (state changes the other direction).

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 operative constraint (only CLOSED agents), how to find them (agent_list(include_closed: true)), and explicitly routes the follow-up to agent_send, clarifying that this tool does NOT deliver the next instruction. It implies the 'don't use for running agents' exclusion via the CLOSED qualifier but never states it negatively; still, the routing and alternative tool naming are strong.

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

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

With no annotations present, the description carries full behavioral burden and it does extremely well. It discloses the sender-tag prefix, bracketed paste, Enter submission default, the exact 300-char lead threshold and pointer behavior, worker text non-truncation, keys mode, wait_ms returning the terminal tail, and both refusal cases (hive unclassifiable and tmux copy mode) with the copy-mode cancel command. No edge case is left undeclared.

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 long, but each sentence earns its place by detailing a distinct behavior or exception. It front-loads the primary function, then layers exceptions and constraints (lead limit, worker refusal, copy mode). The only minor deduction is for length—it could potentially be tightened by linking to annotations (which are absent) or splitting into structured notes, but given the complexity, the verbosity is justified.

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 7 parameters, no annotations, and no output schema, this description is exceptionally complete. It covers all invocation paths (text, keys), all failure modes (lead, hive, copy mode), retry instructions, related tools (agent_message_get), and parameter semantics (wait_ms tail, name vs agent_id precedence). An agent can call it correctly in every scenario without additional info.

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?

Despite schema coverage being 71% (text lacks a schema description), the tool description adds substantial meaning: it explains that 'text' can be any shape, is prefixed with sender tag, delivered as bracketed paste, and hits the 300-char lead exception; it explains 'keys' are tmux names and how they bypass refusal; it clarifies 'wait_ms' behavior (returns terminal tail) and the precedence rules for name vs agent_id. This goes far beyond the raw 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?

The description states a specific verb ('Type into an agent's terminal') and resource (agent by name or agent_id), and clarifies the delivery mechanism (bracketed paste, Enter submit). It distinguishes itself from sibling tools like agent_spawn, agent_resume, agent_message_get, and agent_close by describing its core function unmistakably. The lead exception and refusal conditions further pin down exactly what it does, so an agent can tell it apart from all siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: text for normal input, keys for tmux key events, and warns against using text to a lead beyond 300 chars (with pointer fallback and pointer to agent_message_get). It states when text path is refused (unclassifiable hive, copy mode) and provides a retry path. It also implies the relationship to agent_spawn by noting a claude worker is already briefed, giving clear context without listing 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It extensively covers side effects: automatic briefing, refusal of unauthorized harnesses, project locking, inability to type into unclassifiable command panes, and human monitoring via tmux. This is well beyond a minimal statement of the action.

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 every clause carries meaningful information, and the core action is front-loaded. The long, semicolon-heavy sentences make it slightly harder to parse, but there is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 9-parameter tool with no annotations, the description covers defaults, refusal conditions, edge cases, project scoping, and monitoring. An output schema exists, so return-value explanation is not required. Nothing essential for calling this tool 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?

All 9 parameters are documented in the input schema, so the baseline is 3. The description adds valuable policy context around command/harness resolution and defaults, but it does not add per-parameter semantics beyond the schema's own descriptions. It neither harms nor significantly elevates parameter understanding.

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 ('Spawn a worker agent') and distinguishes this tool from downstream interaction tools by explaining what spawn does and what it refuses. It also clarifies the default command/harness behavior, leaving no ambiguity about the tool's purpose.

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 clear usage context: how to brief a claude worker, when commands/harnesses are refused, and which panes cannot be typed into later. It references agent_send's refusal behavior, but it does not explicitly contrast agent_spawn against other lifecycle siblings like agent_resume or agent_close, which would have made the guidance complete.

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

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

With no annotations, the description carries the behavioral burden. It discloses useful behavior beyond a simple 'returns status': it includes a short terminal tail, that include_brief returns the exact injected brief, and why hive stores that copy (appended system prompt appears in no transcript). This gives the agent meaningful expectations about privacy and provenance.

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 the core purpose, with the include_brief explanation earning its place by clarifying why a non-obvious behavior exists. There is no filler or redundant schema repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only status tool with four optional parameters and no output schema, the description covers the essential concepts: identification, terminal tail, and the brief-return option. It doesn't detail exact return fields or unknown-agent behavior, but the schema fills parameter gaps and the tool is simple enough that this is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all four parameters and their constraints. The description adds some context around name vs agent_id and the purpose of include_brief, but it mostly repeats or lightly reinforces what the schema already states. The baseline of 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?

The description states a clear verb and resource: it returns detailed status for one agent, named or by agent_id. It also distinguishes itself from sibling tools like agent_list (listing) and agent_output by focusing on status plus terminal tail and optional brief. The scope 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 description clearly implies when to use it: when you need status for a single named agent, including terminal tail or the original brief. However, it does not explicitly contrast with related tools like agent_list or agent_output, nor does it state when not to use 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?

No annotations are present, so the description carries the full burden of behavioral disclosure. It discloses the two usage modes and the allowed topic set, but it does not explicitly state that the tool is read-only, what the output format is, or what happens with an invalid topic; these are minor gaps for a help utility but still leave some behavior unspecified.

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 sentence that front-loads the purpose, states the default behavior, and lists the accepted values. There is no filler or repetition of structured information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-optional-parameter, no-output-schema help tool, the description covers the invocation modes and all accepted topic values. It does not describe invalid-topic behavior, but that is a minor omission for such a low-complexity 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?

The schema only defines topic as a string with no description or enum, so the description must compensate. It fully compensates by explaining that omitting the parameter yields an overview and by enumerating all eleven valid topic values, giving an agent everything needed to invoke the tool correctly.

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 phrase 'Hive usage guidance' names both the resource and the purpose, and the rest of the sentence specifies the exact behavior: omit for an overview or pass one of the listed topics. This clearly distinguishes the help tool from the dozens of operational siblings by marking it as meta-guidance rather than an action.

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 explicit invocation guidance: omit the topic for an overview, or pass one of the enumerated topics for targeted help. It does not state a 'when not to use' condition, but since help is the only meta-tool among the siblings, no alternative tool competes with 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Delete a shared value by key,' omitting consequences like irreversibility, behavior on missing keys, idempotency, or return values. This is a destructive operation, so more context is needed.

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 a single, direct sentence with no wasted words. However, it is under-specified for a destructive operation, so while concise, it lacks the necessary contextual structure expected of a well-rounded definition.

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 tool's destructive nature and the absence of annotations, the description is insufficient. It does not explain safety considerations, error handling, or the project-scope default behavior. An output schema exists, so return values may be covered, but critical usage context 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 50% (only project_id has a description). The tool description adds nothing about the 'key' parameter or how project_id interacts with it, failing to compensate for the missing schema documentation. Agents get no additional meaning beyond the parameter names.

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 clearly states the action (delete) and the target (shared value by key), making the purpose obvious. It distinguishes from kv_set and kv_get by the verb alone, though it does not explicitly mention alternatives.

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 guidance on when to use this tool versus alternatives. There is no mention of when not to use it, prerequisites, or context such as project scope defaults beyond the schema description of project_id. The intended usage is implied but not 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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Get' without stating that the operation is read-only, has no side effects, or what happens when the key is missing. It does not mention error behavior or return format, which is a significant gap for an unannotated 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?

The description is a single, efficient sentence with no filler. It is appropriately sized for a simple get operation and front-loads the core action. 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?

For a tool with no annotations and no output schema, the description is incomplete. It does not state what the tool returns, how to handle missing keys, or the role of the optional project_id override. The agent must infer behavior from the name and schema, which is insufficient for a tool with potential project-scoping nuances.

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% (only project_id has a description). The description adds no parameter-specific information beyond the schema. It does not clarify the semantics of 'key' or explain how project_id affects behavior. Since coverage is not high, the description should compensate but does not.

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 (Get), resource (shared JSON value), and key access mechanism. It clearly differentiates from siblings like kv_list (enumerate) and kv_delete (remove), though it doesn't explicitly name them. It could be slightly more explicit about being a single-value fetch.

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 guidance on when to use this tool versus alternatives like kv_list or kv_set. The context of siblings is present but the description does not reference them or state exclusions. Usage is only implied by the name and description, not explicitly 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the prefix filtering behavior and implies read-only via 'List', but does not disclose what is returned (keys, values, or pairs), empty-result behavior, or any safety caveats. It adds the filtering behavior detail but stops short of describing the output contract.

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 sentence with zero wasted words. The action ('List shared values') is front-loaded and the optional filter is stated immediately after. Every word 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 simple two-parameter tool, the description is adequate but leaves gaps: it doesn't clarify what 'shared values' returns (keys, values, or key-value pairs), doesn't state that omitting prefix returns all values, and with no output schema and no annotations, the return format is left to inference. It's sufficient for a simple list operation but not 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 50% (project_id has a detailed description; prefix does not). The tool description adds meaning by explaining that prefix filters the list, which compensates for prefix's missing schema description. project_id is already well-covered by the schema, so the description adds nothing there. Overall the description adds marginal value beyond the schema but covers the key prefix semantics.

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 clear verb ('List') and a resource ('shared values'), and mentions the prefix-filtering behavior. It distinguishes itself from the sibling kv_get (get a single value) by the list semantics, though it doesn't explicitly name siblings. It's slightly ambiguous whether 'values' means keys, values, or key-value pairs, but the core purpose 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 description offers no guidance on when to use this tool versus alternatives like kv_get or kv_delete. The project_id schema description contains useful usage guidance (use ONLY when user explicitly asks for another project), but that lives in the schema, not the tool description, and the description itself provides no when/when-not direction.

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

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

With no annotations, the description carries the full behavioral burdenhand. 'Set' implies mutation, but the description does not disclose whether setting the same key overwrites existing values, what 'small' means as a limit, or what happens when a TTL expires. These are important gaps for a mutating KV 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?

Two short, front-loaded sentences with no fluff. The core action and sharing semantics come first, and the optional TTL is appended efficiently. Every phrase 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?

The core invocation details (key, value, optional TTL) and the sharing purpose are present, and an output schema exists so return values need not be described. However, missing overwrite behavior, size constraints, and TTL expiration details reduce completeness for a tool with no 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?

Schema coverage is 50%, with value and project_id already described. The description adds 'small' to value and clarifies TTL behavior in seconds, but it leaves 'key' unexplained and does not elaborate on TTL expiration semantics. It compensates partially but not fully for the undocumented fields.

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 uses a clear verb ('Set') and specific resource ('small shared JSON value'), and 'other sessions can discover' distinguishes it from the kv_get/kv_list/kv_delete siblings. It also signals the optional TTL, making the tool's purpose 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 description clearly states the intended use: storing a shared JSON value that other sessions can discover. It gives context for when this tool is relevant, though it does not explicitly name alternatives or state when not to use 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?

With no annotations provided, the description carries the burden of behavioral disclosure, and it does well: it states non-blocking semantics, that re-acquiring extends the lease, and that leases expire automatically. It does not detail what happens when the lease is already held by someone else, but the 'Try to' phrasing implies the operation may fail.

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 carrying meaningful information: the core action, renewal behavior, and expiry behavior. There is no filler, and the main purpose is front-loaded.

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 lease-acquisition tool, the description covers the essential behavioral context: non-blocking, renewal, and expiration. An output schema exists, so return-value details are not required in the description. The only minor gap is explicit conflict handling when another actor holds the lease.

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%, with key and project_id already described in the schema. The description adds some meaning by associating the key with a 'named lease' and implying ttl_seconds drives lease expiration, but it does not explicitly explain ttl_seconds units or behavior beyond 'expire on their own.'

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 clearly states the action: acquire a named lease on a shared work area, and adds key semantics like non-blocking, renewal, and expiry. It is specific enough to be distinguished from lease_release by obvious semantic opposition, though it does not explicitly name the sibling alternative.

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 implies usage: use this to acquire or renew a lease, especially when non-blocking behavior is desired. It gives one concrete usage tip (re-taking extends) but does not explicitly contrast with lease_release or state when not to use the 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It merely states the action without revealing side effects, return values, failure conditions, or permissions. For a tool that likely releases a lease (a mutating operation), this is a significant 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?

The description is a single concise sentence, which is structurally simple. However, it's so brief that it barely adds value beyond the tool name. It is concise but not efficiently front-loaded with essential context, so it doesn't fully earn 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?

Given that the tool has a mutating action, no annotations, and an ambiguous required parameter, the description is incomplete. It doesn't explain what a lease is, what 'release' entails, or how the key maps to a lease. The existing output schema helps, but the description still lacks critical 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?

The description adds no parameter information. The schema already documents project_id with a clear description, but the required 'key' parameter is left undefined. With schema coverage at 50%, the description should compensate but doesn't, leaving the meaning of 'key' 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?

The description states a specific verb and resource: 'Release a lease you own.' It clearly distinguishes from lease_acquire by the action. However, it doesn't explicitly differentiate from other lease-related tools or explain what 'lease' refers to in this context, 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 description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when not to use it, or suggest other tools like lease_acquire. The only implicit hint is 'you own,' which is a precondition but not 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?

With no annotations provided, the description bears the burden of behavioral disclosure. It communicates that the operation is non-destructive (append to end) and mentions a concurrency guard, which is valuable. However, it does not state what happens on revision mismatch, whether the pad must already exist, or what side effects occur beyond appending.

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 two short sentences with no filler. The primary action is front-loaded, and the expected_revision note earns its place by adding an important usage detail. This is appropriately sized for the tool's complexity.

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 append operation with an output schema, the description covers the core behavior and a key optional parameter. It misses important context like failure behavior on concurrent writes, whether a missing pad is created, and any permission requirements, which would be especially relevant since annotations are absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is low at 25%, but the description adds meaning for expected_revision by explaining its concurrency-guard purpose CST. project_id already has a detailed schema description, while pad_id and content are self-evident from their names and types. The description provides partial compensation but does not document every parameter's intended 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?

The description clearly states the action ('Append content') and the resource ('to the end of a pad'), which unambiguously distinguishes it from sibling tools like pad_write or pad_edit. The specific append-only semantics make the tool's purpose immediately obvious.

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 core usage context is explicit: append to a pad when adding content to its end. The optional expected_revision parameter is given a clear purpose ('guards against concurrent writes'), telling the agent when to use it. It does not explicitly name alternatives or exclusions, but the append operation is distinct enough to serve as clear usage 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?

With no annotations, the description carries the full disclosure burden. It discloses that the name is freed and content stays readable, and implies reversibility via unarchive. However, it does not mention any permissions, side effects, or edge cases (e.g., restrictions on archiving certain pads).

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 concise sentences. The core action is in the first sentence, and the second sentence adds a valuable behavioral consequence. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple toggle operation with an output schema present, the description covers the main behavior and consequences. It does not mention any potential failure modes or additional constraints, but these are not critical given the simplicity and the parameter descriptions.

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 schema already describes two of three parameters (archived and project_id) with useful guidance, and the description adds no parameter-specific details. With 67% schema coverage, the baseline of 3 is appropriate since the description does not compensate 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?

Clearly states the verb 'Archive' and the resource 'pad', and explicitly notes the unarchive behavior via 'archived=false'. It also distinguishes archiving from deletion by mentioning that content remains readable, making the purpose unambiguous even among sibling tools like pad_delete.

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?

Provides some context on when to use this tool (to free the pad name while keeping content readable), but does not explicitly name alternatives or state when not to use it. No exclusions or comparisons with pad_delete or other related tools are given.

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

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

No annotations are provided, so the description carries the full burden. It discloses the destructive and permanent nature ('Permanently delete', 'Irreversible') and adds a concurrency detail (expected_revision guards against deleting a just-updated pad). It does not describe effects on related resources (e.g., todos or comments referencing the pad), but the core behavioral traits are well 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?

The description is two tight sentences with zero filler. The core purpose ('Permanently delete a pad') is front-loaded, followed by the irreversibility warning, the sibling alternative, and the optional-parameter purpose. 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. For a destructive tool with one required self-evident parameter (pad_id) and one schema-documented parameter (project_id), the description covers the essential risk information: irreversibility, the preferred alternative, and the concurrency guard. A note on what exactly gets destroyed (associated content, permissions) would push it higher, but it is 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 description coverage is 33%, so the description must compensate for the gap on expected_revision, which it does by explaining the version-guard purpose. pad_id is self-evident and project_id already has its own schema description. The description adds value to one undocumented parameter but does not fully offset the missing semantics for the others.

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 uses a specific verb+resource ('Permanently delete a pad') that precisely states the action and object. It clearly distinguishes from siblings like pad_archive and pad_edit by emphasizing permanence, so an agent can tell what this tool does and what it is not.

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-not guidance by stating 'prefer pad_archive', naming the concrete alternative for non-destructive removal. It does not spell out the positive trigger conditions beyond 'permanently delete', but the destination criteria (irreversible deletion vs. archive) are clear enough to route correctly.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does disclose key behavioral traits — literal (non-regex) matching and the exactly-once constraint — which is genuine value. But it omits failure behavior (what happens with 0 or 2+ matches, error vs. no-op) and the concurrency role of expected_revision, both relevant for a mutating 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?

Two sentences totaling about 23 words. The core action is front-loaded ('Replace one literal occurrence...') and the constraint follows immediately. Every word earns its place; no filler or schema 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. But for a mutation tool with zero annotations and a 5-param schema at 20% coverage, the description should clarify expected_revision's concurrency purpose and the failure mode when old_text is absent or appears multiple times. The core operation is covered, yet these invocation-critical details are left to the agent to infer.

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% (only project_id is documented), so the description must compensate. It adds real meaning for old_text ('must match exactly once; include surrounding context to disambiguate') and new_text as the replacement. But pad_id and especially expected_revision (likely an optimistic-concurrency guard) remain unexplained, leaving a meaningful gap in a 5-parameter 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 ('Replace'), resource ('pad'), and precise semantics ('one literal occurrence of old_text with new_text'). The 'literal' qualifier and 'one occurrence' scoping clearly differentiate it from siblings like pad_write (full overwrite) and pad_append (add content), so an agent can select it correctly without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete invocation guidance: old_text must match exactly once, and the agent should include surrounding context to disambiguate. This tells the agent how to construct a valid call and when it will fail. However, it does not name sibling alternatives or state when to prefer pad_write/pad_append, so exclusion guidance is absent.

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

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

With no annotations, the description shoulders the burden of behavior. It does disclose non-obvious behavior: pads are returned without full content, query searches names and content and returns a snippet, and tags match any listed tag. However, it does not mention pagination, default limit, project scope, or archived handling, leaving gaps for a six-parameter 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?

The description is compact and front-loaded: the core purpose is in the first four words, and the filter semantics follow in a single sentence. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with six optional parameters and no output schema, the description captures the central behavior and filter semantics. It omits return-shape details beyond 'snippet,' pagination behavior, and the project scope rule, so it 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 17%, so the description must compensate. It adds meaningful semantics for query ('matches names and content... returns a snippet') and tags ('any listed tag'), but says nothing about limit, offset, include_archived, or project_id. The remaining parameter names are self-explanatory, but the coverage is incomplete.

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 starts with a clear verb and resource: 'List pads without full content,' which immediately distinguishes it from sibling pad_read (which presumably returns full content). It also explains the query and tag filters, leaving no ambiguity about what the tool does.

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 guidance is given on when to choose pad_list over pad_read or other pad tools; 'without full content' implies the distinction but does not name the alternative or state conditions. There are no exclusions, prerequisites, or 'use instead' cues.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does communicate the read-only nature and the returned data categories, but it omits important behaviors such as what happens when no pad is found, whether pad_id or name is preferred if both are supplied, and any access constraints.

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 a single sentence with no filler. The action, object, result surface, and lookup mechanism are all front-loaded and every word contributes value.

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 operation the description is fairly complete: it identifies the lookup keys and the returned information categories. However, with no output schema and no annotations, the absence of a stated requirement to provide at least one of pad_id or name, and the lack of no-match behavior, leaves some invocation ambiguity.

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 low (33%), so the description must compensate. It adds meaning by presenting pad_id and name as alternative identifier keys, but it does not explicitly state that at least one is required or define precedence if both are passed. project_id is already described in 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?

The description uses a specific verb ('Read') with a clear resource ('a pad's content, revision, and metadata') and identifies the lookup modes ('by pad_id or name'). This clearly distinguishes pad_read from mutation siblings like pad_write, pad_append, pad_edit, and pad_delete.

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 read action implies when to use the tool, but there is no explicit guidance about when not to use it or which siblings are alternatives. It does not state exclusions or provide routing cues beyond the verb itself.

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

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

With no annotations, the description must disclose behavior itself. It clearly states the destructive nature of overwrite and the revision mechanism, but does not explain what happens on revision mismatch or pad-not-found errors. It also doesn't mention any permissions or side effects beyond overwrite. This is adequate but leaves important behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The primary action and overwrite mechanism are front-loaded, and the alternative guidance is concise. 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?

Given the presence of an output schema (which presumably covers return values) and the schema descriptions for project_id, the description covers the core behavior, overwrite mechanics, and routing to siblings. It could be more complete by addressing error conditions (revision mismatch) but is largely sufficient for an agent to call 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 description coverage is only 33%, so the description should compensate. It explains pad_id and expected_revision for overwrite, and notes name uniqueness per project. However, it does not explain tags or content semantics, though content is self-evident. The description adds some value beyond the schema but doesn't fully cover all parameters.

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 clear verb-resource pair: 'Create a pad, or fully overwrite one', and differentiates from siblings by explicitly naming pad_append/pad_edit as alternatives for targeted changes. It also notes the uniqueness constraint per project, adding specificity.

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 explicitly instructs to 'Prefer pad_append/pad_edit for targeted changes', providing clear guidance on when this tool is not the best choice. It implies usage for creation or full overwrite, though it doesn't list explicit exclusions beyond that preference.

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

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

No annotations, so the description carries the full burden. It discloses that the operation registers a directory, defaults to cwd, and is idempotent (returns existing project if path already registered). However, it does not state permissions, side effects beyond registration, or whether name participates in idempotency; still, it offers some transparency.

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 with no filler; the purpose is front-loaded and each sentence adds behavior or default context. Efficient and well-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?

While an output schema exists and the core behavior is described, the description omits any semantics for the name parameter and provides no guidance on required versus optional usage beyond the cwd default. For a registration tool with no annotations, this is incomplete.

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 has no property descriptions (0% coverage), so the description must explain the parameters. It only loosely ties 'directory' and 'defaults to current working directory' to path; the name property is never explained. This is insufficient for 2 parameters.

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 action ('Register a directory as a project') with a clear resource, and adds default-path and idempotency behavior. This distinguishes it from siblings like project_list and 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?

Gives implied usage by noting default to current working directory and idempotent return, but does not explicitly say when to use this over project_list/project_select/project_prune or mention exclusions. The guidance is contextual rather than comparative.

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

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

With no annotations provided, the description carries the full burden. It states the tool lists projects and the selected one, which adequately describes its read-only nature. It does not disclose error behavior or output format, but for a simple list operation this is minimally sufficient.

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 a single, front-loaded sentence with no filler. Every word contributes to conveying the tool's purpose.

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 listing tool, the description covers the essential function. It could mention what the output looks like (e.g., a list of project IDs), but without an output schema, the lack of detail is acceptable for such a simple operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the schema coverage is 100% (an empty schema). The description adds no parameter details because there are none to document, which aligns with the baseline of 4 for a zero-parameter tool.

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 clearly states the tool lists registered projects and identifies the currently selected one. This is a specific verb-resource combination that distinguishes it from siblings like project_add and project_select, which add or change state.

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 purpose implies a read-only query operation, and given the tool has no parameters, it is obvious when to use it for viewing projects. However, it does not explicitly mention when not to use it or suggest alternatives like project_select for changing the selection.

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

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

With no annotations, the description carries full weight. It discloses per-delete verification, self-protection (never prunes own project), environment constraints (lock refusal), and irreversibility (no dry-run). This is comprehensive and covers all critical behaviors.

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 that front-load the purpose, then add constraints and side effects. No redundancy or filler; 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?

Given an output schema exists and no parameters, the description fully covers the tool's behavior, safety, and environmental constraints. An agent receives everything needed to decide when to call it and what to expect.

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, so schema coverage is 100% (no properties). Baseline of 4 applies; description adds no parameter-specific details, which is appropriate since there are none to clarify.

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') and resource ('prune projects'), defines the precise condition (owns no rows anywhere in the store), and contrasts with the caller's own project. Clearly distinguishes from siblings like actor_prune by focusing on project-level cleanup.

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?

Provides explicit exclusions: refuses under HIVE_PROJECT_LOCK=1 and never prunes the caller's own project. Implies usage for cleaning up empty projects, though it does not explicitly name alternative tools for non-empty or actor-specific cleanup.

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

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

With no annotations provided, the description must disclose behavioral traits on its own. It only states the core action ('set project for session') without mentioning side effects, error handling, persistence, or confirmation. It does not indicate whether it validates the project existence, what happens on invalid input, or whether it returns a value. This is a significant gap for a tool with no 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?

The description is a single, front-loaded sentence with no filler. Every word contributes to understanding the tool's purpose. It is appropriately brief and well-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?

For a simple setter with one parameter and no output schema, the description covers the essential purpose. However, it omits practical context such as what happens if the project ID is invalid, whether the selection persists across tool calls, and whether there is a way to query the current selection. These omissions leave some ambiguity for an agent deciding how to use the tool safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It does convey that project_id identifies the project to act on, which is useful. However, it does not explain how to obtain a valid ID (e.g., via project_list) or any format constraints beyond what the schema already provides. The description adds a little context but not enough to fully compensate for the missing schema 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?

The description clearly states a specific action ('Set') on a specific resource ('which project') and clarifies the scope ('later tools act on in this session'). It differentiates itself from sibling project tools like project_list and project_add by framing itself as a session-context setter rather than a data operation.

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 the intended usage: call this before executing project-aware tools. It implicitly signals when to use it, but does not explicitly mention alternatives or exclusions (e.g., 'not for listing projects'). The context is clear enough for an agent to infer the role, but lacks direct comparison to siblings.

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

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

With no annotations provided, the description carries the full burden. It discloses the unarchive capability, the effect on todo_list (excluded by default), that todo_get can still reach it, and the refusal condition for blocking uncompleted todos. This is substantial behavioral context, though it doesn't cover permissions or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no fluff. The action is stated upfront, followed by key behavioral notes and a refusal condition. Every clause earns its place, making it highly concise and readable.

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 tool with three parameters and an output schema, the description covers the essential behaviors: archiving, unarchiving, list exclusion, retrieval by id, and the blocking condition. It doesn't address authentication or other environmental factors, but these are likely covered by the context of the todo system. Given the output schema exists, return values are presumably documented, so the description is sufficiently 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 coverage is 67% (archived and project_id have descriptions, but todo_id does not). The description does not add detail for todo_id beyond implying it identifies the todo. It repeats the archived=false option already in the schema, adding no new semantic value. The missing todo_id description is not compensated.

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 clearly states the action: archive or unarchive a todo, with the archived flag. It also provides behavioral context by noting archived todos are excluded from todo_list and still accessible via todo_get. While it references pad_archive as a mirror, it doesn't explicitly contrast with other todo tools, but the core purpose 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 description implies when to use the tool (to archive/unarchive) and mentions the refusal condition when blocking a non-completed todo, but it doesn't explicitly state when to choose this over alternatives. Since there is no direct sibling for archiving, the guidance is implicit rather than explicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses the core behavior (blocking and cycle rejection) but omits other relevant behaviors such as whether it validates that the todos exist, whether it is idempotent, or how errors are surfaced. The cycle rejection is a useful behavioral note, but more transparency would be expected for a mutation tool with no annotation coverage.

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 a single sentence that front-loads the purpose and includes the cycle-rejection caveat. Every word earns its place; there is no fluff or redundancy.

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?

The tool is relatively simple, but the description omits potential edge cases and behaviors such as what happens when a blocker already exists, whether multiple blockers are allowed, or how errors are returned. While the output schema may cover return values, the description alone does not provide complete context for an agent to call the tool correctly in all scenarios.

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 schema description coverage is only 33% (only project_id has a description). The description implicitly explains the roles of todo_id and blocker_id through the sentence 'todo_id cannot start until blocker_id completes', adding semantic meaning beyond the schema. However, it doesn't explicitly describe the parameters or explain project_id beyond the schema's existing description. Given the low coverage, the description partially compensates but not 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?

The description clearly states the action: add a blocker between two todos, with a specific semantic ('todo_id cannot start until blocker_id completes'). It distinguishes itself from sibling tools like todo_unblock by describing the operation and the cycle rejection, making its purpose 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 guidance is provided on when to use this tool versus alternatives (e.g., todo_unblock). It doesn't mention that it creates a dependency that can be removed, nor does it specify any prerequisites or context for invocation. The usage context is implied only by the name and description, but no explicit when/when-not guidance is given.

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

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

No annotations are provided, so the description bears the full burden of explaining side effects. It only states the basic add action and gives use-case context; it does not disclose whether the comment is appended, whether it overwrites content, what permissions are needed, or any other behavioral implications. This is thin for a mutation 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?

Two short sentences contain no filler. The action is front-loaded, and the usage guidance is the only addition, making every sentence valuable.

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 three-parameter mutation tool, this is adequate: it gives the action and a practical usage scenario, and an output schema exists to cover return values. However, it lacks a clear differentiation from todo_update and omits behavioral or authorization context, so it is not 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 33%: project_id has a rich description, but body and todo_id have none. The description adds partial meaning by indicating body content through handoff examples and by implying todo_id is the target todo, but it does not explicitly define either parameter. It compensates somewhat but not 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?

The description opens with a specific verb and resource: 'Add a comment to a todo.' It clearly conveys the core action, but it does not explicitly distinguish itself from the sibling todo_update tool, even though the comment-vs-update distinction is reasonably inferable.

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 second sentence provides concrete when-to-use context: 'Use for handoffs: changed files, tests run, decisions, remaining risk.' This gives an agent a clear scenario, but no alternatives, exclusions, or 'when not to use' guidance are mentioned.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It clearly states the mutation effect, the reopen path, and that the tool returns todo ids newly unblocked. It does not cover idempotency or permissions, but the core side effects and return behavior are transparent enough for a simple toggle 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?

One tight sentence with no filler. The primary action is front-loaded, and the key qualifier (completed=false) and return value are included immediately. Every part 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?

Given the low parameter complexity, an output schema, and strong schema descriptions, the description is sufficient. It explains the action, the main parameter behavior, and the meaningful return. No critical information needed to invoke the tool 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%, so the schema already documents project_id well. The description adds semantic meaning to completed by explaining that false means reopen, which goes beyond the schema's 'Defaults to true.' todo_id is implicit in the main action, and project_id is fully covered by 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?

The description states a specific verb and resource: 'Mark a todo complete', and adds the reopen behavior when completed=false. This clearly identifies the tool's purpose and distinguishes it from generic todo_update or todo_archive. An agent can tell what this tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: call this when a todo should be marked complete or reopened. However, it does not explicitly say when to prefer todo_complete over siblings like todo_update, nor does it mention exclusions or alternatives. The guidance is adequate but relies on 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?

With no annotations, the description carries the full burden of behavioral disclosure. It does disclose that creation returns a 'slim receipt', explains slug fallback behavior, and notes blocked_by ordering. However, it does not mention permission requirements, project-selection prerequisites, idempotency, or failure conditions. The slug behavior is already thoroughly documented in the schema, so the marginal transparency added beyond structured data is modest.

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 four short sentences, front-loaded with the primary action. Each sentence delivers a distinct piece of information: scope, slug behavior, blocked_by, and return format. There is no filler, and the slug explanation is a condensed version of the lengthy schema text, appropriate for a top-level description.

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-value details aren't needed. The description covers core creation actions, slug, and blocked_by, but omits the requirement for an active project, the meaning of body/tags/priority, and how project_id overrides operate (although the schema covers project_id). For a 7-parameter mutation tool with no annotations, more context on prerequisites and error scenarios would be beneficial, but the current description is not critically incomplete.

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 43%, so the description must compensate for undocumented parameters. It adds clear meaning for blocked_by ('encode ordering') and summarizes slug behavior, but body, tags, priority, and title are not mentioned, and project_id is only implied by 'project-scoped.' Since the schema already describes slug and project_id in detail, the net added value is mostly for blocked_by, which leaves several parameters underexplained.

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 'Create a project-scoped todo' – a specific verb and resource. The 'create' verb clearly distinguishes this from sibling tools like todo_update, todo_complete, and todo_archive, and the 'project-scoped' qualifier adds additional precision. An agent can immediately tell what this tool does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied through the verb 'create' and the todo domain, but the description does not explicitly state when to use this tool versus alternatives such as todo_update or todo_complete. It gives parameter guidance for slug and blocked_by but offers no exclusions or alternative-selection conditions. The tool name and context convey the primary use case, but the description lacks explicit 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?

With no annotations provided, the description carries the full burden. It discloses that this is a read operation ('Read') indicating no side effects. However, it does not mention behavior on missing IDs, error handling, or any authorization requirements. For a simple read tool, this is minimally adequate but missing important edge cases.

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 a single, front-loaded sentence that immediately states the action and scope. It contains no filler and every word adds value. This is an exemplar of concise tool descriptions.

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 must convey what is returned. It does so by listing body, blockers, what it blocks, and optional comments. While it lacks details on error responses or the effect of project_id (though the schema describes that), the core information needed to call the tool correctly is present. Minor gaps prevent a 5.

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% (only project_id has a description). The tool description adds meaning to include_comments by saying 'optionally comments', but does not clarify todo_id beyond its obvious role. Given the low coverage, the description partially compensates but not fully. The parameters are simple and self-explanatory enough that a 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?

The description clearly states the tool reads a single todo in full, specifying exactly what is returned (body, blockers, what it blocks, optionally comments). This distinguishes it from sibling tools like todo_list (which lists todos) and todo_create/update (which modify). The verb 'Read' plus the resource 'one todo' makes the purpose 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 description implies usage: use this when you need a single todo's complete details, as opposed to todo_list for multiple. However, it does not explicitly mention alternatives or state when not to use it. The guidance is inferred from the tool name and description rather than explicitly provided, so it falls at 'implied usage'.

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

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

With no annotations provided, the description carries the burden of disclosing behavior. It does so by stating that archived todos are excluded by default, include_archived=true retrieves them, query matches title/body/slug, and is_blocked=false finds dispatchable work. It does not mention return shape or pagination behavior, but the key behavioral quirks are surfaced.

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 three short sentences with no filler. The first sentence establishes the purpose, and each subsequent sentence adds a distinct behavioral fact that an agent needs. It is front-loaded and 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?

For a list tool with nine optional parameters and no output schema, the description covers the most important filtering behaviors but omits meaning for several parameters and does not describe the returned summary fields or default pagination. The schema's enums and standard parameter names reduce the risk, making this minimally 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%, so the description must compensate for most parameters. It explains query, is_blocked, and include_archived, but leaves tags, limit, offset, status, and priority without any added meaning. The project_id parameter is covered by the schema's own description, but the majority of parameters are underspecified.

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 clearly states the action and resource: 'List todo summaries.' It also adds useful scope by explaining what fields the query matches and the archived exclusion behavior. It does not explicitly distinguish itself from sibling tools like todo_get, though 'summaries' hints at a list-vs-detail distinction.

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 implies when to use the tool: to list todos, find dispatchable work with is_blocked=false, and search by query. It provides no explicit guidance about when to prefer an alternative sibling tool or when not to use it, leaving some routing to the agent's 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Remove' implies a mutation, but it does not clarify side effects (e.g., whether the relationship must exist, if it is idempotent, or what happens to dependent todos). No output or error behavior is mentioned, leaving the agent with minimal guidance on the tool's runtime behavior.

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 a single sentence with zero filler. It is front-loaded with the core operation and is appropriately sized for a straightforward removal tool. No redundant details are present, and the structure is clear and 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?

Although an output schema exists (which we don't see) and might cover return values, the description is minimal for a mutation tool. It lacks context on prerequisites, error cases, or any special conditions. Given the absence of annotations, the description should provide more behavioral context, but it does not. It is adequate only for the simplest of scenarios.

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% (only project_id has a description). The description adds no parameter semantics beyond the parameter names themselves. todo_id and blocker_id are self-explanatory from the tool name, but the description does not explicitly state their roles or any constraints beyond the schema. With low schema coverage, the description should have compensated but did not.

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 'Remove one blocker relationship from a todo' uses a specific verb (remove), a resource (blocker relationship), and an object (todo). It clearly conveys the operation, which is unambiguous even without naming the sibling todo_block. It could have explicitly differentiated from the add-blocker operation, but the purpose is clear and concise.

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 guidance is provided on when to use this tool versus its siblings (e.g., todo_block, todo_update). The context implies it is the inverse of todo_block, but there is no explicit mention of alternatives or conditions for selection. An agent is left to infer usage 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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose a critical behavior ('Omitted fields are preserved') and the output shape ('Returns a slim receipt'), which adds value. However, it does not mention error cases (e.g., non-existent todo_id), whether a project override is required, or any side effects beyond the update. These are notable gaps given the absence of annotation context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences with no filler. The primary action and core behavior are front-loaded, followed by a brief note on the return value. Every word earns its place, making this an example of efficient writing.

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 tool with 8 parameters, low schema coverage, and no annotations, the description is too sparse. It does not explain when to use it, what the expected input fields are beyond the schema, or what 'slim receipt' entails since no output schema is provided. An agent would struggle to correctly construct a call without consulting the schema extensively and inferring usage from sibling names.

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 slug and project_id have descriptions). The description does not compensate: it merely says 'Update todo fields' without explaining any parameter semantics, enums, or relationships. The preservation note is about update behavior, not parameter meaning. The agent gets minimal additional insight about what each parameter does or how they interact.

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') and adds a key behavioral detail ('Omitted fields are preserved'). This makes the tool's purpose clear, but it does not explicitly distinguish it from other modification tools like todo_complete or todo_archive, which also change state. Still, the general 'update' scope is well conveyed.

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 guidance is given on when to use this tool versus alternatives. The description does not mention todo_complete for marking done, todo_archive for archiving, or any conditions for partial updates. An agent must infer from the name alone, which is insufficient for a tool with many sibling operations.

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

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

With no annotations provided, the description fully carries the behavioral burden and does so excellently. It discloses cascading cancellations of hold notices and undelivered finish notices, explicitly calls out what is NOT canceled, and even explains the underlying reasoning. This is far beyond what a typical tool description provides.

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 long, but every sentence adds a distinct behavioral fact or condition: scope, hold notice cancellation, finish notice cancellation, and the deliberate non-cancellation of the per-worker block notice. It is front-loaded with the core action and then layers exceptions, making it dense but structured. Some explanatory clauses could be trimmed 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?

Given the tool's complexity and the absence of annotations, the description is remarkably complete: it covers authorization scoping, side-effect cascades, edge cases about standing watches, and explicit non-effects. An output schema exists, so not detailing return values is acceptable.

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 input schema covers project_id with a description, but wake_id has no schema description and the tool description does not explicitly tie wake_id to the wake-up being canceled. The phrase 'Cancel a pending wake-up' implies wake_id identifies that wake-up, but this is indirect and does not fully compensate for the 50% schema 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?

The description opens with a specific verb and resource: 'Cancel a pending wake-up', and immediately clarifies the ownership scope and lead override. This clearly differentiates wake_cancel from siblings like wake_set and wake_update by focusing on cancellation rather than creation or modification.

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 clearly states when cancellation is permitted ('a pending wake-up you own, or - if you are a running lead - any pending wake-up in this project'), giving strong usage context. It does not explicitly name alternative tools for other operations, but the operation and permission conditions are unmistakable.

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

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

With no annotations, the description carries the disclosure burden. It surfaces the non-obvious untruncated-body behavior and the project scope. It does not spell out error behavior or return shape, but for a simple read the core behavioral traits are 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?

Two sentences, with the core behavior front-loaded and the trade-off against wake_list in the second sentence. 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?

For a low-complexity getter with one required parameter, the agent has enough to select and invoke it correctly: the id, project scoping, and why the untruncated body matters. Omitted response-shape details are not blocking given the tool's simplicity.

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 schema already documents project_id thoroughly; the description adds only that wake_id identifies the wake, which is thin for the one required parameter. At 50% schema coverage, a stronger description of wake_id (e.g., where to obtain it) would help.

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 action and object: 'Read one wake-up by id, in this project, with its UNTRUNCATED body.' It also distinguishes itself from wake_list by naming the truncation difference, so an agent can select it 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?

It explicitly names wake_list as the alternative and gives two concrete trigger conditions: seeing exactly what a wake will say, and confirming a wake_update change. This is direct when-to-use 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains meaningful traits: one-shot wakes leave the pending list the moment they fire, recently_delivered is limited to the last 10, and delivery state includes typed_at, held_at/held_reason, and confirmation. It does not explicitly confirm read-only behavior, but the description strongly implies it.

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 compact and front-loaded with the main purpose. Both sentences carry essential information about behavior and delivery state without extraneous content.

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?

The description is largely complete for a read-only list tool: it names the pending list, the recently_delivered section, its size cap, and the delivery-state fields. Since there is no output schema, it would benefit from a bit more detail on the exact shape of pending wake entries, but an agent has enough to select and call the tool 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 description coverage is 100%, so the baseline is 3. The tool description itself adds no parameter-level meaning, but the schema already fully documents project_id, including the 'only when explicitly asked' rule.

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 starts with a specific verb and resource: 'List pending wake-ups in this project', and further clarifies what it additionally includes ('recently_delivered'). It distinguishes itself from the single-wake sibling tools by describing its list-oriented scope and the special recently_delivered section.

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 clear context for when to use this tool, especially for checking whether a one-shot wake actually fired and whether it was acknowledged. It does not explicitly name alternatives like wake_get or state when not to use this tool, 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 no annotations provided, the description carries the full burden. It discloses the key behavioral trait: the body is typed as a fresh user turn prefixed with '[hive wake #N]', and that it may arrive in a session with none of the current conversation. It also explains the default delivery target. It doesn't mention cancellation or repeat behavior in detail, but the core side effects are clearly 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?

The description is compact and front-loaded with the core mechanism, then adds usage guidance. Every sentence earns its place, though the final sentence about the own lead pane is slightly dense and could be clearer. It is appropriately sized for a tool with this many behavioral nuances.

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 tool's complexity (5 params, no annotations, output schema present), the description covers the essential behavioral contract: what happens, where it delivers by default, how to write the body, and when to override project scope. It doesn't explain repeat_every_seconds or how to cancel, but those are discoverable via sibling tools (wake_cancel) and the output schema. The description is complete enough for correct invocation in most 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 description coverage is only 40% (2 of 5 params have descriptions), so the description must compensate. It explains the semantics of delay_seconds and body ('after delay_seconds the body is typed...'), and clarifies deliver_to's default ('Defaults to delivering to THIS session'). It also gives guidance on project_id. The only param not addressed is repeat_every_seconds, but the overall compensation is strong.

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 ('Schedule a wake-up') and resource (a delayed message typed into a target session's terminal), and distinguishes it from polling. It also names the sibling alternative (wake_when_idle) implicitly by contrast, and the sibling list includes wake_cancel/wake_list/wake_get/wake_update, so the agent can tell this is the creation/scheduling variant.

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 explicitly says 'Use instead of polling' and gives concrete guidance on when to use the default delivery vs. deliver_to, plus a strong directive to write the body self-contained because it may arrive in a session without context. It also warns against using project_id unless the user explicitly asks for another project, which is exactly the kind of when-to-use/when-not-to-use guidance an agent needs.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that delay_seconds is relative to now, that repeat_every_seconds only affects subsequent firings and does not move the next fire time on its own, and that editing is restricted to pending wakes. It also implies return behavior by pointing to wake_get for verification. These are significant behavioral details beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph. It front-loads the core purpose but packs many caveats and type-specific details into one block. Every sentence adds value, but the structure could be improved with bullet points or separate sentences for the idle-wake restriction. It is concise enough, not verbose, but not optimally 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?

Given the tool's complexity (5 params, 1 required, nuanced semantics, and output schema exists), the description covers all essential behavioral and usage aspects: in-place edit, relative timing, interval behavior, pending-only restriction, and type-specific rules. The output schema covers return values, so no further explanation is needed. Nothing critical 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 only 20% (project_id), so the description must explain the other parameters. It clearly explains delay_seconds ('RELATIVE TO NOW... moves the next fire time to now + delay_seconds'), repeat_every_seconds (affects only subsequent firings), and the nature of body (subset of fields). It also states that any subset can be provided, clarifying optionality. This fully compensates for the low schema 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 description opens with a clear, specific verb-object pair: 'Edit a pending wake-up you own, in place, without minting a new id.' This immediately distinguishes it from wake_set (which creates a new id) and wake_cancel (which removes). The purpose is unambiguous and the resource is named.

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 provides explicit conditions for use: 'Only a still-pending wake can be edited' and 'use wake_get to read the result back.' It also clarifies the distinction between delay wakes (from wake_set) and idle wakes (from wake_when_idle), explaining that only body can be edited on idle wakes. This effectively routes the agent to the right tool and behavior.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that one-shots stop watching after firing, standing watches never stop until timeout or wake_cancel, already_satisfied is returned when all agents are idle, delivery holds past max_wait_seconds under dialog/unsubmitted-text conditions, and duplicate standing watches are refused.

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 and every sentence carries information, but the opening sentence is a long run-on that packs the core purpose, timeout exception, delivery hold, and a rules-file reference into one hard-to-parse statement. The two-shape structure that follows is clear, but the front-loading hurts readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two distinct behavioral modes, seven parameters, and an output schema, the description is remarkably complete. It explains lifecycle, timeout handling, delivery behavior, failure/refusal cases, and when to prefer each shape. The only real gap, body semantics, is minor and does not undermine call correctness.

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 high at 86%, and the description still adds meaningful semantics for mode, scope, max_wait_seconds defaults/lifetime, and agents/scope mutual exclusivity. However, the required body parameter is left entirely undocumented in both the schema and the description, preventing a perfect score.

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 identifies a specific verb and resource: wake up when watched agents go idle or when max_wait_seconds passes. It clearly distinguishes the two invocation shapes (one-shot agents vs standing scope) and frames the tool as a reactive subscription, setting it apart from siblings like wake_set or wake_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?

It explicitly advises when to use the standing watch ('Use the standing watch when you are running more than one worker'), explains why a one-shot is insufficient in that case, and recommends 'Use either instead of polling.' It also states refusal conditions: duplicate standing watches and lead targets.

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

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

No annotations are provided, so the description carries the burden. The verb 'Show' implies a read-only operation with no side effects, which is a positive signal. However, it does not disclose any output format or potential edge cases (e.g., what happens if session context is missing). Given the simplicity, a 3 is appropriate—the description adds some context (effective project scope) but could be more explicit about behavior.

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 with zero filler. The primary action and scope are front-loaded, and the usage instruction is compact. Every word contributes to the tool's understanding.

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-only introspection tool, the description covers the essential information: what it shows and when to call it. It does not describe the return format, but since there is no output schema, that is not required. It is complete enough for an agent to invoke it correctly in a new session.

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 are zero parameters, so the baseline is 4 as per the rubric. The description does not need to elaborate on parameters, and the empty schema fully documents their absence.

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 ('Show') and a precise resource ('this session's actor identity and effective project scope'). It clearly distinguishes this tool from siblings like project_list or todo_list by focusing on session-level introspection, so an agent can tell its purpose without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs to 'Call this first in a new session,' giving a clear when-to-use condition. It does not mention alternatives or when-not-to-use, but since it is a session setup call, the guidance is sufficient for basic usage.

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