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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds substantive behavior beyond them: the -32010 error when no open review is addressed to the caller, the resulting state (abstained), and the fact that this state is non-terminal with named follow-up tools.

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 sentences, all load-bearing: purpose, alternative differentiation, error condition, and state/exit paths. Front-loaded and free of filler, though the differentiation clause is dense enough that it is slightly heavier than strictly needed.

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

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

For a non-idempotent write tool with no output schema, the description supplies exactly what is missing: the precondition (open review addressed to caller), the failure mode (-32010), and the post-state with onward routes. Params are fully covered by the schema, so nothing an agent needs to call it correctly is absent.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the enum. The description only alludes to category values ('conflict of interest', 'want of context'), adding marginal semantic color rather than new syntax or format detail. Baseline 3 applies when the schema does the heavy lifting.

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 (stand aside from a review) and the scope (a participant who cannot decide), and explicitly contrasts itself with chap.decide.reject: abstaining judges nothing and leaves the artefact intact. An agent can distinguish it from decide.reject without opening either schema.

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

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

Gives an explicit when-not path (use in place of chap.decide.reject) and the precondition that selects this tool: an open review addressed to the caller. It also names the recovery routes (chap.escalate.raise, fresh chap.review.request) when the abstention is not the end of the story.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: accepted calls land under 'envelope', refused coordinator-recorded attempts under 'request' with an 'outcome' error code and no effect, and entries return unaggregated so grouping is the caller's job. That is exactly the behavioral context annotations cannot carry.

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 purpose and scope before the return-shape detail, and most sentences carry real information. The refused-attempt example is illustrative and slightly padded, but overall it is dense without being wasteful for a nested-schema 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?

With no output schema, the description correctly shouldered the return-value burden by explaining the envelope/request distinction and the unaggregated shape. It leaves ordering, result-size limits, and any pagination behavior unstated, which is a real gap for a log-query tool.

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

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

Schema description coverage is 100%, so the schema already documents range, filter, and workspace fully. The description restates the filter axes (method, sender, task, outcome) without adding syntax or semantics beyond what the nested schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('Read entries from a workspace's audit log') with the scope of optional range/filter narrowing. It implicitly separates itself from the audit verification siblings by calling itself 'the query surface for everything the workspace has recorded', but it never names an alternative tool, so sibling routing is left to inference.

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 context is implied: it is the read path for recorded entries and 'records nothing, so it never appears in its own output'. However there is no explicit when-to-use statement versus chap.audit.verify_chain, verify_receipt, or submit_to_scitt, and no exclusions or prerequisites are given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=false and destructiveHint=false, so the safety profile is largely covered. The description adds valuable fallback context (statements returned unsigned when no submitter is configured), but it does not address the non-idempotent hint — i.e. that repeat submissions anchor duplicate statements — nor what a configured submission 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?

Two sentences, front-loaded with the core action and then the conditional fallback. No filler, no restatement of the title or schema.

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?

Complete for a tool whose annotations carry the safety profile and whose schema fully documents all parameters, including the nested range object. The one open question, the return payload when a service is configured, is minor and partly implied by the out-of-band 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?

Schema description coverage is 100%, so all four parameters including the nested sequence window are documented in the schema itself. The description only loosely gestures at 'a range of audit entries' and adds no syntax, defaults, or sequencing semantics beyond what the schema already states.

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+resource: building COSE_Sign1 statements for a range of audit entries and submitting them to the SCITT transparency service. This clearly separates it from sibling audit tools (audit.read, audit.verify_receipt, audit.verify_chain) by function, though it never names an alternative to disambiguate the choice explicitly.

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

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

Usage is implied by the description: use it to anchor entries, with a stated fallback (out-of-band return) when no SCITT service is configured. However, it never says when an agent should choose this over chap.audit.verify_chain or verify_receipt, nor any prerequisites for anchoring.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds substantial context beyond them: it enumerates the verified/not_evaluated/error outcomes and warns that not_evaluated must not be reported as verified. This is the key behavioral information an agent needs to interpret results, and it is absent from 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?

Three tight sentences, front-loaded with the core action, then the result-interpretation rules. Every sentence earns its place with no 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?

There is no output schema, so the description correctly takes on the burden of explaining return semantics, and it does so with the status/ok/entries_unchecked mapping. The only shortfall is the absence of routing guidance relative to sibling audit tools.

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

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

Schema description coverage is 100% and both parameters are documented with examples in the schema. The description adds no additional meaning about the 'from' participant URI or 'workspace' identifier, so the baseline 3 applies.

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

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

States a specific verb+resource combination: 'Replay a workspace's prev-hash chain.' An agent can tell this is a chain-integrity verification operation. It does not explicitly distinguish itself from the close sibling chap.audit.verify_receipt, which is the only gap.

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

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

Usage is implied (use this to verify chain integrity) and the description gives strong interpretive guidance for results, but it never states when to choose this over chap.audit.verify_receipt or chap.audit.read, nor any explicit exclusions or prerequisites.

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

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

Annotations already cover readOnly/idempotent/openWorld/destructive, so the bar is lower, yet the description still adds real behavior: fail-closed semantics with error code -32082 when no hook is configured, and the guarantee that a missing verifier cannot read as a pass. That is exactly the kind of failure-mode context annotations cannot express.

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

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

Four tight sentences, front-loaded with the purpose and the sibling contrast, followed by the failure behavior and read-only guarantee. No sentence is redundant or restates the schema.

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 verification tool with no output schema, the description covers purpose, sibling distinction, and the failure path thoroughly. It could still say what a successful verification yields (e.g. a boolean verdict vs a receipt echo), so it is nearly but not fully complete.

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

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

Schema description coverage is 100%, so the schema documents workspace, from, and the nested receipt object itself; the description adds only the semantic framing that the receipt comes from an external service. Baseline 3 applies since the structured schema carries the parameter 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?

States a specific verb (Check) and resource (a receipt returned by an external SCITT transparency service), with the outcome spelled out ('confirming that service logged the statement'). It explicitly names the sibling it is not — chap.audit.verify_chain — and draws the boundary between them.

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

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

Explicitly routes the agent between this tool and chap.audit.verify_chain ('the two answer different questions'), which is strong when-to-use guidance. It stops short of naming the precondition that produces the input (a receipt from chap.audit.submit_to_scitt) or an explicit when-not clause, so it's clear context rather than full routing.

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

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

Annotations already declare destructiveHint=true, non-idempotent, non-readOnly, so the safety profile is covered. The description adds genuinely new behavioral context: cancellation is terminal and settled tasks are refused, which an agent cannot infer from the annotations alone. It stops short of describing what happens to in-flight participants or partial work.

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

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

Two sentences, zero filler, with the core action front-loaded and the terminality constraint immediately following. Every clause earns its place.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers the key risk (terminal, irreversible) and the refusal condition, while annotations and the 100%-covered schema handle the rest. The remaining gap is routing guidance against supersede/rollback.

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 all four parameters including the refusal code -32061 and the audit-recorded reason are fully documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema carries the weight.

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 ('Cancel a task') that an agent can immediately act on. It is distinguishable from most siblings, but does not explicitly separate itself from the close neighbours chap.control.supersede and chap.task.complete, which an agent must choose between.

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 through the constraint that an already-settled task cannot be cancelled, which tells the agent this only applies to in-flight work. However, it never states when to prefer cancel over supersede, rollback, or complete, and gives no prerequisites or permissions guidance.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds genuine behavioral context on top: a completed/declined/cancelled/superseded task is refused with error -32061, participant scope leaves existing work running, and workspace scope restricts the API surface to an explicit allowlist. It does not mention authorization requirements or what a paused task means for downstream routing, keeping it out of the top band.

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 verb ('Pause work.') followed by three parallel scope clauses, each earning its place by describing a distinct effect. The workspace clause's long method allowlist is dense but informative. No filler sentences.

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 seven-parameter control operation this is substantially complete: the core complexity (differing behavior per scope) is spelled out, and the schema fully documents the remaining parameters. The notable gap is the absence of any return/result information, which matters because there is no output schema, and no statement of the authority required to pause at workspace scope.

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

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

Schema description coverage is 100%, so the baseline is 3 and the schema already documents all seven parameters, including the enum semantics for scope and in_flight_policy and the warning that the coordinator ignores in_flight_policy. The description's scope sentence largely restates the schema's own scope description rather than adding format, interaction, or dependency 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 names a precise verb (pause) and enumerates the concrete effect per scope: task moves to 'paused', participant stops receiving new assignments, workspace blocks all but a short allowlist. The effect-level detail makes the tool unmistakable. It stops short of naming sibling operations (chap.control.cancel, chap.control.resume, chap.control.supersede) that an agent must choose between, so the differentiation is implicit rather than explicit.

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 context is implied through the three scope clauses, telling the agent what each scope accomplishes. There is no statement of when to pause versus cancel, supersede or roll back, and no exclusions or prerequisites (who may pause, what state the target must be in). The agent must infer the selection from the sibling names alone.

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

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

Annotations already declare the operation is non-read-only, non-destructive, non-idempotent, and closed-world. The description adds meaningful behavioral context by explaining exactly what each scope does: a task returns to its paused state, a participant can be assigned tasks again, and a workspace returns to active. It does not cover permission requirements or return format, but the core side effects are disclosed.

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

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

The description is a single front-loaded sentence that efficiently covers the tool's operation and the three scope outcomes. It wastes little space, though its dense colon-and-list structure is slightly harder to parse than a more naturally split sentence would be.

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 output schema, five fully documented parameters, and annotations covering safety traits, the description is nearly complete. It explains scope-dependent behavior well, but does not address when to use this tool versus sibling control operations or mention prerequisite state beyond what the schema provides.

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 fully documents each parameter, including scope values and the refusal code for unpaused tasks. The description reinforces the scope meanings but does not add syntax, ordering, or dependency details beyond what the schema provides. Baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

The description gives a specific verb and resource: resume work paused at the same scope. It clearly separates the three possible scopes (task, participant, workspace) and their effects, so an agent can understand the operation. It does not explicitly distinguish this from sibling control tools such as pause or rollback, but the core purpose is clear.

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

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

Usage is implied through the phrase 'paused at the same scope' and the scope descriptions, which indicate this tool is used after some prior pause. However, the description does not explicitly say when to choose this over alternatives like chap.control.pause, cancel, rollback, or supersede, nor does it list exclusions beyond the schema-level refusal note for unpaused tasks.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds genuinely new behavior: the rollback is appended to the audit log rather than rewriting history, and only mode ceiling plus member roles are reapplied. It still omits permission requirements and whether a rollback can itself be undone.

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

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

Two sentences, zero filler, and the most consequential fact (what gets restored) is front-loaded. Nothing is repeated that the schema already carries in more detail.

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, non-idempotent mutation with five parameters and no output schema, the definition covers the essential semantics: what is restored, what is not, and the audit-append behavior. Gaps remain around permissions and side effects on in-flight tasks, but the annotated safety profile and a fully documented schema carry most of the load.

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 explains each parameter, including the nuanced what_to_restore semantics and the -32062 refusal code. The description's restatement that mode ceiling and member roles are restored adds only marginal meaning over that schema text, so the baseline 3 applies.

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

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

States a concrete verb+resource ('Restore workspace state from a snapshot') and immediately narrows scope to what is actually reapplied (mode ceiling, member roles). It reads as the clear inverse of the sibling chap.control.snapshot tool, though it never names or contrasts that sibling explicitly.

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

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

The description gives no when-to-use guidance, no prerequisites, and no routing against alternatives such as chap.control.cancel, chap.control.supersede, or chap.control.set_mode_ceiling. The only chaining hint ('artefact id returned by chap.control.snapshot') lives in the schema, not the description.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds the refusal behavior for over-ceiling tasks, which is useful, but leaves the step-up authentication/error behavior and audit recording to the schema rather than surfacing it itself.

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

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

Two tight sentences with no waste, and the core effect (setting the ceiling) is front-loaded before the consequence clause. Every sentence earns its place.

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

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

Given a rich 100%-covered schema and annotations covering safety and idempotency, the description carries enough to call the tool correctly. It could note who is authorized or the audit implications, but the essentials are present.

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%, including enum values and the step-up auth error code, so the schema carries the parameter semantics. The description adds no parameter-level meaning beyond what the schema provides, which is the expected baseline when coverage is complete.

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

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

States a specific verb ('Set') and a well-defined resource ('highest operating mode tasks in this workspace may request'), and the refusal consequence clarifies scope. It does not, however, explicitly distinguish itself from control siblings like pause/resume/cancel, so sibling differentiation is left implicit.

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 only implied: an agent can infer you call this when you want to constrain the maximum mode, and that over-ceiling tasks are refused. There is no when-to-use vs. alternative guidance (e.g., relative to control.pause or workspace.set_profiles) and no stated prerequisites.

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

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

Adds substantial context beyond the annotations: it names the return value (snapshot artefact id), states that this id is the only valid target for rollback and that labels cannot be used to select snapshots, and discloses the precise scope of what a rollback actually restores. readOnlyHint=false with a tool that 'changes nothing' is consistent because an artefact is written, not workspace state mutated.

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 purpose, then return contract, then the rollback caveat. Nearly every sentence earns its place, though the label-versus-id point is partly a restatement of the schema's own description of label.

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

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

With no output schema, the description correctly supplies the return value and its downstream use. It also covers the crucial limitation that snapshots are a narrow safety net covering only mode ceiling and member roles, which is exactly the ambiguity that would otherwise cause an agent to over-trust rollback.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool meaning: it clarifies that label is human-facing only and that rollback selects by artefact id, which is the single most likely misuse of the label parameter. The include parameter's capture scope is left to the schema.

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

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

Specific verb (capture) plus resource (workspace state as an artefact), and it explicitly frames the tool against chap.control.rollback, which it names. An agent can distinguish this from siblings like chap.control.rollback or chap.audit.read 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?

States the triggering condition clearly: capture before a change you may want to undo. It also names the related tool (rollback) and the artefact-id contract that links them. It stops short of explicit when-not guidance, but the 'narrow safety net' caveat effectively bounds expectations.

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

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

Goes well beyond the destructiveHint=false/idempotent annotations: discloses that the original is superseded-and-linked rather than deleted, that review requirement is inherited from the original regardless of review_required, and the specific error code (-32063) for a paused assignee. Rich behavioral detail for a mutation.

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 purpose then behavior/edge cases. No filler, though the review-inheritance clause is dense and slightly overlaps the schema.

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

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

No output schema exists, but annotations cover the safety profile and the description covers the key mutation quirks (non-deletion, review inheritance, error code). Mode-ceiling (-32040) and idempotency are left to schema/annotations, 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?

Schema description coverage is 100% and the schema already documents the review inheritance rule and the not-paused assignee constraint. The description adds only the -32063 error code, so it sits at the baseline for a fully documented schema.

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

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

States a specific verb and resource ('Replace a task with a successor') and clarifies the outcome (original moves to superseded, stays linked). The supersede semantics distinguish it conceptually from chap.task.update/complete/cancel, though no sibling is named explicitly.

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

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

Explains what happens during the call but never says when to choose supersede over alternatives like chap.control.cancel, chap.task.update, or chap.task.route. No exclusions or prerequisites for invocation are given.

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

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

Annotations only carry the standard mutation flags (readOnly=false, destructive=false, idempotent=false). The description goes well beyond them, disclosing the authorization rule with its error code (-32011), the quorum-dependent completion semantics (approval may leave the review open under all_approve or quorum:N), and the schema adds the digest-mismatch refusal (-32074).

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

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

Three sentences, front-loaded with the core action, then authorization, then completion semantics and the alternative. No filler; every clause carries operational information.

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

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

For a mutation tool with no output schema, the description supplies what annotations cannot: caller eligibility, error codes, and the interaction between this decision and the review's rule. An agent has everything needed to invoke it correctly or route 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 100%, so all six parameters are documented in the schema itself (from, tags, comment, task_id, workspace, approved_artefact_digest, including the SHA-256 pattern and its binding/refusal behavior). The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (approve) and resource (the artefact under review), and pins the scope with 'as it stands', which distinguishes it from chap.decide.override (corrected version) and chap.decide.reject in the sibling 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?

Explicitly names who may call it (only the addressed reviewer, others refused with -32011) and names the alternative for the adjacent case ('Use chap.decide.override instead to accept a corrected version'). The when-to-use condition is fully spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety is covered. The description adds a real behavioral trait beyond that: the patch, rationale and tags are co-recorded so the audit log captures what changed and why, which explains the non-idempotent nature. It stops short of describing refusal conditions or what the caller receives back.

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

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

Two sentences, front-loaded with the action and mechanism (RFC 6902 JSON Patch) before the audit rationale. The trailing clause 'rather than only that the work was not accepted as written' is slightly wordy but justifies why the tool exists alongside reject.

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 10-parameter mutation tool, the description covers the core semantics (patch is applied, result is accepted, audit captures patch plus rationale) while the schema carries parameter detail and error codes (-32012, -32074) and annotations carry the safety profile. Only the return shape and idempotency implications are unaddressed.

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

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

Schema description coverage is 100%, so all ten parameters including diff, rationale, tags, policy_refs and approved_artefact_digest are already documented, and the description only echoes the patch/rationale/tags trio. Baseline 3 applies when the schema does the heavy lifting.

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 (correct/override) and resource (the artefact under review), and 'accept the result' makes clear this is a terminal decision rather than a comment. It implicitly differs from chap.decide.approve/reject by modifying content rather than just accepting or refusing it, but it never names those siblings to make the distinction explicit.

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

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

There is no explicit statement of when to choose this over chap.decide.approve or chap.decide.reject, which are the obvious alternatives in a 39-tool sibling set. The reader must infer from 'override with a correction' that this is the path when the draft is nearly right but needs edits.

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 give only the generic safety profile; the description adds real value by disclosing the state-transition semantics (task becomes 'declined', or returns to 'in_progress' with request_revision) and the reviewer-authorization constraint. It does not mention the -32074 digest-mismatch refusal, but that detail is carried by 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?

Three sentences, front-loaded with the action and its outcomes, then the authorization rule, then the alternative tool. Slightly dense in the middle clause ('which is the choice between ending the work and sending it back'), but every sentence earns its place.

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

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

For a mutation tool with no output schema, the description covers the action, the resulting state, who may invoke it, and the alternative tool. Remaining gaps (audit-entry recording, digest-mismatch behavior) are already handled in the fully covered schema, 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 description coverage is 100% and each parameter is already well documented, including request_revision and the digest pattern/error. The description's gloss on request_revision ('the choice between ending the work and sending it back') largely restates the schema rather than adding new syntax or format guidance, so baseline 3 applies.

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

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

States a specific verb+resource ('Reject the artefact under review') and immediately clarifies the two possible outcomes (declined vs. back to in_progress). It also explicitly distinguishes itself from the sibling chap.decide.override, so an agent can tell them apart without opening either schema.

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

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

Gives an authorization condition (only the addressed reviewer may decide) and explicitly routes the agent to chap.decide.override when the intent is to fix and accept rather than refuse. No guidance on adjacent alternatives like abstain or escalate, so it stops short of full when/when-not coverage.

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

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

Adds substantial context beyond the annotations: closing is final, further comments and votes are refused with error -32032, retries are idempotent and change nothing, and uncast votes are absent rather than abstentions. The specific error code and the abortion-vs-abstention semantics are exactly the kind of detail annotations cannot convey.

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

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

Four tight sentences, each carrying distinct information: what closing does, finality plus error code, retry safety, and tally semantics. The core action is front-loaded 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 mutation tool with idempotent/destructive annotations, the description covers finality, error behavior, idempotency, and vote tallying. There is no output schema, and the description notes the outcome is returned but does not characterize the returned outcome's shape, leaving 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?

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the deliberation_id cross-reference to chap.deliberate.open. The description adds no parameter-level syntax or format meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb (close) and resource (deliberation), plus the additional behavior that closing computes the outcome from votes cast under the deliberation's rule. This is distinguishable from siblings like chap.deliberate.open and chap.deliberate.vote without opening any schema.

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

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

Gives clear context for use: closing is final, and retrying on an already-closed deliberation is safe and returns the same outcome. It does not explicitly name alternatives (e.g., vote first, or use chap.deliberate.vote), so the routing guidance is implicit rather than spelled out.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent behavior; the description adds that comments are weightless in the outcome and admissible only before close, which is real semantic context. The refusal-after-close code lives in the schema rather than here, so it isn't fully self-contained.

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

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

Two tight sentences, front-loaded with the action and then the constraint. Every clause earns its place; nothing is repeated from the schema or annotations.

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 four-required-param mutation with no output schema, the description covers purpose, audience, timing, and effect, and the schema carries error codes and parameter detail. Only minor gaps (duplicate-comment behavior given non-idempotency) remain.

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 all four parameters are already documented with examples and the error code for a closed deliberation. The description adds no syntax or format detail beyond the schema, which is the baseline-3 case.

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

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

States a specific verb and resource ('Record a comment on an open deliberation') and immediately scopes it against the tally ('carry no weight in the outcome'), so an agent can distinguish it from chap.deliberate.vote and chap.deliberate.close without opening any schema.

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

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

Gives clear conditions: any participant, at any point before chap.deliberate.close. It implicitly separates this from voting (comments have no effect on outcomes), which is useful routing. It does not name an explicit alternative tool or a 'do not use when' case, so it falls short of 5.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the description's added value is the immutability contract: participant list, rule, weights and veto map are fixed at open, and no outcome exists until close. That is genuinely useful behavioral context beyond the annotations. It stops short of warning that a retried open creates a second deliberation, which matters given idempotentHint=false.

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 sentences, front-loaded with purpose then routing then return value then lifecycle constraint. Dense and nearly waste-free, though the rule enumeration appears twice in close proximity (description and schema) and 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?

For a nine-parameter, nested-object creation tool with no output schema, the description covers the return value (deliberation_id consumed by comment/vote/close), the immutability of terms, and the close-time outcome. Error codes live in the schema, so their absence here is acceptable; only the duplicate-on-retry risk is unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters, including the rule string, the veto map semantics and the integer-only weights constraint. The description restates the rule vocabulary and the fixed-at-open behavior but adds no format or syntax detail the schema lacks. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Open a group decision among several participants') and immediately scopes it with the voting-rule vocabulary (any_one_approves, quorum:N, weighted_vote:T, etc.). It explicitly distinguishes itself from the sibling chap.review.request, so an agent can route without opening either schema.

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

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

Names the condition for use ('where several people must weigh in on one question') and names the alternative plus its differing condition ('chap.review.request is the tool for judging one participant's output'). It also clarifies the lifecycle boundary with chap.deliberate.close, so the agent knows this tool does not produce an outcome.

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

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

Goes well beyond annotations by disclosing a concrete failure mode with its JSON-RPC error code (-32031 on a second vote), the immutability of a cast vote, and the non-obvious semantic that an abstention withholds approval under all_approve/quorum:N. These are behavioral consequences an agent could not derive from readOnlyHint/idempotentHint alone.

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

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

Three sentences, zero filler, front-loaded with the action and the vote values, then the immutability rule and the abstention consequence. Every sentence changes how an agent would call or interpret the 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 mutation tool with no output schema, the description covers the error behavior, the one-vote rule, the abstain edge case, and where the tally actually happens, plus the schema covers veto/weight semantics. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so every parameter including vote, weight, veto_invoked and deliberation_id is already documented in the schema. The description restates the abstain semantics that the schema's vote field already carries, adding no syntax or meaning beyond it; baseline 3 applies.

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

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

States a specific verb and resource ('Cast a yea, nay or abstain in an open deliberation') and scopes it to an *open* deliberation, which distinguishes it from siblings like chap.deliberate.close and chap.deliberate.comment. An agent can tell immediately what this does and what it is not.

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

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

Explains the operative condition (deliberation must be open) and the constraint that each participant votes once and cannot revise, and routes tally interpretation to a named sibling, chap.deliberate.close. It doesn't explicitly say when *not* to use it (e.g. to change a vote, comment, or abstain via chap.abstain.declare), so it falls short of full when/when-not guidance.

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

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

Annotations declare readOnlyHint=false but destructiveHint=false, which is ambiguous on its own; the description resolves it by disclosing that a route_decision artefact is written while the task does not move. It also surfaces the default policy thresholds (critical, or high with confidence below 0.6), which the agent cannot infer from the schema. It stops short of describing permissions or response payload, so it is not exhaustive.

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

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

Three sentences, each load-bearing: what it does, what it deliberately does not do plus the handoff, and the default policy. The non-action constraint is front-loaded right after the 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?

With no output schema, the description carries the return burden and does so adequately by stating it reports the escalate/no-escalate answer and the target. It leaves the precise response shape and whether the chain contains reasoning for the decision unstated, which is a minor gap for a tool whose main output is a judgment.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (including the -32516 refusal condition on default_escalation_target). The description adds policy context but no additional parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb (evaluate) and resource (a task's routing hints against the escalation policy) with the exact question it answers: whether to escalate and to whom. It also names the sibling chap.escalate.raise, so an agent can separate this evaluator from the actor without opening either schema.

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

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

Explicitly scopes when to use it ('It decides only... the task does not move') and directs the agent to the alternative when action is wanted ('act on the answer with chap.escalate.raise'). This is the when/when-not/alternative pattern in compact form.

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 only the safety profile (not read-only, not idempotent, not destructive); the description adds real behavior beyond them: the original moves to 'escalated' and is linked to a successor, the successor's input is empty unless supplied, mode and review requirements are inherited, and specific error codes (-32063 paused assignee, -32040 mode above ceiling) are disclosed.

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

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

Front-loaded with purpose and alternatives, then preconditions and error behavior. Dense and mostly earning its place, though the empty-input and mode-ceiling points are repeated verbatim in the schema, which is mild 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?

For a mutation tool with a nested successor object and no output schema, it covers state transitions, inheritance rules, input defaults, preconditions and error codes. 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 100%, so the baseline is 3, but the description adds semantics the schema does not carry, notably that the successor 'requires review when the original did, or when it is a trial task under modes/1.0'. Some mode/input notes merely restate the schema, keeping it short of 5.

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 ('hand a task upwards') plus the distinguishing condition ('where the current holder can act but should not decide alone'), and names two siblings it is not. An agent can separate it from chap.handoff.propose and chap.control.supersede without reading either schema.

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

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

Explicitly routes between alternatives: sideways passing goes to chap.handoff.propose, outright replacement to chap.control.supersede. It also states the negative precondition that completed, cancelled or superseded tasks cannot be escalated.

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?

Despite annotations already covering safety (readOnlyHint=false, destructiveHint=false), the description adds vital behavioral details not in annotations: the irreversible resolution of the proposal (a later accept/decline returns error -32051), the restriction that a paused participant cannot accept (error -32063), and the exact effect of omitting accepted_task_ids. This is far beyond the annotation set.

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

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

The description is four tight sentences with no waste, front-loading the core action and effect, then covering the optional parameter and key error conditions. Every sentence earns its place.

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

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

Given the tool's complexity (state-changing, permission-sensitive, with error codes), the description provides complete context: it explains responsibility transfer, optional parameter behavior, error conditions for repeated actions and paused participants. No output schema exists, but the description covers what an agent needs 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 100%, so the schema already documents all parameters thoroughly. The description only adds meaning for accepted_task_ids by clarifying that omitting it accepts all tasks. For the other parameters, the description adds no new semantic information beyond the schema.

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

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

The description states a specific verb+resource ('Accept a proposed handoff') and clarifies the crucial effect: related tasks are reassigned to the accepting participant, making responsibility actually move. This distinguishes it clearly from chap.handoff.decline and chap.handoff.propose.

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 exactly when to use it: to accept a proposed handoff. It also specifies the behavior when accepted_task_ids is omitted (accepts all). Although it doesn't explicitly name alternatives, the sibling tool chap.handoff.decline and the context of a proposal make the choice obvious.

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

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

Annotations already declare this as a non-read-only, non-destructive, non-idempotent write. The description adds genuinely new behavioral context: nothing is reassigned on decline, the proposal is resolved permanently, repeat calls fail with error -32051, and the reason is persisted for the proposer to reroute. It stops short of naming required permissions or who is allowed to decline.

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 short sentences with the core action front-loaded, followed by sibling contrast, terminality, and reason semantics in a logical order. Slightly redundant with schema text on the reason, but every sentence carries distinct information.

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

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

For a five-parameter mutation with no output schema, the description covers the action, its effect on tasks, the alternative tool, and the error behavior on retry. The only gap is authorization context—who may decline—which an agent might want before invoking.

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 all five parameters including reason and suggested_target are already documented in the schema. The description's mention of the reason ('recorded so the proposer can route the work elsewhere') largely restates the schema text rather than adding format or constraint detail, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Decline a proposed handoff') and immediately contrasts the outcome with chap.handoff.accept ('The tasks stay with the proposer and nothing is reassigned'), so an agent can distinguish the two siblings without opening either schema.

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

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

Explicitly routes between the two options by naming the alternative it is not, and goes further to describe the terminal condition: a later accept or decline returns -32051, and retrying requires a fresh proposal. It gives the agent both the selection rule and the failure mode.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive mutation, so the safety profile is covered. The description restates the proposer-assignment precondition, but that same detail also appears in the schema's tasks description, so it adds little new behavioral context and says nothing about what a successful proposal produces or how it is resolved.

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

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

Two sentences with the core purpose front-loaded and no filler. The second sentence partially duplicates the constraint already in the tasks schema description, which is a minor redundancy rather than a structural flaw.

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 six-parameter mutation with no output schema and no annotation coverage of return behavior, the description establishes the eligibility precondition but omits what the proposal returns and how it proceeds. It is adequate to place the call correctly but not complete for the full lifecycle.

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 (workspace, from, to, tasks, summary, context_links) is already documented, including error codes -32052 and -32050. The description adds only the cross-cutting constraint that all tasks be assigned to the proposer, which is the baseline expectation when the schema does the heavy lifting.

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

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

The description gives a specific verb and resource ('Propose handing one or more tasks to another participant or a group') and names the follow-on context needed to pick them up. It clearly separates the tool from siblings like chap.handoff.accept and chap.handoff.decline, though it does not name them explicitly.

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

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

It supplies one real eligibility rule — tasks must be currently assigned to the proposer — which tells the agent when the call will succeed. However, it gives no explicit guidance on when to propose versus accept/decline a handoff, or on the proposal lifecycle, leaving usage largely inferable from the tool name.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=false). The description adds one behavioral fact outside those annotations — that participant type governs review eligibility — but it is a thinner restatement of the 'type' schema description and omits permissions, idempotency semantics, and failure behavior.

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

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

Two sentences with essentially no padding, and the core action is front-loaded. The second sentence is a slightly awkward clause but still earns its place by tying the type enum to an outcome.

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 output schema, the rich annotations and 100%-covered schema carry most of the burden, so the description is adequate. It nevertheless leaves out authorization requirements, what happens on duplicate joins (despite idempotentHint=true), and the significance of the 'role' 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 100%, so the schema already explains every parameter, including the enum values, the 'from' URI format, and the 'admin' role semantics. The description merely enumerates the type values with less precision than the schema, adding no syntax or format detail beyond it; baseline 3 applies.

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

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

The description gives a specific verb and resource ('Add a participant to a workspace'), which cleanly distinguishes it from admissions siblings like chap.participant.leave or chap.participant.revoke_key. It stops short of naming an alternative when one is genuinely confusing, so it lands at a clear-but-undifferentiated 4.

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 only implied by the verb 'Add a participant to a workspace'; there is no explicit statement of when to use this versus chap.participant.leave, nor any prerequisite such as required permissions or role in the workspace. The second sentence discusses the effect of the type field rather than routing guidance, so it reads as minimum-viable.

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 mark it destructive and idempotent, but the description adds substantial non-obvious behavior: audit entries persist, past signatures remain valid, task assignment and reviewer privileges are lost, and rejoining requires a fresh join. This is exactly the side-effect disclosure an agent needs before a destructive call and goes well beyond the annotation set.

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: the action is front-loaded, then the persistence guarantee, then the operational consequences. Every sentence contributes a distinct fact and none is padding or restatement of the title.

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

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

With no output schema, the description still covers what matters for a destructive membership change: irreversibility semantics, retained audit data, lost privileges, and the rejoin path. Nothing an agent needs to call this safely is missing.

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

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

Schema description coverage is 100% with two well-documented parameters (participant URI and workspace id), so the schema carries parameter meaning. The description adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Remove a participant from a workspace') and immediately differentiates the semantic effect from the inverse sibling by naming chap.participant.join as the return path. An agent can distinguish this from revoke_key/rotate_key purely on scope of membership.

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 what 'leaving' means operationally and explicitly forecloses one misuse case ('leaving is not a way to withdraw a decision'), which is genuine when-not guidance. It stops short of routing the agent between this and adjacent tools like revoke_key or rotate_key, so it is clear but not exhaustive.

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 annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the description's job is to add context beyond that. It does: the downstream effect ('signatures presented with it are refused from then on') and the admin authorization requirement are both useful behavioral facts not present in the annotations. It does not address the non-idempotent hint (e.g. what happens on a repeat revoke), leaving one annotation-implied behavior unexplained.

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

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

Three short sentences, front-loaded with the action, followed by the effect and the authorization caveat. No filler, no repetition of the schema, and every sentence carries distinct information.

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

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

For a destructive, non-idempotent mutation with no output schema, the description covers purpose, consequence and authorization, which is most of what an agent needs. The remaining gap is the non-idempotency and reversibility story (can a revocation be undone? what does a second revoke return?), which the annotations hint at but the description never resolves.

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

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

Schema description coverage is 100% and every parameter (kid, from, workspace, target_uri, reason) is already documented in the schema, including error codes -32071 and -32011. The description's mention of the admin role for another participant's key is the only parameter-relevant addition, and even that is duplicated in the target_uri schema text, so the baseline 3 applies.

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

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

States a specific verb and resource ('Revoke a signing key') plus a concrete motivating scenario ('after a device is lost'). It is clear what the tool does, though it never names the obvious sibling alternative chap.participant.rotate_key, so an agent must infer the rotate-vs-revoke distinction on its own.

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 a clear use context ('after a device is lost') and a hard precondition ('Revoking another participant's key requires the admin role'), which tells the agent when the call is permitted. It stops short of explicit when-not guidance or naming the rotate_key alternative, so it is context-rich but not fully routing.

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, but the description adds real context the annotations cannot: the old key is retained in key history with a valid_until timestamp so prior signatures still verify. That materially explains why destructiveHint=false holds. The conditional signature requirement is only covered inside the new_jwk parameter, not surfaced as behavioral guidance.

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

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

Two tight sentences with the operation front-loaded and the retention consequence second. Every clause earns its place and nothing is padded.

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

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

For a four-param mutation with no output schema but fully described inputs and error codes, the description covers what happens to the retired key and the replacement. It could say more about permissions/authentication needed to rotate another participant's key, which is the main 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 100%, so old_kid, new_jwk, from, and workspace are already well documented, including error codes -32071/-32072 and the conditional request-signing rule. The description adds no per-parameter detail beyond what the schema provides, which is the expected baseline when the schema does the heavy lifting.

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

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

Specific verb+resource: 'Retire a participant's signing key and register its replacement' names the retire-and-replace operation precisely, and the second sentence clarifies the retained-history semantics. It never names the close sibling chap.participant.revoke_key, so the rotate-vs-revoke distinction is left for the agent to infer.

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

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

Usage is implied by the replace semantics (rotate when you have a replacement key), and the retained-history note hints at why one would rotate rather than revoke. There is no explicit when-to-use/when-not guidance and no mention of the alternative chap.participant.revoke_key, which shares the same key-management surface.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, so the agent knows this mutates state, and the description usefully explains what is written (a route_decision artefact carrying the provenance rule). It adds context beyond the annotations, though it omits the refusal condition present only in the nested 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?

Two tight sentences, front-loaded with the action and its outcome values, with no filler. The inline enumeration 'skip, spot_check or full' is slightly awkward but earns its place by naming the decision domain.

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

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

With no output schema, the description does explain what the call produces (a route_decision artefact and the rule behind it), and the rich input schema covers inputs and the refusal path. The main gap is a lack of guidance on prerequisites such as required routing hints at the task level.

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%, including detailed notes on artefact_routing_hints merge behavior and the -32514 refusal, so the schema already carries the parameter semantics. The description contributes no additional parameter detail, making the baseline 3 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 names a specific decision ('how much review a task warrants') and enumerates the three possible outcomes (skip, spot_check, full), plus states the side effect of recording a route_decision artefact. That is far more specific than its siblings, though it does not explicitly differentiate itself from nearby routing tools like chap.task.route.

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 says the decision comes 'from its routing hints,' which hints at the input context, but there is no when-to-use guidance, no exclusions, and no named alternative. An agent cannot tell from this text when to call chap.review.depth versus chap.task.route or chap.review.request.

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

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

Goes well beyond the annotations by disclosing that the rule is frozen once the review opens and a conflicting later request is refused with -32014, that a different artefact on an open review is likewise refused, that only workspace members can actually decide, and that the deadline is recorded but not acted upon by the coordinator. These are exactly the behavioral traits (idempotency-by-add, immutability, error codes) an agent needs before calling.

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

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

Three sentences, front-loaded with the action and its recipients, followed by the follow-up path and the re-request semantics. No filler, no restatement of the title, and each sentence carries distinct information.

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

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

For a 7-parameter mutation tool with no output schema, the description covers the workflow, the immutability rules, and the failure codes (-32014) adequately. It is silent on what the call returns (e.g. a review identifier) and on permission prerequisites for the caller supplying `from`, which is a minor residual gap.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds cross-parameter meaning the schema silos cannot: the same-artefact/same-rule repeat semantics for `to` and `artefact`, and the fact that omitting `rule` on a later request leaves it untouched. It does not add new guidance on `from`, `task_id`, or `workspace` beyond what the schema already says.

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

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

States a specific verb+resource ("Open a review on a task") and the scoping object ("address it to one or more reviewers"). It also names the downstream decision tools, so an agent can place this tool in the workflow relative to chap.decide.approve/reject/override and chap.abstain.declare without opening any schema.

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

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

The description routes the agent clearly: this opens the review, the addressed reviewers then call chap.decide.* or chap.abstain.declare, and re-requesting with the same artefact widens the reviewer set. It does not, however, state when *not* to use it (e.g. against a draft that has no task yet, or instead of chap.task.route), so exclusions are absent.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds real behavioural value beyond them by disclosing the state transition (review_requested vs completed) and the fact that the output becomes the artefact under review. It does not address re-submission or overwrite behaviour for an already-completed task.

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 action and then the branch behaviour. Every sentence earns its place and nothing is repeated from the schema.

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

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

With 6 params (3 required), a nested routing_hints object, 100% schema coverage, no output schema and annotations covering safety, the description supplies the missing piece: what state the task ends in. It omits only the return payload and idempotency-on-retry details, which are minor given the rest of the coverage.

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

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

Schema description coverage is 100% and the parameter docs are unusually thorough (confidence canonicalisation, routing_hints semantics, error -32602). The description itself adds no parameter-level detail, so the schema does all the work — 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+resource ('Submit a task's output') and immediately disambiguates the two execution paths, so an agent can tell it apart from chap.review.request, chap.task.update and chap.decide.* without reading any schema. The branch description makes the tool's scope unambiguous.

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

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

Gives clear context: tasks needing review are held as the artefact under review and move to review_requested, while all other tasks complete immediately. That tells the agent when this call is the right one. It stops short of naming an explicit alternative or a when-not condition (e.g. 'do not call this to request a review directly').

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 carry only the basic safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), and the description adds real behavioral detail beyond them: retry semantics with and without idempotency_key, the difference between review_required and normal completion, and the paused-assignee refusal. Crucially, the non-idempotent default implied by the annotations is consistent with the described behavior that a keyless repeat creates a second task.

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 definition of a task before the behavioral fine print. Nearly every clause earns its place (review semantics, retry safety, refusal condition), with only mild redundancy against the schema text.

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 10-parameter creation tool with no output schema, the description supplies what the schema cannot: the return value (task_id that the lifecycle carries) and the failure conditions (paused assignee). Combined with the fully documented schema and safety annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters, including routing_hints, idempotency_key, and review_required. The description largely restates that structured content (idempotency, review_required, paused assignee) rather than adding syntax or format meaning the schema lacks, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create a task') and immediately defines the resource ('a unit of work assigned to one participant'), which distinguishes it from lifecycle siblings like chap.task.update and chap.task.complete. An agent knows exactly what this produces and what the task_id 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?

Gives clear context for key decisions: when to set review_required (completion depends on a reviewer, not the assignee) and when idempotency_key matters (safe retries). It also states a precondition (assigning to a paused member is refused). It stops short of explicitly naming when to use this vs. the sibling update/complete tools, but the lifecycle framing implies 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?

Annotations only cover safety hints (write, non-idempotent, non-destructive). The description adds substantial behavior: the route_decision artefact it writes, the default first-member-not-paused policy, and the exact refusal codes -32510 and -32063 with their triggering conditions.

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

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

Front-loaded purpose followed by usage rationale then behavioral detail in a logical order. The second sentence is dense with error codes but each clause carries information the agent needs; minimal waste.

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

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

With no output schema, the description correctly explains what is produced (the route_decision artefact) and all failure modes. It could state the response shape or ordering of candidate evaluation more explicitly, but it is largely sufficient for a 4-required-param mutation tool.

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

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

Schema description coverage is 100%, so from/to/task_id/workspace/candidates are already documented. The description largely restates the candidate-selection rules already present in the schema, adding little param-level syntax beyond it. Baseline 3 is appropriate.

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

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

Specific verb (choose/reassign) plus resource (task assignee) with clear scope. It explicitly distinguishes itself from chap.task.create by naming the route_decision artefact that direct assignee-setting does not capture.

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

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

States precisely when to use it ('where the choice itself belongs on the record') and contrasts that with the alternative of setting assignee directly on chap.task.create. The selection criterion (auditable routing decision) is spelled out rather than left to inference.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real behavioral context on top: illegal transitions are refused with -32602, 'review_requested' is not an accepted target, and review_required tasks must go through chap.task.complete. It does not describe what happens to task history or whether the change is reversible.

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

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

Two sentences, no filler, with the core operation stated first and the constraints immediately after. Every clause carries information an agent needs before invoking.

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 non-idempotent mutation with annotations already declaring safety and no output schema, the description supplies the critical gating rules (legal transitions, the review carve-out) and the error code. Adequate, though a note on what a successful call changes or returns would round it out.

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 five parameters, including the state enum and its transition constraints. The description largely restates the schema's state guidance and adds nothing about 'from', 'workspace', or 'progress_note', so the baseline of 3 applies.

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

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

States a specific verb and resource ('Move a task to a new state') and separates itself from the adjacent siblings by naming chap.task.complete and chap.review.request as the paths for review-related outcomes. The scope (state transition only) is unambiguous, though it does not distinguish itself from chap.task.route or chap.control.cancel.

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

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

Gives an explicit precondition ('Only the transitions in the specification's lifecycle table are accepted') and an explicit exclusion with a named alternative ('a task that requires review cannot be completed here' → use chap.task.complete). It stops short of stating when this tool should be preferred over other task-mutating siblings such as chap.task.route.

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 only that this is a non-idempotent mutation; the description goes well beyond that by disclosing the exact JSON-RPC error codes -32022, -32020 and -32021 and their triggers. It also explains the non-obvious side effect that a late answer has already had the ask-time default applied, which materially changes what the caller should do.

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

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

Three sentences, all front-loaded with the action first, then validation semantics, then the deadline edge case. No filler and nothing repeated from the schema.

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 six-parameter mutation with no output schema, the description covers success preconditions, all three failure modes and the deadline default, which is what an agent most needs. It omits what happens on success (e.g. whether the asker is notified) and whether 'from' must be a valid workspace participant, but these are secondary.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the answer must name an option id when the whisper carried options, and any other value is refused with -32022. That enforcement rule is not stated in the schema and clarifies the interaction between answer and answer_option.

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

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

The first sentence states a specific verb and resource ('Answer an open whisper'), which cleanly distinguishes it from the sibling chap.whisper.ask that creates whispers. An agent can identify the operation 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?

It states the precondition ('open whisper') and three explicit refusal conditions (already answered, past deadline, invalid option), which tells the agent when the call will not take effect. It stops short of naming chap.whisper.ask or other siblings as the alternative path, so it is clear context rather than 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?

Annotations declare a non-read-only, non-idempotent, non-destructive operation, and the description adds genuine behavioural context: the deadline lapse semantics and the guarantee that a task is never blocked waiting on a reply. It does not cover permissions or what is returned, so it stops short of a 5.

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

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

Two sentences, zero waste, with the core action front-loaded and the lapse consequence immediately following. Every clause earns its place.

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

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

There is no output schema, and the description never says what a successful call returns (e.g. a whisper id needed for chap.whisper.answer). For an otherwise well-scoped 9-parameter creation tool that gap is the main omission, but the required/default/lapse contract is fully covered.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the deadline/default mechanics already documented in deadline_ms and default_if_lapsed but adds no format, bounds, or option-id semantics beyond the schema.

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

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

The description states a specific verb and resource ('put one question to one or more participants') with the defining scope of a whisper: a deadline plus a default. It is clearly distinct from siblings like chap.task.create or chap.review.request, though it does not name a sibling explicitly to sharpen the boundary.

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 explains the lapse behaviour ('if the deadline passes unanswered the default applies'), which implies this is for non-blocking asynchronous questions, but gives no explicit when-to-use guidance against alternatives such as chap.escalate.raise or chap.review.request. Usage is inferable, not stated.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds that the returned workspace id is reused by all later calls, but says nothing about failure modes (e.g., duplicate workspace id), auth requirements, or the effect of profile/mode settings, much of which the schema carries instead.

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

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

Two tight sentences with zero filler, front-loaded on the action and resource, with the most operationally important fact (the returned id that later calls depend on) placed at the end as a takeaway.

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

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

With no output schema, the description usefully states the return value (workspace id) and defines what the created entity is. For a 4-parameter, mostly-optional creation tool with fully documented schema fields, this is close to sufficient; only existence/conflict behavior and any auth preconditions are unaddressed.

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

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

Schema description coverage is 100% and the parameter docs are unusually rich (mode semantics, profile side effects, mode_ceiling refusal codes), so the schema does the heavy lifting. The description adds no parameter-level detail beyond the schema, which makes the baseline 3 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?

Uses a specific verb+resource ('Create a workspace') and defines the resource concretely as the container for participants, tasks and audit log of one piece of collaborative work. The create action is clearly distinguishable from siblings like chap.workspace.describe or chap.workspace.set_profiles, though it never names or contrasts them explicitly.

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

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

Usage is only implied: by calling the workspace the container for participants/tasks and stating the id is carried by every later call, the description hints that this is a prerequisite first step. There is no explicit when-to-use statement, no guidance on what to do if the workspace already exists, and no named alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the reported fields but discloses nothing further about auth requirements or limits, which is adequate but not 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?

A single efficient sentence with the verb and reported fields front-loaded and zero waste.

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

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

With no output schema, the description usefully enumerates the returned state fields. For a one-parameter read-only tool whose safety profile is already annotated, this covers what an agent needs to invoke it correctly.

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

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

There is a single 'workspace' parameter with 100% schema description coverage, so the schema already documents it. The description adds no format or identifier syntax beyond the schema, which is the baseline case.

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 ('Report') and resource ('workspace'), and enumerates the state it returns (members, profiles, audit length, task/override counts). This cleanly distinguishes it from sibling mutations like chap.workspace.create and chap.workspace.set_profiles.

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

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

Usage is implied by 'current state' phrasing but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., chap.audit.read for audit details). The agent must infer the 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 declare destructiveHint=true, readOnlyHint=false and idempotentHint=false; the description adds concrete consequence detail beyond them: the list is not merged, absent profiles are dropped, and enabling audit-scitt/1.0 strands earlier entries permanently outside the chain. That names what gets destroyed and the downstream verification impact (chap.audit.verify_chain reporting not_evaluated).

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

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

Three sentences, all load-bearing: the operation, the non-merge semantics, the irreversibility consequence, and the safer alternative. Front-loaded with the core behavior and no restatement of the title.

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 destructive mutation with no output schema, the description covers operation semantics, irreversible consequences, and the preferred alternative path. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% and the 'profiles' property description already covers the complete-set/replace meaning plus the audit-scitt stranding caveat, so the description is largely reinforcing structured data. Baseline 3 applies; the extra edge-case detail ('starts the chain from that point', verify_chain reports not_evaluated) is useful but duplicative of the schema text.

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: 'Replace the whole set of profiles enabled on a workspace.' The replace (not merge) semantics are stated up front, which separates it from read/describe siblings and from any additive profile tool. An agent can distinguish it from chap.workspace.create 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 an explicit alternative and the condition that selects it: 'Prefer setting profiles at chap.workspace.create, where no entries exist yet to strand.' It also implies when not to use it (workspaces that already have audit entries), which is exactly the kind of routing guidance an agent needs.

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