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?

readOnlyHint=true already tells the agent this is a safe, non-mutating operation, so the description's main added value is the list of areas inspected. It does not say whether the tool reports problems, throws on failure, or how severe findings are surfaced, which matters for a diagnostic tool.

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

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

A single front-loaded sentence with the verb first and the scope enumerated after the colon; no filler. The list items ("view drift", "log") are terse to the point of being cryptic, which slightly undercuts the efficiency.

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

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

With no parameters, no output schema, and a read-only annotation, the definition is close to sufficient, but it leaves unclear what a diagnosis returns and whether a failure result is an error or a report. For a tool whose whole job is reporting findings, that gap is noticeable.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The colon-separated list of checks gives the agent a mental model of scope without implying any input it must supply.

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 ("Diagnose") and resource ("the project") and enumerates the checks performed: root, configuration, registry validity, view drift, log. An agent knows exactly what the tool inspects, though it never distinguishes itself from plausibly overlapping siblings such as task_validate or quality_check.

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 statement of when to run this versus task_validate or quality_check, no prerequisites, and no exclusions. The word "Diagnose" hints at troubleshooting, but with two sibling tools that could equally sound diagnostic, the agent is left to infer the routing decision.

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 adds real value: planner-only authorization, draft/planned-only scope, empty string as a clear operation, and a redirect for started tasks. It does not say what happens if a started task is passed (error vs silent no-op) or whether the edit 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 short sentences, each carrying a distinct constraint: what can change, who may call it, and where started tasks go instead. Nothing redundant.

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

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

There is no output schema and no annotations beyond a mutation flag, so the description carries the burden of telling the agent what a successful edit returns and what failure looks like. It covers scope and preconditions but not outcomes or the meaning of the required 'by' credential.

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 five parameters exist, so the description must compensate. It does well on 'spec' (path + section, empty clears) but leaves 'id' and especially 'by' unexplained, and it calls the parameter 'spec_source' while the schema names it 'spec', which can cause a mis-mapped 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?

Specific verb plus a concrete list of editable fields (title, spec_source, verification_cmd) scoped to draft/planned tasks. It clearly separates itself from task_note, but does not explain how it differs from the very similarly named sibling task_update, which an agent would have to guess 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?

'Planners only' states the precondition, 'pass at least one of...' states the invocation constraint, and 'Started tasks take task_note instead' routes to an explicit alternative. It stops short of saying when to use it versus task_update, the sharpest ambiguity here.

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

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

readOnlyHint=true already tells the agent this is a safe read, and the description reinforces it by describing a listing operation. It adds value beyond annotations by disclosing that json=true changes the return shape to a JSON array, which matters since there is no output schema; the default (non-json) rendering is left unstated.

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 core action, with the parameter notes packed in via parenthetical and clause. No wasted words.

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

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

For a zero-required-parameter list tool with no output schema, the description covers the action, the filter, and the json return mode, and annotations cover the safety profile. The remaining gap is the default output format when json is not set, which an agent would have to discover by calling.

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 has to carry the meaning, and it does explain both parameters: status as an optional filter and json as a flag that switches the return to a JSON array. The status enum values themselves are enumerated in the schema, so the agent can combine both sources.

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

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

States a specific verb and resource ('List tasks') plus the optional filter, which clearly separates it from single-task siblings like task_show or the routing tool task_next. It does not name those alternatives explicitly, but the scope is unambiguous.

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

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

The optional status filter and the json=true behavior are described, implying usage, but there is no statement of when to prefer this over task_next, task_show, or task_sort, nor any exclusion or prerequisite. Guidance is inferred rather than 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?

readOnlyHint=true already tells the agent this is a safe read, and the description usefully adds 'append-only' and 'JSON array' to convey immutability and payload shape. It omits behavior that materially matters for a log: event ordering, the default when no limit is given, and any cap on how far back the log goes.

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 dense sentence with zero padding, and the core noun (the log) is front-loaded ahead of the filtering options. The parenthetical '(subtasks included)' is well placed, though the sentence crams three distinct filter modes into one clause chain.

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

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

For a tool with three undocumented optional parameters and no output schema, the definition is thin — it should say what a log event looks like and what the default result is with no filters. Since there is no output schema, the description is the only place that information could live, and it is only partly there.

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

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

With 0% schema description coverage, the description carries the full parameter burden and partially delivers: 'task' maps to one task (with subtasks included), 'by' to one identity, 'limit' to the last N events. It never uses the parameter names explicitly and leaves open whether filters combine (AND) and whether 'last N' implies reverse-chronological order.

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 resource — the append-only mutation log — and states its return form (a JSON array), so the agent knows it retrieves history rather than mutating anything. It does not, however, contrast itself with siblings such as task_show or task_note, whose output could be confused with log data, so it stops short of a 5.

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

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

Use is only implied: the optional filters suggest 'use this when you want the log for a task or identity,' but there is no explicit when-to-use, when-not-to-use, or named alternative among the many task_* siblings. The agent must infer that this is the history/audit path rather than the current-state path.

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?

readOnlyHint=true is consistent with "Show," so no contradiction. The description adds real behavioral context beyond the annotation by disclosing the four eligibility conditions a task must satisfy, but it says nothing about what is returned when no task qualifies (empty result vs. error) or about the 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?

One sentence, front-loaded with the answer ("the one task that may start now") and then the qualifying conditions. Nothing is wasted and nothing is buried.

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

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

For a two-parameter tool with no output schema and no documented parameters, the description should explain the `owner` and `json` semantics and the empty-queue case. It covers the selection logic well but leaves an agent unable to predict outputs or parameter effects.

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?

Both parameters have 0% schema description coverage, so the description carries the full burden and fails: neither `json` (presumably output format) nor `owner` (presumably a queue filter, but does it scope the queue or the gate check?) is mentioned. An agent cannot safely set `owner` from this description alone.

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?

"Show the one task that may start now" is a specific verb+resource, and the eligibility chain (queue head, planned, dependencies met, phase gate met) makes the tool's selection rule unambiguous. It stops short of naming how it differs from siblings like task_show or task_list, but the semantics are clear enough to choose correctly.

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

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

The phrase "may start now" implies when to reach for this tool (picking the next actionable task), but there is no explicit when-to-use/when-not guidance and no alternative named. Usage must be inferred from the criteria rather than read 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 only declare readOnlyHint=false, so the description carries most of the burden: it discloses that the operation is purely additive (append, not replace), that a timestamp is generated server-side, and that status is untouched despite being a write. It stops short of saying whether the write requires permissions, whether notes can later be edited/removed, or what the call 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 short sentences, zero filler, with the core action first and the key constraint (no status change) trailing immediately after. Nothing is repeated from the name or 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 three-parameter append tool with no output schema and minimal annotations, the description covers the essential semantics and the key non-effect, which is enough to call it safely. However, the undocumented "by" parameter and the absence of any statement about what the caller gets back leave real gaps at 0% schema 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 0% across three parameters, so the description must compensate and largely does not. "text" is inferable from "note," but the optional "by" parameter is never explained (author? actor id? format?) and "id" is not stated to be a task identifier with any expected format. The timestamp mention is useful but describes an implicit behavior rather than a 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 ("Append") and resource ("a timestamped note to a task") in one clause, and immediately bounds the effect with "Does not change status." The parenthetical use-case list (decisions, follow-ups, reasons) further narrows the intent. It does not name a sibling such as task_log or task_edit, so the differentiation from those is inferential 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?

The parenthetical examples give clear situations to reach for this tool, and "in any status" removes the obvious precondition other task tools impose. "Does not change status" implicitly routes status changes to task_update/task_edit, but no alternative is named outright, so the exclusion is left for the agent to infer.

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.