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 thoroughly explains side effects: clearing awaiting_ack, closing pin rounds, refusal conditions with expect_body_sha256, one-per-(message, role) overwriting, prohibition on self-acknowledgement, and retirement of nudges. This is exceptionally transparent.

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 dense with critical information, structured logically from core action to edge cases. It front-loads the primary purpose and then details nuances. While not minimal, every sentence contributes to correct usage, making it efficient for the complexity involved.

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, the description is remarkably complete. It covers all major behaviors: decision semantics, pin round closure rules, agreement conditions, nudge retirement, and cross-references get_acknowledgements. An agent can call it correctly without additional external knowledge.

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 has zero descriptions (coverage 0%), so the description must compensate. It explains the meaning of decision values, the 4000-character limit on note, the purpose of expect_body_sha256 (digest verification), and implies message_id context. This fully compensates for the schema's lack of documentation.

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 explicitly states the tool records a role's decision on a message, enumerating the four decision values and the optional note. It clearly identifies the resource (message) and the action (acknowledgement), distinguishing it from sibling tools like mark_read or resolve_message by its unique 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 provides rich context on when to use the tool, including conditions for void closing a pin round and the effect on awaiting_ack. It also references get_acknowledgements for checking agreement. However, it does not explicitly state when NOT to use it or compare with alternative tools, though the behavior is so specific that the intended use is unambiguous.

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 — and excels: it reveals the token is shown exactly once, that existing roles/tokens/message history are untouched, that the new role can read the whole channel, and that the new role affects future protected-pin rounds under specific conditions. This is rich behavioral context beyond what any structured fields provide.

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 information-dense but every sentence earns its place: admin constraint, token behavior, capacity/novelty checks, non-destructive guarantee, read scope, and the subtle consent implication. It front-loads ADMIN ONLY before the action, making the most decision-critical fact immediately visible.

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 who may use it, transport, prerequisites, return value (token shown once), side effects, and future side effects, which is complete for an agent deciding when to call it. With an output schema present, return shape doesn't need explanation, and omission of explicit error paths is acceptable given the stated prerequisites.

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 for both parameters. It does: 'channel' is an existing channel and 'role' must be new and a lowercase slug, with the <=12 roles constraint. It doesn't fully specify channel identifier format or exact expected value examples, but it provides meaningful semantics beyond the raw schema for both required 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 (add a role), the target resource (existing channel), and the key distinguishing behavior (returns a bearer token shown exactly once), which clearly separates it from siblings like list_roles and create_channel. It also specifies it is ADMIN ONLY, 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?

The description gives clear context for when to use the tool: it is ADMIN ONLY, uses HTTP transport, requires the channel to have room (<=12 roles), and requires the role to be new. It doesn't explicitly name alternative tools or say 'use X instead', but the conditions and prerequisites are concrete enough to guide correct usage without misleading the agent.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict that; it describes a read-only listing operation. It adds substantial behavioral context: it explains the default role, exclusions, the 'obligation' field for entries that are also action_required, and the behavior of the 'fields' projection. This goes far beyond the annotation and makes the tool's behavior fully transparent.

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 serves a purpose. It front-loads the core purpose, then details exclusions, parameter behaviors, and usage advice. It is structured logically, though it could be slightly tighter without losing information. The verbosity is justified by the tool's complexity and the lack of schema coverage.

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 has 5 parameters, no schema description coverage, and an output schema, the description covers everything an agent needs: what the tool does, what it excludes, how each parameter affects results, and when to use it. It even suggests follow-up actions. It is complete enough for correct invocation and result handling.

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

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

Schema coverage is 0%, so the description must compensate. It explicitly explains 'from_role' (filters by author), 'pin_key' (narrows to one pin's round), and 'fields' (list of names or 'headers' for a smaller response). It implies 'to_role' via 'addressed to a role (defaults to yours)' but does not name it directly. It omits any description of the 'limit' parameter, which is a minor gap given its obvious meaning.

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 begins with a specific verb and resource: 'List proposals (kind='proc') addressed to a role' and clearly states the purpose is to retrieve items needing that role's decision. It differentiates from sibling tools like open_obligations by noting it is analogous but distinct, and explicitly lists exclusions (nudges, opened-for-reading, superseded, etc.) that set it apart from other listing tools.

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 when-to-use guidance: it tells the agent to check both this and open_obligations, explains what is not included (superseded, already voted, etc.), and gives conditional advice on handling entries with missing subjects (use acknowledge with decision='void'). It also explains when to use the 'fields' parameter for large listings, which is a direct usage instruction.

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 thoroughly: it discloses that dry_run is the default and returns a preview, that applying requires repeating with dry_run=false plus expect_count and key/word_message_id, what is refused, and that retired messages remain readable with a 'superseded_backfill' event. Reversibility via undo_backfill is also made explicit.

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 and information-dense, with nearly every sentence adding context. However, the 'fields' sentence is effectively stated twice ('projects the preview rows' and 'Optional fields projects the response'), and the candidate-category layout reads as a long wall of text. Given the 8-parameter complexity, the length is mostly 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?

The description covers the full call lifecycle: candidates, filters, preview content, refusal conditions, application requirements, reversibility, and output projection. Since an output schema exists, return-value details do not need to be restated, but snapshot_at remains unexplained and concepts like would_cascade, not_candidates, and multi_claimed are named without definitions.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for most parameters: dry_run, ids, key, include_by_reference, expect_count, word_message_id, and fields all receive meaningful explanation. However, snapshot_at is present in the schema but never mentioned, leaving one of eight parameters semantically unaddressed.

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 statement: 'replay the supersede rule over rounds settled BEFORE the rule existed.' It also enumerates distinct candidate categories ('key', 'target', 'reference' rows), which lets an agent understand exactly what the tool acts on and how it differs from siblings like undo_backfill.

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 frames the one-off historical backfill use case, explains the dry_run=true preview-then-apply workflow, and names undo_backfill as the reversing operation. It does not explicitly list when-not-to-use alternatives, but the 'BEFORE the rule existed' qualifier and two-phase workflow provide strong contextual 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 full responsibility. It discloses return format, expiry details, security implications (single-use URL, key expiration, revocation, token rotation), permission model, and that the link is only accepted for board GET. This is exceptionally transparent.

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 lengthy but every sentence carries useful information, and it is front-loaded with purpose and return values. It is structured logically, covering purpose, security, permissions, and invalidation, making it efficient despite its length.

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 complete for an agent to call correctly: it explains what the tool does, when to use it, security and permission nuances, how to invalidate links, and provides a parameter constraint. The output schema exists, but the description already covers the return fields, so nothing essential is missing.

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

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

Schema description coverage is 0%, so the description must compensate. It provides the label length limit (at most 80 characters) but gives no detail on the channel parameter beyond the default, leaving the agent to infer that 'channel' refers to the target channel. It adds some value but not enough for full clarity.

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 action ('Issue a READ-ONLY viewing link') on a specific resource (a channel's /board). It clearly differentiates from sibling tools like revoke_board_access by focusing on creation of a viewing link, not revocation.

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 states when to use the tool (to get a viewing link for a human to watch the channel) and provides context on who can call it (admin or role for own channel). It also mentions the alternative for invalidation (revoke_board_access) and clarifies that the link carries no role for mailbox tools.

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 the full behavioral burden and does so well: it discloses the pull-based wake-up model, the one-time-per-build appearance of server.whats_new, the last-transition-author rule for task-list ownership, and the unblocked/resume semantics. These are non-obvious behaviors that materially affect how the agent interprets the response.

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 front-loaded, with the call timing and pull-based warning placed first. It is longer than ideal, but the many list categories and ownership rules are genuinely needed; a more list-like formatting would improve scannability.

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 tool with no annotations and a rich output contract, the description is remarkably complete: it names every returned category, explains how ownership is determined, points to the exact sibling tools for follow-up actions, and covers the version-change behavior. An agent has everything needed to call and interpret 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?

The tool has zero parameters and 100% schema description coverage, so there is no parameter meaning to add. The description instead clarifies what the returned fields mean, which is the relevant semantic burden for a parameterless bootstrap-status 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 opens with a clear directive and then states exactly what the tool returns: 'your role's bootstrap' with counts and categorized task lists. It distinguishes itself from sibling tools by naming read_inbox, open_obligations, awaiting_ack, and set_work_status as the tools for fetching the underlying lists, so an agent can tell what channel_status does and does not provide.

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 explicitly prescribed: 'Call this at the start of every session AND before wrapping up a task'. It also explains the pull-based channel context and routes list-fetching to named sibling tools, plus notes server_build() as the alternative for a full whats_new list, giving the agent clear when-and-with-what 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 burden of behavioral disclosure. It covers idempotency ('Idempotent per resolution'), side effects ('logged to message_history as 'resolution_confirmed''), constraints ('Notes and reasons are at most 4000 characters'), and the rule about who can call it. This is comprehensive and goes 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 front-loaded with the core purpose and immediately provides context. Every sentence adds value: the loop explanation, idempotency, logging, length limit, and restriction. It is appropriately detailed without being verbose or 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?

The description covers the behavioral context, side effects, and usage scenario thoroughly. Since an output schema exists, it need not describe return values. The only gap is the lack of explicit parameter semantics, but that is addressed separately. Overall, the tool is well-contextualized and an agent can call it correctly despite the param gap.

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

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

Schema description coverage is 0%, so the description must explain the parameters, but it does not. It never mentions 'message_id' or its meaning, and only refers to 'notes' indirectly via 'Notes and reasons' without mapping it to the 'note' parameter. The description provides almost no parameter guidance.

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 ('confirm') and resource ('a resolution you verified'), and clearly distinguishes it from the other half of the debt loop ('resolve_message' implied). The phrase 'closing half of the debt loop' immediately sets it apart from its 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 explicitly explains when to use it: when a resolved obligation surfaces in channel_status().resolved_for_you of the participant who did NOT resolve it, and contrasts it with the alternative of reopening. It also states the restriction that the resolver cannot confirm their own resolution, which prevents misuse.

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 key behaviors: ADMIN-only access, HTTP transport, one-time token display (server stores hashes), message routing rules, consent requirements for protected pins, and naming constraints. This is exceptionally transparent 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?

The description is a single, well-structured paragraph that front-loads the critical 'ADMIN ONLY' flag and then delivers dense, useful information without redundancy. Every sentence adds value—token lifecycle, message routing, consent, and naming rules—with 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?

Given the tool has an output schema (which presumably describes the returned tokens), the description covers all necessary operational aspects: prerequisites, token handling, routing, consent, and naming. It is complete for an agent to call it correctly and understand the consequences.

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

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

Schema coverage is 0%, so the description must explain parameters. It does so thoroughly: names and roles must be lowercase slugs with specific character constraints and max 64 chars, and roles must be between 2 and 12. This adds significant meaning beyond the bare 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 clearly states the tool's purpose: creating a channel (an isolated mailbox for 2..12 named roles). It distinguishes itself from siblings like list_channels, delete_channel, and add_role by focusing on creation. The verb 'create' plus the resource 'channel' is specific and 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 clearly states 'ADMIN ONLY' as a prerequisite and implies this is the creation tool, not for listing or deleting. It also provides critical usage context: tokens are shown only once, and protected pins require voter consent. However, it does not explicitly name alternative tools or state conditions like 'use this when you need to establish a new mailbox.'

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 supplied, the description carries the full burden and does so well: it discloses the auth requirement, the token revocation, the visibility change in list_channels, the fact that the DB file survives on disk for audit, and the irreversible name non-reuse rule. These are exactly the side effects an agent must know before invoking a destructive operation.

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

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

Three tight sentences, front-loaded with the admin precondition, then consequences, then the disk-cleanup caveat. Every clause carries information; nothing is redundant.

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

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

An output schema exists, so return-value explanation is unnecessary. Given a one-param destructive tool with no annotations, the description covers prerequisites, side effects, persistence, and irreversibility — everything needed to call it correctly and 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?

There is one parameter ('name') with 0% schema description coverage, so the schema offers nothing. The description implies the parameter identifies the channel and adds a meaningful property ('the name cannot be reused'), but never explicitly defines what the 'name' argument is or its format, leaving a small gap for a single required param.

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 ('deactivate a channel') and immediately enumerates the concrete effects (revokes tokens, hides from list_channels), which is far more precise than the tool name alone. It is clearly distinguishable from siblings like create_channel, list_channels, or rotate_token.

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

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

Gives a hard precondition — 'ADMIN ONLY (HTTP transport)' — and briefly notes the manual file-removal alternative if data must truly be purged. It does not, however, contrast this tool with sibling operations such as rotate_token or list_channels, so the when-to-use among alternatives is only partially covered.

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 soft-delete semantics, tombstone visibility, preservation in get_thread, retention of acks and lifecycle events, and the full set of refusal conditions. This is far beyond a generic 'delete' statement.

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 sentence earns its place: primary behavior, visibility consequences, chain preservation, history retention, and the nuanced refusal cases with alternatives. It is front-loaded with the core purpose before enumerating edge cases.

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-looking operation with many edge cases, the description covers the important behavioral constraints and gives actionable alternatives. An output schema exists, so return-value documentation is not needed. The tool is complex, and the description addresses that complexity well.

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

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

Schema coverage is 0%, but the only parameter is message_id, an integer. The description repeatedly references messages and their IDs, making the parameter's role clear even without an explicit parameter description. It does not add type/format detail, but the context is sufficient for this single obvious parameter.

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

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

The description opens with a specific verb and resource: 'Soft-delete a message you sent or received,' then defines the outcome precisely as a tombstone. It distinguishes this operation from ordinary deletion and from sibling tools like resolve_message or reopen_message by explaining what delete_message does and does not do.

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 conditions for use and explicitly lists refusal cases with alternatives: proposals must be authored, votes should be used instead, open action_required messages must be resolved first, and resolved-but-unconfirmed messages require confirm_resolution or reopen first. This gives an agent clear routing guidance relative to sibling tools.

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

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

The description goes well beyond the readOnlyHint annotation, detailing how votes from non-voters are reported, how quenched_by_revision and declared_dead_by are handled, and how the fields parameter projects the response. It clarifies edge cases and response semantics, which is exactly what an agent needs to interpret results correctly.

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 lengthy but information-dense; every sentence contributes value, and it is front-loaded with the core purpose. It could be better structured with bullets or separators, but it is not verbose or redundant. The level of detail is justified given 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?

Given the output schema exists, the description does not need to enumerate return fields, but it explains the semantic meaning of the response (missing, needed, non-voters, etc.) and the projection behavior. It covers all essential aspects for correct invocation and interpretation, making it fully complete.

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

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

With 0% schema description coverage, the description fully compensates by explaining the 'fields' parameter in detail: it can be a list of field names or 'headers' for the usual set, and omitting it returns the full record. The message_id parameter is implied by the context. The description adds substantial meaning 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 clearly states the tool's function: returning the consent state of a message, including acknowledgements and missing votes. It specifies the exact resource (message) and the action (get acknowledgements) with enough detail to distinguish it from generic getters. It also explains the 'needed' count and the distinction between voters and non-voters, which adds 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 implies when to use it: when you need to know missing votes, which is what the collected votes alone cannot tell you. It explains the purpose and the fields projection for large listings. However, it does not explicitly name alternative tools or state when not to use it, though the context strongly suggests it's the right tool for consent-state queries.

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

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

Annotations declare readOnlyHint=true, and the description does not contradict that. The description adds useful behavioral context by detailing the template's contents and the exact subsequent steps (send_message and pin_set) that should follow. This goes beyond the read-only hint and helps the agent understand the tool's purpose in the broader workflow, though it doesn't describe any additional side effects or 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, dense sentence that packs a lot of information: what the template contains, how to use it, and the exact next steps. It front-loads the purpose and provides necessary workflow details without excessive verbosity. While it could be split into clearer sentences, it remains efficient and scannable.

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

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

With no parameters and an output schema present, the description doesn't need to explain return values. It fully covers what the template is, what it includes, and how to use it in the follow-up actions. The description leaves no gaps for an agent to call this tool correctly; it even specifies the exact message and pin parameters to use later.

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 schema description coverage is 100% (trivially). The baseline for 0 params is 4, and the description doesn't need to add parameter information. It correctly focuses on the output and usage rather than parameters, which 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 provides a starter team-charter template for a new channel, including its content (mission/goals skeleton, ten ground rules). This is a specific verb+resource ('get template') that distinguishes it from siblings like send_message or pin_set, which are about sending and pinning, not generating templates.

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 explains the intended workflow: after retrieving the template, replace placeholders, propose it via send_message, and pin it with pin_set. This gives clear context on how and when to use the tool. It doesn't explicitly state when not to use it, but the absence of any similar template tool makes exclusions unnecessary. The workflow guidance is explicit and practical.

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

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

The readOnlyHint annotation already declares the tool safe; the description adds beyond that: it states that any channel member can verify an upload, and that text is returned only when with_body=true. This provides useful permission and optional-body behavior, though it does not mention rate limits or degenerate 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 two sentences, with the primary action and results front-loaded in the first sentence. The second sentence adds the access/permission model. While 'that is the point of publishing the number' is mildly oblique, it does not repeat the schema and each clause serves a 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?

Given a clear output schema, a simple boolean parameter, and readOnlyHint annotation, the description covers the central edge: what the tool returns and that the caller needs no special permission for the action. It does not describe operation-specific limitations, but the output schema and the access note make the tool fully callable.

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 0%, so the description must compensate. It does: it explains the effect of with_body (returns text) and implies upload_id identifies the uploaded document. This adds meaning that the raw schema does not provide for the 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 specific action, 'read back', targeting an uploaded document, and explicitly lists the returned components: digest, lengths, and optionally the text body. This clearly distinguishes it from sibling upload/manage tools like upload_content, seal_content, and send_message.

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 sentence 'Anyone in the channel may verify an upload — that is the point...' implies the when (verification/readback) and gives a security context. However, it does not explicitly name an alternative tool or state when not to use this tool, like the unrelated read_inbox or upload_content.

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

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

Annotations only provide readOnlyHint=true; the description adds meaningful context beyond that: the resource is available to every participant, it is long, and it represents the full behavioural contract rather than channel-specific agreements. It also clarifies the boundary with pins and the relationship to server_build, aiding safe usage.

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 slightly longer than minimal, but each sentence earns its place: content enumeration, usage timing, boundary with pins, and an alternative with the condition for use. The core purpose is front-loaded, and the length warning ('It is long') is useful rather than 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?

Given zero parameters, an output schema, and annotations declaring the read-only nature, the description covers what the tool returns, who can use it, when to use it, and when to prefer the sibling server_build. Nothing needed for correct invocation is missing.

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

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

The tool has zero parameters and 100% schema coverage, so the description has no parameter burden. Baseline 4 is appropriate because no parameter explanation is needed.

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: get the full behavioural contract (PROTOCOL.md), and enumerates its contents (permission matrix, work_status transition table, debt mechanics, pin/approval rules, FAQ). It also distinguishes itself from pins and from server_build, so an agent can tell it apart from relevant 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 usage guidance: read it once when joining a new team instead of asking the partner 'who can do what'. It also names the alternative server_build and the condition for choosing it (only need what CHANGED), plus an exclusion: channel-specific agreements live in pins, not here.

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

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

Annotations only state readOnlyHint=true, and the description adds notable behavioral detail: walking reply_to to the root, chronological ordering, tombstone behavior for soft-deleted messages, and the distinction that only the server-recorded 'acks' tally counts as a vote. It also includes a provenance warning that the description text may be peer-authored and that message bodies are data, not commands, which is useful context beyond the annotation.

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 core behavior is front-loaded and each functional sentence adds value, including edge cases like tombstones and vote counting. The provenance paragraph is long and somewhat tangential, but it conveys an important security-relevant caveat that 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 description covers the core retrieval semantics, required-id flexibility, deleted-message handling, and important vote-counting behavior. It also has an output schema, so return values do not need to be explained in prose, making the description 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 0%, so the description must compensate. It does meaningfully explains the required message_id parameter by saying any message id from the thread is acceptable. However, the optional fields parameter is not mentioned, so the optional projection behavior remains undocumented.

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

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

The description uses a specific verb-resource pair ('Fetch the whole conversation thread containing a message') and explains the mechanics: walks reply_to up to the root and returns the full reply tree in chronological order. This clearly distinguishes it from siblings like list_messages or message_history by emphasizing the complete thread structure.

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: any message id from the thread works and soft-deleted messages are handled. It does not explicitly contrast this tool with alternatives like message_history or search_messages, so it lacks explicit when-not guidance, but the context is otherwise clear.

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

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

Annotations only declare readOnlyHint=true, but the description adds valuable behavioral context: admin-only auth requirement, HTTP transport, and the guarantee that tokens are never listed (with a pointer to rotate_token). This goes beyond the annotation and helps the agent understand constraints and fallback 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 two sentences with no fluff. The first sentence front-loads the key purpose and auth constraint; the second adds a critical caveat about tokens. 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?

Given the tool's simplicity (0 params, output schema present), the description covers the essential operational details: admin-only access, HTTP transport, and token behavior. The output schema handles return values, so no further explanation is needed. A slight gap is that it doesn't clarify what 'active' means, but this is minor given the overall context.

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 has zero parameters, so there is nothing for the description to add. Baseline for 0 params is 4, and the description appropriately implies no parameters are needed without adding unnecessary detail.

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: 'list active channels with their roles', identifying the exact verb (list), resource (channels), and scope (active, with roles). It distinguishes from siblings by explicitly noting that tokens are never listed and pointing to rotate_token for that 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 provides strong context: it is ADMIN ONLY and for listing channels, making the intended use case clear. It also gives an explicit exclusion for tokens ('Tokens are never listed — rotate_token issues a fresh one'), which helps route the agent away from an alternative. However, it does not explicitly compare against other listing tools like list_messages.

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

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

Annotations only declare readOnlyHint=true. The description adds real behavioral context beyond that: results return newest first, pin_key matches only structurally linked proposals (not text mentions), and the fields projection omits bodies. No contradiction with annotations. The safety profile is covered by the readOnly annotation, so the description's added sorting/linking semantics justify a strong score.

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 but front-loads the core purpose before detailing filter semantics. Every sentence earns its place; the pin_key and fields explanations, while lengthy, clarify genuinely subtle behavior. It could be broken into bullet points for scannability, but nothing is wasted.

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 12-parameter tool with 0% schema coverage, the description covers the highest-risk semantics (pin_key linking, fields projection, substring vs exact match) but leaves limit, since, to_role, from_role, and unread_only undocumented in both schema and description. The presence of an output schema covers return format. Given the tool's complexity, the gaps on five parameters prevent a higher score.

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

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

Schema coverage is 0% with 12 parameters, so the description carries the full burden. It explains the nuanced semantics of the tricky params well: topic (substring on topic), text (substring across topic OR body), status (open/resolved), kind/work_status (exact match), pin_key (structural link), and fields (projection list or 'headers'). However, it omits five parameters entirely — limit, since, to_role, from_role, and unread_only — leaving their meaning to the bare schema 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 opens with a specific verb+resource: 'Search the full message history with optional filters.' It clearly states scope (full history), the operation (search), and what the filters do. It also distinguishes pin_key from text matching, which helps separate this tool's unique behavior. The 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?

Provides actionable usage context: when to use the 'fields' projection ('Use it when a listing over a long history would otherwise be too large'), and clarifies the pin_key vs text= distinction. However, it does not explicitly route the agent away from sibling tools like search_messages, message_history, or read_inbox, leaving some selection inference to the agent.

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

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

Annotations only provide readOnlyHint, and the description adds meaningful behavioral context beyond that: it explains the two possible 'source' values, which is authoritative, and the under-reporting caveat in stdio mode. This gives the agent a realistic expectation of reliability.

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 purpose, then adds only the necessary caveat about source behavior. Every sentence earns its place without wasted words.

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

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

For a zero-parameter read-only tool with an output schema, the description covers the essential behavior, the two runtime modes, and the key limitation. Nothing critical is missing for an agent to invoke and interpret 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?

There are zero parameters, so the schema already leaves nothing ambiguous. The description still clarifies what the tool returns, but no parameter documentation is needed.

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 answers a clear user question ('Who is in this channel') and states the exact return shape ({roles, you, source}). It distinguishes list_roles from siblings like list_channels and add_role by targeting channel membership specifically.

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 explains when the data is authoritative (hosted mode with channel registry) versus inferred (stdio mode) and warns about under-reporting. However, it does not explicitly say when to choose list_roles over alternatives or 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, this description carries the burden well: it discloses a permission-style constraint (refusal for other roles) and a non-obvious side effect (the unread counter decrement) that an agent could not infer otherwise. It does not cover idempotency or partial-failure behavior when a batch contains mixed-role messages.

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

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

Three short sentences, each earning its place: purpose, constraint, and differentiating side effect. The unread-counter fact is front-loadable but stays tight and is not buried.

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

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

For a two-parameter mutation with an output schema present, the description covers purpose, access constraint, and the key side effect, so nothing essential is missing. Minor gaps remain around behavior with no arguments and batch error semantics.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains that message_id targets a single message while message_ids targets several, mapping the two parameters to their distinct use cases. It does not explicitly state that supplying both or neither is invalid, leaving some ambiguity.

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 (mark as read) and resource (one message via message_id or several via message_ids) with an explicit scope restriction ('addressed to you'). It also names the sibling read_inbox and explains how this tool differs from it, so the agent can distinguish the two without opening a schema.

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

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

Gives clear selection context: use this when you need messages actually marked read, since it is 'the ONLY thing that decrements the unread counter — read_inbox does not.' It also states the exclusion (refuses messages addressed to a different role). It stops short of spelling out when read_inbox is the better choice, but the routing signal is 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?

Annotations declare readOnlyHint=true, and the description adds meaningful behavioral context: who, when, the note/reason, ordering (oldest first), and the special rule that a work_status passed to send_message is recorded as a sender transition. This goes beyond the schema without contradicting the annotation.

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 zero filler, front-loaded with the core concept and a valuable non-obvious detail about send_message. 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?

With one required integer parameter, a readOnlyHint annotation, and an output schema present, the description covers event types, ordering, actors, and a special edge case. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 0%, but the description supplies the referent — 'for a message' — making the single integer message_id unambiguous. It doesn't spell out format or validity, but for a single required parameter the added context is sufficient.

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 verb and resource ('Audit trail of lifecycle events for a message') and enumerates specific event types (resolve/reopen/work_status transitions, body revisions, supersedes). This differentiates it from siblings like get_thread or pin_history without needing to inspect their schemas.

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

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

The description implies when to use it (when needing the lifecycle audit for a message) and provides clear context, but it does not explicitly name alternatives or state when-not-to-use conditions. Sibling tools like pin_history serve related but distinct purposes, yet no explicit routing is provided.

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 only readOnlyHint=true in annotations, the description adds substantial behavioral depth: the distinction between age_days and idle_days, the fact that nothing is auto-closed, the default role default, and the fields projection behavior. This goes well beyond what annotations provide.

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 purpose, followed by field semantics and usage guidance. The idle_days explanation is slightly discursive but serves an educational purpose; overall it earns its length without being bloated.

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 output schema exists and the readOnlyHint annotation is present, the description covers all operational aspects an agent needs: what is listed, what fields are returned, how projection works, the default role behavior, and when to use the tool. 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 0%, so the description must carry the parameter semantics. It thoroughly explains the 'fields' parameter, including 'headers' and omit behavior, and explains that to_role defaults to the caller's role. 'limit' is left to the schema's integer/default, which is acceptable since it's straightforward.

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 ('List') and defines the resource precisely: action_required messages with status='open' addressed to a role, defaulting to the caller's role. It also clarifies these are obligations that need resolve_message, which distinguishes it from general message listing or search tools.

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: use it when a listing over long history would be too large to return, and project fields for 'which messages' questions rather than pulling full bodies. It doesn't explicitly name sibling alternatives like list_messages or search_messages, but the intended boundary is mostly inferable.

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

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

Annotations already indicate readOnlyHint=true, and the description adds substantial behavioral context: it explains the exact hashing algorithm (SHA-256 over raw UTF-8 bytes with no normalization), the meaning of length fields, and that the server does not verify anything—these are valuable beyond the annotation. No contradiction with annotations.

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

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

The description is detailed and well-structured, front-loading the purpose and then explaining response fields and hashing semantics. While long, every sentence adds meaningful information without redundancy, earning a high score for conciseness relative to the 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?

Given the tool's simplicity (single param) and the presence of an output schema, the description adequately explains the return fields (body_sha256, body_length_bytes, body_length_chars) and the null case. It does not explicitly describe the response structure but covers the essential behavior, making it complete enough for an agent to call 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 has one required parameter 'key' with no description and 0% coverage from the description. The description mentions 'by key' but does not clarify key format, constraints, or examples. Since schema coverage is low, the description should compensate but does not, leaving the parameter semantics under-specified.

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

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

States a specific verb (get) and resource (pinned entry by key), and clearly distinguishes from siblings like pin_list and pin_history by specifying it retrieves the current version for a single key. The null behavior is explicitly mentioned, which adds clarity.

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 for fetching a single pinned entry by key, but does not explicitly mention when to use this versus alternatives like pin_list or pin_history. No conditions or exclusions are provided, leaving the agent to infer the appropriate 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?

Beyond the readOnlyHint annotation, the description discloses ordering behavior (newest first), the audit content (who changed it and when), and the projection semantics of the `fields` parameter (full record by default, 'headers' for the usual listing set, enumerated field names). It also explains the size rationale and recommends fetching individual records afterward, adding meaningful behavioral 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?

The description is dense but well-structured: purpose and ordering come first, then parameter behavior, then usage rationale. Every sentence carries distinct information, and the longer middle sentence is justified by the need to enumerate valid field values and explain the 'headers' shortcut.

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 tool with two parameters, an output schema, and no nested objects, the description covers purpose, ordering, projection semantics, and size-driven usage guidance. An agent has enough information to decide when to call it and how to set `fields`; return-value details are appropriately left to the 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?

The `fields` parameter is thoroughly described: allowed values are enumerated, the special 'headers' value is defined, and the default behavior when omitted is stated. The `key` parameter is only implicitly explained as the pinned entry's key, but that is sufficiently clear given the tool name and required 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 purpose: returning the full version history of a pinned entry by key, newest first, framed as an audit of who changed it and when. This clearly distinguishes it from siblings like pin_get or pin_list by focusing on the historical record rather than current state or a simple 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?

The description gives explicit guidance for the `fields` parameter: use it when a long history listing would otherwise be too large, since bodies dominate the response size, and fetch wanted bodies individually afterward. It does not explicitly contrast against sibling tools like pin_get or pin_list, but the usage context for the optional projection is clear.

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

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

The description goes well beyond the readOnlyHint annotation. It discloses that the tool returns no bodies, that every pin response carries body_sha256 and length fields, and it explains the exact hashing semantics (raw UTF-8 bytes, no normalisation) and the ambiguity rationale for two length fields. It also clarifies that the server publishes these values but does not verify them, which is important behavioral context for an agent deciding whether to trust the values.

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 purpose and the no-bodies caveat, then expands into hash/length semantics. The first two sentences are tight and high-value. The later sentences about hashing and length are somewhat verbose but earn their place because they explain non-obvious behavior that an agent needs to interpret the response correctly.

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 parameterless list tool with an output schema and readOnlyHint annotation, the description is complete. It covers what the tool returns, what it does not return, how to get bodies, and how to interpret the hash and length fields. The only minor gap is that it doesn't mention pagination or ordering, but the description explicitly frames this as a cheap one-call overview, so that omission is not material.

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

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

The tool has zero parameters, so the schema provides no parameter semantics to clarify. The description compensates by explaining what the response contains and how to interpret the hash/length fields, which is the closest analogue to parameter semantics for a parameterless tool. A 4 is appropriate because there are no parameters to document, and the description adds meaningful context about the returned 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 states a specific verb ('List') and resource ('all pinned entries') and enumerates the exact fields returned (key, title, version, updated_by, updated_at, approved_by). It also explicitly distinguishes itself from pin_get by noting that bodies are excluded, so an agent can tell this tool apart from its sibling 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?

The description explicitly says when to use this tool: for a cheap overview and to verify a local copy of every document in one call. It also names the alternative, pin_get(key), for fetching a body. This is clear usage guidance with an explicit exclusion and alternative.

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

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

Very detailed disclosure: every write appends a version, protected keys require approval with a complex validation process, dry_run behavior is described, return values are specified, and it transparently notes that the server does NOT verify the hash or length—it only publishes them for the team to check. No annotations are provided, so the description fully carries the burden, and it does so richly.

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 but is front-loaded with the core purpose in the first sentence. It uses structured lists and semicolons to organize complex approval conditions and hashing details. While long, every sentence contributes essential information; the length is justified by 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?

Given the tool's complexity (7 parameters, approval logic, hashing, dry_run), the description covers all critical aspects: how to use it, return values, edge cases, and the team's verification responsibility. The only minor gap is 'body_ref', but it's not essential to the core operation. An agent has enough information to call the tool correctly without further clarification.

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 significant meaning to several parameters: it explains the role of 'approved_by' (proposal id), 'dry_run' (runs checks without writing), and clarifies constraints on 'title' and 'version'. However, 'body_ref' is not explained at all, and the schema has zero description coverage, so the description compensates for most but not all parameters. It adds value beyond the schema but leaves one parameter ambiguous.

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

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

States a specific verb and resource ('Create or update a channel-level pinned entry by stable key'), and implies the distinction from siblings like pin_get, pin_list, and pin_history by referencing versioning and history. An agent can clearly tell this is the write operation for pins.

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 guidance on when to use the tool, including the approval requirement for protected keys, the dry_run option for testing, and the condition that other keys are written freely. It does not explicitly name alternatives for reading, but the context (versioning, history) makes it clear that pin_get/pin_list/pin_history are for retrieval, so usage is well implied.

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

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

With no annotations, the description carries the full burden and does so richly: it never marks messages read, it DOES record delivery via opened_at (explaining the opened/unopened_unmarked counter split), only mark_read decrements unread, and proposals include an acks tally. The provenance warning about peer-authored content and unverified approval claims adds critical safety 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?

Front-loads the core behavior (unread default, no mark-read) before the mechanics, which is good structure. However, it is lengthy and restates the mark-read distinction multiple times, so a sentence or two could be trimmed.

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 explanation isn't required. Combined with thorough behavioral and routing detail, the agent has what it needs to invoke correctly; the only shortfall is the undocumented 'fields' parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies 'limit' (newest limit messages, chronological) and 'unread_only' (default behavior), but the 'fields' parameter is never explained, leaving a real gap across 3 undocumented 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 verb and resource (read inbox) plus the crucial scope nuance that it returns unread messages by default and does not mark them read. It also distinguishes itself from siblings like mark_read, list_messages, and open_obligations, so an agent can route away from it correctly.

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

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

Explicit routing guidance: when unread may exceed the limit, use list_messages(unread_only=true) to page the older part, and open debts are visible via open_obligations. It states when-not/alternatives rather than leaving them to inference.

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

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

Annotations provide readOnlyHint=true, and the description adds meaningful behavioral context beyond that: it discloses that tasks with resolved/deleted blockers DO appear, that unblocking is surfaced but never automatic, and that each item carries age_days and idle_days. It does not contradict the read-only annotation. It could add more about pagination or exact output shape, but the output schema exists and the behavioral notes are valuable.

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 that front-loads the core purpose and then adds the key distinction and edge-case behavior. It is somewhat long but every sentence earns its place: the open_obligations contrast, the blocker edge case, and the age_days/idle_days note are all useful. It could be slightly more scannable with a break, but it is not bloated.

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 has an output schema, the description need not explain return values. It covers the core question, the distinction from the sibling, the edge case of resolved blockers, and the action to take (set_work_status). The only gap is parameter semantics for limit/fields, but with 0 required parameters and an output schema, the description is largely complete for an agent to select and invoke 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 0%, so the description carries the burden for parameter semantics. However, the description does not explain the 'limit' or 'fields' parameters at all. The schema itself provides titles and defaults, but no descriptions. The description adds no parameter-level meaning, so a baseline 3 is appropriate given the schema has some structure but the description does not compensate for the 0% 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 states a specific verb and resource: 'ready_work' returns open obligations addressed to you that are not behind a live blocker, oldest first. It clearly distinguishes itself from the sibling open_obligations by contrasting 'how much do you owe' with 'what do you pick up'. This is a clear, specific purpose that an agent can act on.

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 explains when to use this tool versus open_obligations: use ready_work at the start of a session to decide what to pick up, while open_obligations answers the total amount owed including blocked work. It also explains the edge case of resolved/deleted blockers and directs the agent to set_work_status to resume such tasks. This is explicit when/when-not guidance with named 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?

With no annotations, the description carries the full burden — and covers mutation effects, side effects (records who/why), idempotency (no-op for open message), and a constraint (4000 character limit). This exceeds the minimum viable 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?

Four dense sentences, front-loaded with the core action and followed by the most decision-relevant behavioral details. 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 two-parameter mutation tool with an output schema, this description covers the state transition, permission nuance, side effects, idempotency, and a length constraint. Nothing an agent needs 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 description coverage is 0%, so the description must compensate. It adds meaning about the reason parameter's purpose (who reopened and why) and its 4000-character constraint, but message_id semantics are left entirely to the schema's name and type.

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 precise verb and resource: 'reopen a resolved action_required message' and adds scoping details ('Either party may reopen, not just the author') that distinguish it from its resolution siblings. The intent is unambiguous and clearly not confused with resolve_message or confirm_resume.

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 says when the tool should be used — when a resolved message needs to be reopened, especially when the executor finds their fix incomplete. It does not explicitly name an alternative tool, but the guidance is explicit enough that an agent can decide 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?

With no annotations, the description carries full behavioral burden and does so thoroughly. It discloses side effects (recording who/when/note), that resolving an already-resolved message is a no-op, that the response lists 'unblocked' tasks, that surfacing is symmetric until the other party confirms or reopens, and that notes are capped at 4000 characters.

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 necessary nuance about role etiquette, symmetric surfacing, no-op behavior, unblocked-task handling, and character limits. Core purpose is front-loaded in the first sentence, and the rest builds logically from mechanism to etiquette to explicit prohibitions.

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 parameters, meaningful side effects, and role-based etiquette, this description is complete. It explains the response's 'unblocked' list, behavior on repeated calls, legitimate and illegitimate uses, and cross-tool routing to reopen_message and confirm_resolution; the existence of an output schema covers the need to document exact return fields.

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

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

Schema description coverage is 0%, so the description must compensate. It adds real meaning for resolution_note: optional, capped at 4000 characters, and carries substantive semantics like 'cancelled, not needed' or naming what was done. message_id is only implied by context and the schema title, not explicitly explained, which is the main 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: 'Mark an action_required message as resolved.' It clearly distinguishes itself from siblings by naming reopen_message and confirm_resolution as the alternatives for unsatisfied or satisfied verification, so an agent can select this tool over its 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 for both roles: the addressee resolves with a note naming what was done, while the author verifies and uses reopen_message if unsatisfied or confirm_resolution if satisfied. It also states what is NOT legitimate — resolving a debt the other side owes as if the work were done — and describes a legitimate self-cancellation case.

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 that previous votes are 'QUENCHED, not deleted,' flagged 'stale,' stop counting toward 'agreed,' and cause the proposal to reappear in awaiting_ack. It also exposes auditability via old/new sha256, permission constraints, the pin-approval restriction, and the fact that recipients/kind/pin_key are fixed at send time.

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 sentence contributes a distinct, operationally relevant fact. It front-loads the core action and then layers on state effects, audit, permission, and immutability constraints. There is no repetition or 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 mutation tool with no annotations and five undocumented parameters, this description is unusually complete: it covers state changes, permissions, timing restrictions, auditability, and update scope. The only notable omission is body_ref semantics, which keeps it from being fully complete. An output schema exists, so return-value documentation is already handled elsewhere.

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 clarify body as the re-issued text, note's max length, and that topic 'may be updated along the way.' However, body_ref is never explained, and the relationship between body and body_ref is ambiguous. With five parameters and no schema descriptions, this partial coverage leaves a real gap.

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

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

The description opens with a specific verb and resource: 'Re-issue the BODY of a proposal you sent, on the same message id.' It also explicitly frames this as 'the way to publish edition 2 of a draft instead of sending a new message,' which distinguishes it from sibling tools like send_message. An agent can immediately understand the tool's unique function without inspecting other schemas.

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

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

The description states when to use this tool ('the way to publish edition 2 of a draft instead of sending a new message') and when not to: 'Only the author may re-issue, and not after the proposal has approved a pin version.' It also clarifies that a different audience or pin means 'a different proposal,' implying a new message should be sent instead. This gives both positive and negative 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 burden and delivers: required authority (ADMIN ONLY), transport constraint (HTTP transport), immediate and irreversible-looking effect (cookies stop working immediately), and explicit boundaries (role tokens and mailbox untouched). This is rich behavioral context an agent could not infer from the schema.

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

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

Front-loads the most critical constraint (ADMIN ONLY) and uses tightly packed clauses with zero filler; every sentence (scope, effect, boundary, next step) 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 destructive admin action, the description covers authority, mechanism, effect, and untouched resources, and an output schema already exists so return values need no explanation. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 0% for the single 'channel' parameter, so the description technically owes compensation, but it never clarifies whether the value is an ID, name, or slug. The parameter is largely self-evident by name, keeping this at a minimal-viable baseline.

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

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

States a specific verb and resource with precise scope: 'revoke EVERY read-only viewing key of a channel'. It also implicitly distinguishes itself from siblings by noting that role tokens (rotate_token) and the mailbox are untouched.

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

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

Gives a clear motivating scenario ('the answer to a lost or shared phone') and points to the natural follow-up tool ('issue a fresh link with board_link'). It does not explicitly state when NOT to use it or name the alternative revocation tool (rotate_token), so it stops short of full routing 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 burden and does well: it discloses the ADMIN ONLY restriction, that it works only over HTTP transport, that the operation revokes all tokens of the pair, and that the old token stops working immediately (destructive, non-reversible). It does not state permission-failure behavior or rate limits, but the core behavioral profile is 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?

Three short sentences, zero filler, with the admin/transport constraints and the trigger condition front-loaded before the destructive effect.

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

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

An output schema exists, so return values need not be described, and the admin/transport caveats plus the revocation semantics cover what an agent needs. A note on auth requirements or whether the new token appears in the response would close the remaining gap.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It explains that channel and role jointly identify the token set to revoke and reissue, which adds real meaning, but gives no valid values, case rules, or what happens if the pair has no existing token.

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: revoke all tokens of one (channel, role) pair and issue a fresh token. The scope (one channel/role pair, all its tokens) makes it clearly distinct from create_channel, delete_channel, or revoke_board_access.

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

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

Explicitly names the trigger condition ('Use when a token leaked or was lost'), which is concrete guidance. It does not name an alternative tool or state when not to use it, but rotation has no direct sibling equivalent, so the omission is minor.

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

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

With no annotations, the description carries the full burden and largely meets it: it discloses the irreversible constraint ('cannot be appended to'), the reason (the number is published, so bytes must stop moving), and the hashing rule (sha256 over raw UTF-8, no normalisation) for verifying the returned digest. It omits idempotency (what happens if sealed twice) and any auth requirements.

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 action and its effect, then the constraint and verification rule. Slightly dense and repetitive ('same rule as everywhere here', 'exactly as stored') but nearly every clause carries information.

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

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

An output schema exists so return values need not be explained, yet the description usefully clarifies how to use the returned digest. For an irreversible mutation with zero annotation coverage, it covers the key behavioral risk; only edge cases like repeat sealing and permissions are 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?

One parameter at 0% schema description coverage, so the description should compensate; it implies upload_id identifies the upload being sealed but never states its meaning, origin (e.g. from upload_content), or type. Minimal added meaning over the bare integer field.

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 (seal) and resource (an upload), plus the concrete effect: fixing bytes and publishing sha256 and both lengths. This distinguishes it from siblings like upload_content and get_content, which move or read content rather than freezing 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?

Gives clear contextual usage: it must happen before the upload can be used as body_ref ('Only then can it be used as body_ref'), implying upload must precede it. It does not name alternative tools or state when not to seal, so it stops short of explicit alternatives.

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

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

Annotations declare readOnlyHint=true, and the description adds substantial behavioral context: it explains substring matching via trigram index, handling of short terms with plain scan, exclusion of soft-deleted messages, and the 'match' field indicating which method found a hit. It does not mention rate limits or error handling, but given the read-only nature and the existing annotation, the added detail is significant. No contradiction with annotations.

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

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

The description is dense but well-structured: it opens with the core purpose, then contrasts with a sibling, explains matching semantics, describes parameters, and closes with usage guidance. Every sentence contributes unique information, though the length is above average; it could be slightly tightened without losing 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?

Given the tool's complexity (7 parameters, output schema present), the description covers all essential aspects: query syntax, filtering options, field projection, performance characteristics, and exclusions. It does not need to explain return values since an output schema exists, and it addresses the likely pitfalls (e.g., substring matching, short terms). This is complete 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 0%, so the description must compensate, and it does thoroughly. It explains the query syntax (AND, quoted phrases, OR/NOT), the optional filters (from_role/to_role/kind/status), and the 'fields' parameter in detail, including the special value 'headers' and default behavior. This far exceeds what the bare schema provides.

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

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

The description clearly states it performs full-text search across channel history with ranking and snippets, and explicitly contrasts it with list_messages which is a substring filter. It identifies the exact use case ('what did we decide about X') and names the sibling it differs from, making its purpose unmistakable.

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 guidance on when to use this tool: when a listing over long history would be too large, and when ranked results are needed. It directly contrasts with list_messages, noting the substring filter is unranked, and advises fetching specific messages individually afterward. This leaves no ambiguity about tool 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 disclosure burden and meets it: it states refusals (sending to self, action_required with multiple recipients, proc without both explicit answers), validation limits (topic ≤ 80, addenda ≤ 4000), multi-recipient single-message semantics, pin/nudge retirement behavior, and the return shape {id, created_at}. No contradictions exist.

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

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

Information density is high and every sentence earns its place, but the delivery is a single dense run-on paragraph with no line breaks, bullets, or section headers. Front-loading is good ('Send a message'), yet the wall-of-text format makes the critical validation rules hard to scan. Appropriate length, poor structure.

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 13 parameters, complex cross-field validation, and subtle state-machine behavior, the description is remarkably complete. It covers edge cases, refusal conditions, hosted-channel vs stdio mode differences, and return values (which the output schema also documents). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0%, and the description fully compensates. Every parameter is explained: 'to' (role/list/'*'), 'kind' with its enum values, 'work_status' with its six states, 'pin_key', 'voters', 'about_message_id', 'addenda', 'body_ref', 'action_required', and 'decision_requested' — including constraints and interplay between them.

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

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

Opens with a specific verb+resource ('Send a message') and immediately establishes scope through role semantics. The description makes the tool's purpose unmistakable and clearly distinguishes it from siblings like upload_content, set_work_status, and mark_read by explicitly referencing them and their different functions.

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 extensive when-to-use guidance: explains which kinds allow multi-recipient sends, when action_required is refused, when decision_requested should be set false, and points to alternatives like upload_content + seal_content for long bodies and set_work_status for later status changes. This exceeds mere context and gives actionable selection criteria.

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

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

The description discloses that the tool reflects the live running process, not static code, and that it surfaces deliberate omissions. This adds meaningful behavioral context beyond the readOnlyHint annotation, with no contradiction.

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

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

Three dense sentences with the core purpose front-loaded. The phrasing is slightly elaborate but each clause contributes meaning and no information is wasted.

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 no-parameter read-only introspection tool with an output schema, the description fully covers what the tool is, why to use it, and when to call it. Nothing necessary for correct invocation is missing.

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

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

The tool has zero parameters and the schema coverage is 100%, so the description has no parameter burden. A baseline of 4 is appropriate because no parameter explanation is needed.

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 identifies what the tool does: reports the running server's version, changes, implementation details, and deliberate non-implementations. It distinguishes itself from source-tree inspection and implies a unique role among sibling tools.

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

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

Explicitly tells the agent to ask this tool instead of reading a source tree and to call it after an upgrade rather than discovering changes by breaking against them. 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, the description carries the full burden of behavioral disclosure, and it delivers thoroughly. It reveals that every transition is logged, that re-setting the current value by the same role is a no-op while by the other role is an audited transition, that blocked_by must reference an unresolved action_required message or be rejected, and that 'done' is not a dead end. It also states the note length limit and that third roles are rejected.

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 highly structured, starting with the primary purpose, then transitions, semantics, blocked usage, and note limit. Every sentence adds value and avoids redundancy. It is front-loaded with the core action and the critical exclusion. The length is justified by the complexity of the state machine, though it could be slightly tighter.

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 covers all essential aspects: when to use it, transition rules, role restrictions, blocked_by semantics, audited logging, and the no-op case. The output schema exists, so return values are not required. The description is sufficiently complete 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?

Schema coverage is 0%, so the description must compensate, and it does for message_id, work_status (with semantic explanations of done_local, done, needs_you, blocked), note (max 4000 chars), and blocked_by (must be an unresolved action_required message). However, it does not enumerate the full set of allowable work_status values, only the notable ones, leaving the agent to infer the complete enum.

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 action ('Change the work_status of an EXISTING message') and explicitly contrasts with sending a new message. It clarifies scope (existing message) and role constraints (sender or recipient only), which distinguishes it from send_message and other message-related tools.

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 provides explicit when-to-use guidance ('do not send a new message just to change status'), explains transition rules (any value can be set, with the done exception), and gives detailed instructions for blocked_by usage versus manual blocking. It also differentiates the semantics of 'needs_you' relative to the setter, giving clear context for when this tool is appropriate.

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 responsibility. It discloses return shape ({restored, refused}), error behavior (raises when nothing restored), logging (both retirement and undo stay in message_history), and the reason length limit. It does not mention idempotency or partial-failure details, but it is otherwise transparent.

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, front-loaded with purpose, and every sentence adds essential detail: constraints, permissions, return value, logging, and reason limit. No filler 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?

Despite lacking explicit parameter explanations, the description covers purpose, usage restrictions, permissions, return format, error behavior, logging, and constraints. For a tool with a simple two-parameter schema and an output schema, this is nearly 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 0%, so the description must compensate for both parameters. It only addresses 'reason' (length limit), leaving 'ids' as implicit – an agent must infer that ids refer to the records to restore. This is insufficient for reliable 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: 'Undo a cleanup: put back records that backfill_superseded retired.' It explicitly distinguishes from the related tool by clarifying what it cannot undo (proposal retired by a vote or new pin version), making its purpose unambiguous and separating it from 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?

It provides explicit when-to-use conditions: only retirements from a cleanup pass can be undone, and only the role that applied the pass or the owner of the key may use it. It also states exclusions (vote-based or pin-version retirements), giving clear guidance on 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 full burden of behavioral disclosure, and it does so thoroughly. It states who may append, that sealed uploads cannot be appended to, the 8 MiB UTF-8 limit, the 80-character label limit, that a sealed upload has its own sha256 and lengths, and what the function returns.

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 sentence earns its place: purpose, usage pattern, security constraint, size limit, label limit, digest semantics, and return value. It is front-loaded with the main use case and then adds necessary constraints, with 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 stateful, multi-call upload tool, the description is complete: it defines the workflow, the lifecycle with seal_content, downstream consumers, size and label limits, access rules, and return values. Even though an output schema exists, the description adds useful behavioral context and leaves no critical gap for an agent.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the two non-obvious parameters: upload_id is the append key, and label has an 80-character cap. The required text parameter is only indirectly described as the piece to upload, which is enough given the tool's name and first sentence, but a direct statement that 'text' is the chunk would have been stronger.

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: upload a document in pieces, enabling large bodies to be sent. It clearly frames the chunked-upload mechanism and distinguishes this tool from send_message, revise_message, pin_set, and especially seal_content by explaining the append-and-seal workflow.

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 tells the agent when to use the tool: when a body is too large to type in one call. It then gives precise procedural guidance: call repeatedly with the same upload_id to append, call seal_content after the last piece, and pass body_ref=<upload_id> to send_message, revise_message, or pin_set. This leaves no ambiguity about how to invoke it 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?

Annotations only provide readOnlyHint=true; the description carries the full burden and does so thoroughly. It discloses the wake condition (new item in actionable counters), the difference between 'pending' and 'pending_at_entry', the immediate return with ignore_backlog=false, the timeout cap at 50s, the retry response, and that nothing is lost between calls. This goes well beyond the annotation and gives the agent a complete mental model.

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 longer than typical but every sentence contributes to purpose, usage, or behavior. It is logically ordered: purpose first, then usage, then wake conditions, then return semantics, then timeout and persistence. There is slight redundancy (e.g., 'sleep' and 'wakes') but no wasted filler. It earns its length given the 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 tool with 3 parameters and no schema coverage, the description covers almost all needed information: what it does, when to use, wake conditions, return values (though output schema exists), timeout behavior, and retry semantics. The only missing piece is poll_interval_s, but that is a minor tuning parameter. The description is complete enough for an agent to call it correctly without further investigation.

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 explains timeout_s (cap at 50s) and ignore_backlog (behavior when false and its relation to backlog), but poll_interval_s is not described at all. The description covers two of three parameters meaningfully, leaving a gap for the third. Since it adds value beyond the schema for most params, this is a strong 4.

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

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

The description clearly states a specific verb ('sleep') and resource ('channel') and enumerates the kinds of events it watches for (new mail, obligation, proposal, etc.). It explicitly contrasts with wait_for_reply, distinguishing it from the nearest sibling. This leaves 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?

It gives explicit guidance: use it when finished with your own work and want to stay available, instead of ending the turn. It contrasts with wait_for_reply (which waits for a reply to one message) and explains the ignore_backlog=false condition that returns immediately if anything is pending. This provides clear when-to-use and when-not-to-use context.

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

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

Annotations only say readOnlyHint=true, and the description adds substantial context: timeout return shape, no-message-loss guarantee, late-reply persistence, nonexistent-id refusal, and the 50s cap. No contradiction with annotations.

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

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

Every sentence earns its place, covering purpose, timeout semantics, filtering logic, refusal behavior, and the wait cap. It is dense but not bloated, with a slightly run-on structure toward the end.

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?

Covers edge cases and operational details: timeout retry semantics, no data loss, after_id loop pattern, include_read behavior, nonexistent message refusal, and the 50s MCP-timeout-aware cap. An agent can invoke and loop correctly without external 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?

Schema has 0% description coverage, and the description compensates for most params: message_id, after_id, include_read, and timeout_s behavior. poll_interval_s is only covered by its title, but is inferable from the name and default.

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: 'Block-poll the inbox for a reply to a given message_id that you have NOT seen yet.' This clearly differentiates it from list/read siblings by emphasizing blocking behavior and the unread filter.

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

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

Gives clear usage context and looping guidance: 'pass after_id=<the last reply you handled> when looping without marking things read' and explains include_read. It does not explicitly name alternatives, but the unique polling behavior makes the use case unmistakable.

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