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

With no annotations to lean on, the description carries the behavioral burden and does so thoroughly: acks are audited, explicit ack grants a 24h reissue lock, governance auto-acks produce a ~1h lock, and unacked tokens remain freely reissuable. It also mentions the failure-mode benefit ('session dying between claim and persistence no longer strands the identity'), which is beyond what the schema or annotations would reveal.

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 call timing, then layers detailed rationale without filler. Each sentence adds a distinct fact: audit, lock duration, auto-ack alternative, and unacked reissue behavior. It is dense but appropriately sized for a lifecycle-critical tool.

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

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

For a two-string-parameter tool, the description covers what the tool does, when to call it, what happens if you do, what happens if you do not, and how it relates to the governance-call auto-ack path. An output schema exists, so the absence of return-value details is not a gap here.

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 both parameters, but it only clarifies the token concept (governance token, plaintext to durable storage) and never mentions 'author'. The author parameter remains undocumented; the description adds no meaning for it beyond the schema's bare 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?

The description opens with a specific verb and resource: confirming that a governance token was persisted, tying it to a concrete lifecycle stage (v2.1 phase 2; v2.3 explicit tier). It clearly separates an explicit ack from a governance-call auto-ack, which prevents confusion with the governance 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?

It gives an explicit trigger ('Call this right after writing the plaintext to durable storage (and reading it back)') and contrasts it with the alternative auto-ack path that produces only a short lock. It also warns to persist before any governance use and explains the consequence of not acking, so an agent knows exactly when this tool is required.

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?

There are no annotations, so the description carries the full burden. It clearly discloses the destructive effect (clearing ALL verdicts), the cost ('Costs 1 budget'), the re-vote requirement, and the free first verdict. This goes well beyond the minimal schema info and gives an agent a solid understanding of the side effects.

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

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

The description is three tight sentences, each earning its place: the core action, the usage rationale, and the cost/voting consequence. It is front-loaded with the most important identifying information and contains no fluff.

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 prerequisites, side effects, cost, and voting consequences. Since an output schema exists, return-value detail is not required. An agent has enough context to decide when to call this tool and what will happen.

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

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

Schema description coverage is 100%, so the schema already documents token, author, and thread_id well. The description reinforces the author requirement ('Creator-only') but does not add significant new parameter-level meaning beyond what the schema already 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 states a specific verb and resource ('bump the thread's revision') and the key effect ('clearing ALL verdicts (G2)'). It is clearly distinguishable from siblings like set_verdict or set_status because it acts on the revision as a whole and resets the verdicts.

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 it ('after revising the artifact under review') and why ('stale passes must not auto-resolve a new revision'). It also carries an implicit exclusion with 'Creator-only,' but it does not name alternative tools or explicitly state when not to use it beyond the creator restriction.

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 exceeds it. It discloses that the token is issued provisionally, the plaintext is shown only once, the need to persist it, the short lock on auto-acks, the 24h anti-hijack lock on explicitly-acked tokens, and the reissue behavior for unacked tokens. It even references incident threads as evidence. This is exceptional transparency.

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

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

The description is lengthy (about 150 words) and includes historical incident references, which adds bulk. However, it is structured into paragraphs and the key points are front-loaded (phase 1, persist now, confirm with ack). While every sentence carries value, it could be tightened without losing meaning.

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

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

The description thoroughly covers the tool's behavior, risks, locks, and next steps, making it highly informative for an agent. The only significant omission is the meaning of the 'author' parameter, which is required. Since the output schema exists but is not described, and the description covers most operational aspects, this is a minor 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?

The input schema has a single required parameter 'author' with no description, and the description does not explain what 'author' means or how to fill it. With schema description coverage at 0%, the description was expected to compensate, but it provides zero information about the parameter. This is a critical 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 clearly states the tool's action: 'Issue (or reissue) your governance token', and immediately frames it as phase 1 of a two-phase process. It distinguishes itself from the sibling ack_token by explaining this call is the provisional phase, and mentions reset_token indirectly through the reissue concept. The purpose 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?

The description provides explicit guidance: use this to get a provisional token, then confirm with ack_token, and do NOT go straight to governance. It explains the consequences of auto-acking vs explicit acking, and when reissue is allowed without a lock. This is thorough and prescriptive.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Start a new review topic' and does not mention side effects, persistence, authentication requirements, rate limits, or whether the action is reversible. This is a significant gap for a creation tool.

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

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

The description is a single, efficient sentence with no wasted words. It is appropriately lean, though it sacrifices valuable behavioral context for brevity.

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

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

Despite having an output schema and fully documented parameters, the description omits higher-level context: what makes a thread distinct, when to create one, and what happens after creation. Agents cannot confidently invoke this tool based solely on the provided text.

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

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

Schema description coverage is 100%, so every parameter is documented in the input schema. The tool description adds no parameter-level information beyond the schema, which gives a baseline of 3 with no bonus for additional semantic 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 'Start a new review topic' uses a clear verb and resource, making the core action understandable. It distinguishes itself from sibling read/comment tools like list_threads and post_comment, though it could be more explicit about what constitutes a 'review topic'.

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

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

No guidance is provided on when to use this tool versus alternatives such as get_thread, list_threads, or post_comment. There are no stated prerequisites, context, or exclusions, leaving the agent to infer the proper usage scenario.

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

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

No annotations are provided, so the description must disclose behavioral traits itself. The description states it 'returns' the protocol, implying a read-only operation, but it does not explicitly state that it has no side effects or what happens if called multiple times. It does add context about the versioned nature and the footer equivalence, which helps an agent understand the data's consistency. However, it lacks explicit statements about authentication or idempotency, which would be valuable without 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 two sentences long and wastes no words. The first sentence states the primary purpose, and the second provides a critical usage instruction and a secondary fact. It is front-loaded with the action and includes essential guidance without fluff.

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

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

Given that this is a simple retrieval tool with no parameters and an output schema exists, the description covers everything an agent needs to know: what it returns (the versioned protocol), who should call it (new members), and when (before participating). The mention of the footer adds extra context but is not essential. The output schema handles the return structure, so no further detail is needed.

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 input schema is trivially complete with 100% coverage. The description does not need to explain parameters, and the baseline for 0-parameter tools is 4. The description does not add any parameter-related semantics, but none are needed. It correctly focuses on the output and usage context.

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 action: 'Return the board protocol (versioned).' The verb 'Return' plus the specific resource 'board protocol' makes the purpose unambiguous. It also adds that the protocol is versioned, which distinguishes it from a static text retrieval. Among the sibling tools, this is the only one that retrieves the protocol, so it stands apart.

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

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

The description explicitly instructs when to use the tool: 'New members MUST read this once before participating.' This is a strong usage guideline that tells the agent exactly who should call it and when. It also notes that the board footer shows the same text, implying the tool is a programmatic way to access it, but the 'MUST' directive 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?

With no annotations, the description carries the burden of behavioral disclosure. It explains the key behavior: the result contains metadata plus the entire comment tree with nested replies. As a read operation, no side-effect warnings are necessary, though auth/error behavior is not mentioned.

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 one focused sentence that front-loads the resource and immediately clarifies the nested-reply behavior. Every word earns its place.

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

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

For a tool with one well-described parameter and an output schema, the description sufficiently conveys the operation and return shape. It only lacks explicit routing guidance relative to sibling tools, but that is not critical to invoking 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 input schema already describes thread_id as 'the thread to read' with 100% coverage. The tool description does not add any further parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Get') with a precise resource: a whole thread including metadata and the full comment tree. It clearly distinguishes this from list_threads or list_comments_since by emphasizing nested replies under parents.

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

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

The intended use is implied by 'whole thread', but the description does not explicitly state when to use this tool versus siblings like list_threads or list_comments_since. No exclusions or alternative routing are 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 no annotations, the description carries the full behavioral burden and succeeds: it discloses the liveness heartbeat, cursor advancement side effect, union-window computation, the sentinel behavior when author is omitted, and the meaning of awaiting_my_verdict. This is far beyond what annotations or schema alone would provide, and nothing contradicts the structured data.

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

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

The description is dense but front-loaded with the most important behavior. Every paragraph adds necessary semantic detail, though internal document references like 'dsh-2', 'C3', and 'dsh #89 minor-5' add background complexity that may not be resolvable by the agent. Still, it is structured and free of 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 polling tool with subtle cursor semantics, the description covers the needed context: when to pass author, how the cursor advances, what the needs_attention header contains, and the sentinel edge case. An output schema exists, and the description also gives return-value guidance, so 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 100%, so the baseline is 3. The description adds real meaning beyond the schema: author controls liveness registration and backlog-union windowing, and since is the first-round fallback when no cursor exists. This improves an agent's ability to set both parameters correctly.

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

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

The description states a specific action and resource — 'Poll for new comments' — and immediately distinguishes this tool from siblings by calling it 'the ONE call that advances your last_read cursor.' An agent can tell it apart from get_thread and the probe without inspecting schemas.

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

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

It explicitly says when to use the tool ('Poll for new comments'), how to use it correctly ('always pass your own tool name'), and what other tools cannot do ('get_thread/the probe/anything else never advances it'). This gives the agent clear selection and invocation 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 behavioral disclosure. It explains the output format, status tiers, idle threshold, heartbeat, and last_wake_error semantics. It does not mention sorting, pagination, or auth, but for a read-only list tool the disclosed behavior is sufficiently rich.

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 action. The second sentence adds precise output details without redundancy. Every element earns its place, including the concrete idle threshold and watcher failure gate reference.

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, the description explains the meaning of returned fields, status tiers, and the diagnostic distinction between 'waiting for member' and 'fix watcher.' This fully equips an agent to invoke and interpret 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?

The tool has zero parameters, so no parameter documentation is needed. The description correctly focuses on output semantics, which is the only relevant caller concern. Baseline 4 is appropriate for a parameterless 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?

States a specific verb and resource: 'List registered participants with liveness status.' The description clearly differentiates this from sibling tools by focusing on participant liveness rather than threads, comments, or protocol actions, and details the exact output contents.

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 clear context for when the tool is useful: to determine whether a participant is simply waiting or has a watcher failure. It lacks explicit exclusions or named alternatives, but the intended use case is evident from the description.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'List' implies a read-only operation, but the description does not explicitly state side-effect-free behavior, default filtering, pagination, or ordering. It also does not mention the status filter behavior that the schema documents.

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, clear sentence with no filler or redundant wording. It is front-loaded and easy to parse, though it is minimal enough that it sacrifices useful context.

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

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

Given the low complexity (one optional parameter), full schema coverage, and the presence of an output schema, the description plus schema cover the basic mechanics of invoking the tool. However, it lacks usage guidance and behavioral transparency, so an agent may not know when to prefer this over get_thread or what default behavior to expect.

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

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

Schema description coverage is 100%, so the schema fully documents the only parameter, status. The description adds no additional parameter meaning, but because the schema already covers it, the baseline of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'List review threads.' This clearly states the operation and object, and is distinguishable from siblings like get_thread (single thread) and list_comments_since (comments). However, it does not explicitly differentiate itself from those 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 provides no guidance on when to use this tool versus alternatives such as get_thread, create_thread, or list_comments_since. There is no mention of typical use cases, exclusions, or how this list operation relates to the other thread-related 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 provided, the description carries the full behavioral burden. It discloses the critical constraint (100-comment cap and rejection on full threads), which is genuinely valuable. However, it does not state success behavior, return contents, or any permission/authorization expectations for a write operation, leaving those gaps uncovered.

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

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

Purpose is front-loaded in the first sentence, and the critical cap constraint is isolated in a compact second block. No filler or repetition; every sentence earns its place, though the structure 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?

For a 6-parameter write tool with a full output schema and 100% schema coverage, the description covers the essential behavioral edge case (capacity rejection) and routing. The only notable omission is an explicit differentiation from reply_comment, but overall the agent has what it needs to call the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters (including the author enumeration in the schema's own description). The tool description adds no parameter-level meaning beyond the schema, so it sits at the baseline 3.

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 ('Post a top-level review comment in a thread') and the qualifier 'top-level' explicitly separates it from the sibling reply_comment. An agent can distinguish this from its closest sibling without opening the schema.

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

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

Discloses the discussion cap and gives an explicit when-not condition ('Posting into a full thread is rejected') with a named alternative ('conclude with set_status instead'). It does not explicitly contrast with reply_comment, but 'top-level' plus the set_status routing covers the main decision points.

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 full responsibility for behavioral disclosure. It explicitly states it is read-only, derived over a query_only connection with no writes possible, and that it provides raw components only with no composite score. It also notes it has zero governance weight and is behavior-invariance tested. This is exceptionally transparent about side effects and limitations.

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 a clear one-line purpose, then expands into detailed technical specifications. It is dense but every sentence adds value, covering the types of data, the classification scheme, and the operational constraints. It is longer than a trivial description but proportionate to 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 complexity of the tool, the description is thorough. It explains what the profile contains, the semantics of the metrics, the distinction between verdict_free and verdict, and the no-write guarantee. The output schema exists, so return format is covered. Nothing essential 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 input schema already fully describes the single parameter 'author' with 100% coverage, including the note that it can be one's own name or another's. The description adds no additional semantic information about the parameter itself. Since schema coverage is complete, the baseline of 3 is appropriate.

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

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

The description states a specific purpose: 'Read-only derived behavior profile for a member.' This is a clear verb+resource combination that distinguishes it from sibling tools like get_protocol or set_verdict, which are about other aspects. The observational nature is emphasized, so an agent can immediately understand this is a non-mutating query.

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 conveys when to use it: for inspecting a member's behavior profile without affecting anything, as it is 'pull-only' and 'never enters any decision path.' It doesn't explicitly contrast with sibling tools, but the read-only, observational framing makes the intended context clear. The absence of explicit alternatives is a minor gap, but the context is strong enough to guide usage.

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

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

No annotations are provided, so the description carries the burden. It discloses a non-obvious domain rule (100-comment cap) and the rejection behavior, plus a workflow alternative. It does not cover auth or side effects, but the key mutation constraint is stated.

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

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

Two short paragraphs, front-loaded with the core action and then the constraint. Every sentence adds information; no filler.

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

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

The description covers purpose, the critical cap, and the fallback tool. However, the phantom 'parent_id' reference creates a real invocation hazard, and there is no mention of error behavior for invalid comment_id, so it is not fully complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description references 'parent_id' which is not present in the input schema (additionalProperties: false). This can mislead an agent into passing an invalid parameter, so the description actually detracts from parameter 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?

States a specific action ('Reply to an existing comment') and resource ('existing comment'), and the parenthetical about multi-level nesting clarifies capability. It is distinguishable from siblings like post_comment by the word 'existing' and from set_status by mentioning the alternative.

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

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

Explicitly says replying into a full thread is rejected and directs the agent to 'conclude with set_status instead.' The phrase 'existing comment' implies it is not for top-level posts, giving clear selection context.

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

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

With no annotations, the description carries the full burden. It discloses that this is a human-authorized, protocol-level override with no protocol-layer auth, and mentions 'no DB surgery, audited append-only' to signal safety and logging behavior. It also ties misuse risk to explicit user instruction. It doesn't state reversibility or prerequisites (e.g., identity must exist), but for a sensitive mutation it is unusually 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 and well-structured, with the core purpose front-loaded and supporting security context following. Every sentence adds information. Minor jargon ('protocol-level root path', 'Threat-model bound') is dense but not verbose.

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 there are only two simple parameters, the description covers the required invocation semantics, security context, and effect. It does not explain what responses look like, but the output schema covers that. The only gap is that it relies on familiarity with set_status's human_override pattern, which an agent might not have.

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 maps 'named identity' to the author parameter and explains human_override in depth, including when it may be set. It does not explicitly spell out that author is the identity whose token resets, but the phrasing is sufficient for an agent to infer the mapping.

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 resets a token: 'Clears the named identity's token so its next claim_token issues fresh.' This is a specific verb and resource, and it distinguishes from siblings like claim_token and ack_token. The 'protocol-level root path' framing adds context without obscuring the core action.

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

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

It gives explicit guidance for the critical human_override flag: 'the flag is to be set ONLY when the machine's user explicitly instructs it.' It also references set_status's human_override as a sibling pattern, which helps an agent infer the exceptional nature of this operation. It doesn't name an alternative tool for ordinary token refreshes, but the condition 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?

With no annotations, the description carries the burden and does disclose useful constraints: creator-only, open-thread requirement, and the floor rule with rationale. However, the claim that additions 'require the names to be registered' conflicts with the schema's note that unknown names are auto-registered, weakening the description's 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?

Two compact sentences front-load the core constraint and avoid unnecessary prose. The internal reference 'trae 边界6' is somewhat cryptic and not helpful to an external agent, but it does not meaningfully bloat the description.

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

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

The description captures essential preconditions and the floor rule, and an output schema is present so return values need not be described. However, it does not clarify add/remove interaction, token usage, or error behavior, and the registration contradiction leaves an important 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 coverage is 100%, so the baseline is 3, and the schema already documents author, thread, add, remove, and token. The main description adds little beyond the floor constraint and actually introduces a contradictory precondition ('names to be registered') that could mislead an agent into rejecting valid adds.

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 ('amend a thread's quorum') plus the key qualifiers: creator-only, open threads, and a floor of 2. This distinguishes it from siblings like create_thread, which establishes a quorum rather than changing one.

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 eligibility conditions: only the creator may call it, only for open threads, and shrinking below 2 members is prohibited. It does not explicitly name alternative tools, but no sibling covers the same amend-quorum operation, so the guidance is sufficient.

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

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

With no annotations, the description carries the full transparency burden and meets it: it discloses the quorum gate, the missing-verdicts rejection report, the terminal nature of wontfix, and the human-only revert rule. This goes well 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 tool's purpose and the exactly-one parameter rule are front-loaded, and each gating clause carries operational weight. The stage-version note (3a/3b) is somewhat extra but still explains current gate behavior.

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 five parameters, an output schema, and no annotations, the description covers the main edge cases: quorum gating, active-member relaxation, auto-resolve, and the human_override requirement for wontfix. It is slightly ambiguous whether the quorum gate applies to single-comment status changes as well as whole-thread changes, but it is otherwise sufficient.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by stating the mutual exclusivity of thread_id/comment_id and the conditional circumstances requiring human_override. It does not repeat the schema's field-by-field definitions.

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

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

The opening sentence names a specific verb ('Mark'), a precise resource ('a thread or a single comment'), and the allowed states ('resolved or wontfix (set back to open)'). This is clearly distinct from the sibling set_verdict, which deals with member verdicts rather than thread/comment status.

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

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

The description gives explicit invocation rules: pass exactly one of thread_id/comment_id, and it spells out when manual 'resolved' is rejected and when human_override is mandatory for 'wontfix'. It does not explicitly name alternative tools for deciding between status and verdict, so it stops short of full alternative routing.

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

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

With no annotations, the description fully discloses major behaviors: cost model (first verdict free, flips cost 1 from thread budget), note requirement for object, quorum restriction, and the reopen side-effect on resolved threads. This goes well beyond the basic verb and helps the agent predict consequences.

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

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

The description is front-loaded with the core action, then uses a tight bulleted rule list. Every sentence carries a distinct constraint or consequence; no filler or repetition of schema details.

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 governance tool with complex budget and quorum rules, the description covers the essential conditions an agent must know to invoke it correctly: eligibility, token, note requirements, cost, and reopen behavior. The output schema exists, so return-format details are not needed in the description.

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

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

Although schema coverage is 100%, the description adds meaning not in the schema: 'object' must have a non-empty note, author must be in quorum, token is the governance credential, and verdict values are pass/object with flip costs. This materially improves 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 names a specific action ('Cast/flip YOUR verdict on a thread') and clearly identifies governance voting as the resource, which is distinct from siblings like post_comment, set_status, and bump_revision. Even without explicit sibling comparisons, an agent can immediately tell what this tool is for.

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 clear context for use: a governance action requiring a token and quorum membership, with explicit rejection of non-quorum members. It does not explicitly state when to prefer this over sibling tools, but the verdict-specific purpose and constraints make the intended use unambiguous.

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