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

readOnlyHint=false is consistent with gates that may execute builds and tests, and the description reinforces this by noting a docs task can skip the build and test gates. It does not state what gets executed, whether failures abort or are reported in-band, or what side effects occur in the workspace, so important behavior for a non-read-only tool is left implicit.

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

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

Three dense sentences with the core action front-loaded and the parameter modes packed into a single compact block; the parenthetical example earns its place. Slightly terse for the amount of conditional logic it encodes, but nothing is wasted.

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

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

There is no output schema, yet 'return a compact JSON report' is never elaborated: the agent cannot tell what the report contains, whether pass/fail is signaled in the report or via an error, or how gate definitions relate to results. For a two-parameter tool with no annotations beyond readOnlyHint=false, that return-value gap is the main missing piece.

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

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

Schema coverage is 0%, so the description carries the full burden and does so for both parameters: 'checks' is defined by its default behavior (omit it and every gate runs) and 'task' is defined both semantically (only that task's profile gates) and syntactically (task=<id>). The only gap is what valid gate names look like beyond the pointer to taskgate.toml.

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?

A specific verb plus resource ('Run quality gates and return a compact JSON report') with extra scope detail: gate names come from [quality] in taskgate.toml and a built-in 'tasks' gate exists. It does not, however, distinguish itself from the sibling task_validate, which sounds like a close neighbor, so an agent must infer 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?

The description explains the alternate modes ('without checks every gate runs; with task=<id> only that task's profile gates run') and gives a concrete example (a docs task can skip build and test gates). But this is parameter-selection guidance rather than when-to-use-this-tool guidance; it never says when not to run quality_check or when task_validate is the better call.

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

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

Annotations only declare readOnlyHint=false, so the description carries the behavioral burden and does so well: auto-assigned subtask ids in the form <parent>.<n>, inherited phase/default profile, the constraint that a parent cannot close while subtasks are open, and rejection of duplicate ids or closed phases. It also discloses the authorization requirement (only 'planners' identities) and that 'by' must be passed explicitly.

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?

Core purpose and the subtask mode are front-loaded, and the parenthetical clauses each carry real constraints rather than filler. It is dense — a single long paragraph — but nearly 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 an 11-parameter mutation tool with no output schema and only a readOnly hint, the description covers modes, inheritance, and authorization but omits the semantics of several required or structural parameters (verification_cmd, depends, spec, owner, status default). Adequate to call correctly in the common case, incomplete for the full schema.

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

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

Schema description coverage is 0%, so the description must explain all 11 parameters, and it only meaningfully covers parent, id, profile, and by (plus implied status). Required fields like verification_cmd, and params like depends, spec, owner, and phase, are never explained, leaving a substantial gap.

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

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

States a specific verb and resource ('Add a draft/planned task') and immediately names the two modes: standalone task or subtask via 'parent'. The add-vs-update-vs-move split against siblings is unambiguous from the verb alone.

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

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

Gives clear conditions for the subtask path ('with parent', one level, parent must be in_progress before a subtask can start) and rejection rules (duplicate ids, closed phases). It stops short of naming sibling alternatives such as task_update for modifying an existing task, 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 only give readOnlyHint=false, so the description carries the real burden and does well: it discloses the state transition, the fields mutated (owner, started), and the gating preconditions that cause refusal. It does not explain what bypassing the gate does, which leaves the destructive/privileged path only partly described.

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

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

Two dense sentences, front-loaded with the action and state transition, followed immediately by the failure conditions. 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 no output schema, the description covers the essential semantics: what changes, what gates apply, and when the call fails. The unexplained 'force' escape hatch is the remaining gap an agent would need.

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

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

Schema coverage is 0% and none of the three parameters are explained. 'by' and 'force' are never mentioned; 'sets owner' only hints at 'by', and 'force' — presumably a gate bypass — is completely undocumented despite being the highest-risk parameter.

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

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

States a specific verb (claim), a specific resource (planned task), and the resulting state transition (-> in_progress, sets owner and started), which differentiates it from the generic task_update and the read-only task_next/task_list. It stops short of naming an alternative sibling explicitly, so it lands just below a 5.

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

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

Clearly states when the call is refused: every earlier task must be done/cancelled (order and phase gate) and dependencies must be done. That is strong 'when not to use' coverage, but it never contrasts the tool with task_update or task_next, so the alternative-selection guidance is missing.

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 readOnlyHint=false: it discloses that set replaces the whole set, that [] clears dependencies, that referenced ids must exist and precede the task, and that the caller must be a planner. It doesn't say what happens when validation fails (does the whole call fail, or partial apply?) or how set/add/remove interact when combined.

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

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

Two dense sentences with the operation and the three modes front-loaded, followed by prerequisites and authorization. No filler, no restating the tool name.

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

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

For a 5-parameter mutation with an empty schema and no output schema, it covers the essential preconditions (existence, ordering, role) and mutation semantics. Remaining gaps are the meaning of the required 'by' and the precedence when set and add are supplied together.

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

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

Schema coverage is 0%, so the description must carry all semantics; it explains set/add/remove well, including the '[] clears' edge case, but leaves 'by' (required) completely undefined and 'id' only inferred from context. Two of five parameters, including one required, remain unclear.

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?

Names a specific verb (change dependencies) on a specific resource (a draft/planned task) and enumerates the three mutation modes (set/add/remove). The scope restriction to draft/planned tasks and the pointer to task_move clearly separate it from task_update and task_move.

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

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

Explicitly states the ordering prerequisite for every dependency ('use task_move first') and the authorization constraint ('Planners only'). It implies rather than states the negative case (non-draft tasks), and does not name an alternative for changing dependencies on already-scheduled 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?

The readOnlyHint annotation already tells the agent this is a safe read, so the description carries a reduced burden and does not contradict it. Beyond that it adds almost nothing: no ordering, no pagination, no indication of whether all tasks are returned when the filter is omitted, and no note on result volume.

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

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

One short sentence, front-loaded with the verb and resource, with the qualifier in parentheses. Nothing is redundant, though the extreme terseness leaves no room for the context a list operation needs.

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

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

There is no output schema, so the description is the only place an agent could learn what a result entry looks like, whether results are paginated, or how they are ordered. For a listing tool those omissions are material, and the description addresses none of them.

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

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

Schema coverage is 0%, so the description must compensate for the single parameter. Calling it an "optional status filter" usefully establishes optionality and that status narrows rather than targets the result, but it never states the default behavior when omitted (presumably all statuses) or that the enum accepts only workflow 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?

States a specific verb ("List") and resource ("tasks") with the scope qualifier "optional status filter." An agent immediately understands this is the enumeration tool. It does not, however, distinguish itself from siblings like task_next, task_sort, or task_render, which also surface task collections.

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 parenthetical hints that filtering by status is permitted but gives no guidance on when to prefer this over task_next or task_sort. There is no statement of when to use it, when not to, or how it relates to any sibling.

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

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

Annotations only declare readOnlyHint=false, so the description carries most of the behavioral load and does so well: it discloses eligibility constraints (draft/planned only), phase ordering invariant, an authorization requirement (planners only), and a mutual-exclusivity rule. It omits failure behavior and whether the move 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?

Three tight sentences, each carrying a distinct rule (what it does, target constraints, caller/argument constraints). The core action is front-loaded before the guardrails.

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 only a readOnlyHint, no output schema, and 0% schema coverage, the description covers behavior and eligibility well but leaves the required `by` parameter and the return/error behavior undefined. An agent can attempt the call but may guess wrong on `by`.

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

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

Schema coverage is 0% across 4 parameters, so the description must compensate. It explains before/after semantics and their exclusivity, and id is inferable as the task being moved, but the required parameter `by` is never explained anywhere — a significant gap for a mandatory argument.

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: changing execution order by placing a draft/planned task directly before or after another. This is clearly distinct from siblings like task_sort (bulk ordering) and task_update (field edits). It stops short of naming those siblings explicitly, so no credit for direct differentiation.

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?

"Never in front of a task that is in flight or done, and phases stay ascending" gives explicit when-not conditions, and "Planners only; pass exactly one of before/after" states a prerequisite and a mutual-exclusivity rule. It's clear context but doesn't route the agent to an alternative tool when the target is in flight/done.

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

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

The readOnlyHint annotation already establishes this is a safe read. The description adds genuine behavioral context by disclosing the selection logic (planned status, dependencies satisfied, phase gate met), but says nothing about what is returned when no task qualifies, whether results are per-owner, or whether selection is deterministic.

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

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

A single front-loaded sentence with no wasted words, putting the core purpose before the qualifying criteria. It is dense but efficient, with only mild opacity in jargon like 'phase gate'.

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

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

For a simple single-task read with one optional parameter and no output schema, the description covers selection logic but omits the empty-result behavior and the meaning of the owner parameter. These are the two gaps an agent would need in order to call and interpret it confidently.

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

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

There is one optional 'owner' parameter with 0% schema description coverage, so the description must carry its meaning, and it never mentions owner or scoping. An agent cannot tell from this text whether 'owner' filters the queue or how it interacts with the selection criteria.

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 verb 'Show' plus the precise resource 'the one task that may start now' makes it clear this returns a single ready task rather than a list, which distinguishes it from task_list. The selection criteria (queue head, planned, dependencies met, phase gate met) sharpen the purpose, 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?

Usage is implicitly conveyed by 'may start now', which signals this is the tool for picking the next actionable task. However, it names no alternative (task_list, task_claim, task_render) and gives no exclusion or prerequisite guidance, so an agent must infer when to prefer 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 declare readOnlyHint=false; the description adds real behavioral context: mutation of review profile, that profiles come from taskgate.toml, the started-task restriction, and the planner permission requirement. It doesn't describe the return or error behavior, but the added context is substantial.

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 scope, followed by constraints and the parameter hint. 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 no output schema and 0% schema coverage, the description covers behavior and constraints well but omits what 'id' and 'by' mean, leaving an agent to infer them. Adequate but with a real 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 0%, so the description must carry all parameter meaning. It explains 'name' (profile defined in taskgate.toml) and 'clear=true', but leaves 'id' and 'by' unexplained in both schema and description, so it only partially compensates.

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

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

States a specific verb+resource pair ('Set or clear the review/verification profile') scoped to draft/planned tasks. It's clearly distinct from siblings like task_update or task_show, though it doesn't explicitly name an alternative for the same job.

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?

'Not allowed once the task has started' and 'Planners only' give explicit preconditions and exclusions. It stops short of naming a sibling alternative, but the when/when-not conditions are clear.

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

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

With only readOnlyHint=false declared, the description carries most of the burden and does add real context: the default action writes a rendered Markdown view, while check=true is non-writing and fails on drift. It still omits where the file is written and whether it overwrites an existing view, but the mutation semantics are disclosed clearly and consistently with the annotation.

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

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

One compact sentence, front-loaded with the action and artifact, then the mode modifier. Nothing is redundant or padded; every clause conveys 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?

No output schema and minimal annotations, so the description is the only source of behavioral detail. It covers the two modes well but leaves gaps an agent would care about: output location/filename, whether it depends on a prior task_validate, and what 'drift' is measured against.

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

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

Schema coverage is 0% and the lone parameter is undocumented structurally, so the description must compensate. It does: 'check=true fails on drift instead of writing' gives both the meaning and consequence of the flag, including the default write behavior implied by 'instead of writing'.

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 ('Render the Markdown view from tasks.json') and names the source artifact, which no sibling mentions. It is distinguishable from task_list/task_validate in resource terms, though it never explicitly contrasts with task_validate, whose drift-checking role sounds adjacent.

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 'check=true' clause implies a mode choice (verify vs write), which is useful conditional guidance. But there is no explicit statement of when to prefer this tool over task_validate or quality_check, 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?

Annotations only declare readOnlyHint=true; the description adds real behavioral value by disclosing that the response includes the effective closing policy (profile, review requirement and reviewer, review delay, quality gates) and subtasks. This matters because there is no output schema to convey return shape.

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: the first front-loads what is returned, the second gives the call trigger. No filler or redundancy.

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

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

With no output schema, the description does the work of summarizing the return payload, which is the key unknown for this tool. The only gap is the unexplained id parameter, which the description should have clarified.

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

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

One required parameter with 0% schema description coverage, and the description never mentions the id at all — no format, no indication of whether it is a task identifier vs. a profile/slug. The parameter is guessable from context, but the description adds nothing beyond the schema.

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

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

Clearly identifies the resource as a single task (by id) and enumerates the distinctive payload: effective closing policy plus subtasks. The verb is implicit rather than stated, but the scope is precise enough to distinguish it from task_list and task_next.

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

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

Gives explicit usage context: 'Read it before verifying or reviewing to know what that task needs.' That is a concrete trigger tied to downstream actions, though it does not name alternatives or state when not to use it.

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

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

Annotations only say readOnlyHint=false; the description supplies the crucial missing fact that this call destroys any order previously set via task_move, which annotations cannot convey. Gaps remain on scope (whole task graph vs. a subset) and reversibility, but the destructive consequence is front and center.

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

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

One tight sentence with no filler; the effect and the destructive scope are both front-loaded.

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

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

For a mutation tool with no output schema, the description covers the core effect and its main hazard, but leaves an aggregation-level question unanswered: does this reorder every task, or only a subset selected by 'by'? The single parameter is entirely unaddressed, which is thin even for a one-parameter tool.

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

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

Schema description coverage is 0% for the single 'by' parameter, so the description must carry its meaning — yet 'by' is never mentioned. Worse, 'Reset the execution order to phase, then id' reads as a fixed order, which an agent could take as contradicting the existence of an ordering parameter.

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

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

Specific verb plus resource: 'Reset the execution order to phase, then id', naming both sort keys and explicitly distinguishing it from task_move, which sets custom order. The one weakness is that it presents the ordering as fixed even though the schema exposes a 'by' parameter, so the stated purpose is slightly narrower than the tool's real surface.

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

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

The sentence implicitly routes the agent: use task_sort to revert to canonical phase/id order, and use task_move when a manual order is wanted. It also warns that the operation discards existing order, which is real usage guidance. It stops short of an explicit when-not or precondition statement.

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

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

With only readOnlyHint=false in annotations, the description carries the full burden and delivers: enforced state transitions, separate-call semantics for verification vs review, caller identity acting as verifier, reviewer identity constraints, delay since verification, checks requirement, fresh-review requirement for done, require_review override, and open-subtask restrictions. This is unusually rich behavioral disclosure.

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

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

The purpose is front-loaded and every sentence carries rules rather than filler. However, it is a single dense paragraph with long semicolon-chained clauses, which slightly harms scanability despite being efficient.

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

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

For a complex mutation tool with no output schema and minimal annotations, the description covers most critical behavior: transitions, identity rules, separate calls, review freshness, and subtask blocking. It still leaves 'reason' semantics and error/return behavior unaddressed, so it is strong 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 0%, so the description must compensate. It explains 'by' (caller identity is the verifier), 'verification_result' and 'review_result' semantics, the nested 'checks' list requirement, and status transition constraints. It does not explain 'reason' or clarify enum value meanings, so some compensation is missing.

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 ('Advance a task's status and record evidence') and immediately distinguishes this from generic updates by stating that transitions are enforced and evidence must be recorded. It is clearly not a sibling like task_move or task_show.

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

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

It provides substantial conditional guidance: send verification_result and review_result in separate calls, reviews require a distinct reviewer identity and delay, and done requires a fresh review unless require_review=false. It lacks explicit when-to-use-this-vs-alternative routing (e.g., versus task_claim or task_move), but the operational conditions are clear.

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

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

readOnlyHint=true is consistent with a validation pass, and the description usefully scopes what is checked. However it says nothing about what a failure looks like — whether it reports violations, throws, or blocks subsequent writes — which is the behavior an agent most needs from a validator.

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

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

A single front-loaded clause with the target first and the three validated dimensions listed compactly. No filler.

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

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

With no params and no output schema, the description is the only source for the result contract, and it omits it — an agent does not know whether success is signaled by an empty result, a boolean, or a list of violations. Adequate to call, incomplete to interpret.

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

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

Zero parameters, so there is no parameter semantics to explain and the description correctly does not invent any. Baseline 4 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?

Names a specific verb (validate) and resource (tasks.json) and enumerates the three checks performed: schema, status transitions and evidence gates. That is far more informative than the bare name, though it doesn't explicitly differentiate itself from the similarly scoped quality_check sibling.

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 this is the pre-flight/verification step among the task_* mutation tools, but nothing states when to run it (before commit? after task_update?) or that quality_check is the alternative for content-quality concerns.

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