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

Annotations already cover the safety profile (not read-only, non-destructive, non-idempotent), and the description adds genuinely new behavior: the append-only semantics, the `author` default of agent with the note that only MCP can override git config, and dryRun as a validate-without-write path. It stops short of saying what happens on repeated identical calls, which matters given idempotentHint=false, so not a 5.

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

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

Three tight sentences, front-loaded with what the tool does and the no-field-change guarantee, then naming, then routing. The CLI-flag aside is mildly incidental but earns its place by anchoring the parameter name across surfaces.

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 4-parameter, no-output-schema append tool, the description covers mutation scope, defaults, the dry-run escape hatch, and sibling routing. The only real gap is return/duplication behavior (does a second identical call add a second comment?), which is a meaningful omission given idempotentHint=false.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-tool semantics the schema cannot: `comment` is the same name as the CLI's --comment flag and update_task's field, which is directly actionable for an agent composing calls. It also reinforces the author and dryRun defaults, though those largely restate 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?

States a specific verb and resource ('Add a comment to a task') and immediately bounds the scope with 'without changing any of its fields,' which separates it from update_task. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives an explicit routing rule: use this to discuss or record progress, use update_task's `comment` when the note accompanies a status or field change. It even flags a hard constraint ('review REQUIRES the note on the same call'), which prevents a wrong-tool call that would otherwise look valid.

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

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

Goes well beyond the annotations: it discloses in-place byte overwrite with no duplicate entry on re-attach, that dryRun validates without writing, and that attaching a .md is what unblocks review of a Research task. Annotations only declare the generic write/idempotency profile, so this added mutation semantics carries real value.

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

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

Front-loaded with the core action, then overwrite semantics, dryRun, and the gate rule in descending priority. It is dense but every sentence carries distinct information; the research-gate sentence restates the refusal consequence twice ('refused review ... so attaching the report is how to recover'), which is the only real redundancy.

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

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

For a 4-parameter mutation with no output schema and no rich annotations, the definition covers write semantics, validation mode, failure codes and sibling routing. It does not say what a successful attach returns (file id, size, resulting file list), which leaves a small gap an agent may care about.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by tying the filename extension to acceptance and the research gate, and by tying id to the attach target and TASK_NOT_FOUND failure. The base64-vs-path distinction for contentB64 is left mostly to the schema.

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

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

States a specific verb and resource ('Attach a file to a task') plus the payload form (base64) and the key invariant ('without changing any of its fields'). The final sentence contrasts it directly with the add_comment sibling, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit use cases ('reports, screenshots and evidence'), a named alternative for the adjacent case ('use add_comment for discussion text'), a validation-only mode ('Pass dryRun'), and a concrete trigger/recovery path for the research gate (RESEARCH_REPORT_REQUIRED until a .md is attached). Both when-to-use and when-not-to-use are covered.

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

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

Annotations only flag it as a non-readonly, non-destructive, non-idempotent mutation; the description adds substantial context beyond that: the root-before-child ordering rule, the fallback behavior and its explicit notice, the refusal of orphaned children, and the empty-board-is-success-with-null semantics. No contradiction with readOnlyHint=false since it genuinely mutates state.

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

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

Front-loaded with the core action and return-value guarantee, and most sentences carry distinct information (root-first, fallback, refusals, dryRun). It runs long and repeats the filter idea already in the schema, but nothing is wasted enough to penalize heavily.

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

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

No output schema exists, and the description compensates by explaining the return semantics (the object is the task; empty/filtered-out yields null success equivalently to the CLI with exit 0). Combined with the ordering and fallback rules, an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100% and all four parameters (tag AND-matching, type enum, user, dryRun preview) are already documented in the schema. The description adds only light framing (filters 'narrow the pool') without new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (claim) and resource (highest-priority todo task) and the resulting state change (set to in-progress), plus clarifies the returned object IS the claimed task. It also explicitly differentiates itself from siblings by naming list_tasks for browsing and get_task for inspecting an already-held task.

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

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

Explicit when-to-use (pull the next unit of work) and when-to-use alternatives (list_tasks to browse without claiming, get_task to inspect a held task). It also spells out the root-first preference, the child fallback condition with CHILD_CLAIM notice, and the refusal of children under backlog/done parents.

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

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

Goes well beyond the annotations: discloses that `links` is an additive MERGE unioned with `parent`, that duplicate pairs are no-ops, and that `links: []` is REFUSED — non-obvious failure behavior an agent would otherwise trip on. dryRun explicitly validates without writing, consistent with destructiveHint=false.

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

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

Front-loads the core action and the usage routing first, then the tricky merge semantics. The merge paragraph is dense but every clause carries non-obvious information; only slight redundancy (repeating the links refusal in both schema and prose) keeps it from a 5.

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 14-parameter mutation tool with no output schema, the description covers the risky areas (link merging, dryRun, field selection) that an agent must get right. Edge parameters (sortKey, selector/cssSelector alias, type enums) are adequately handled by the 100%-covered schema, so nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics the schema does not: the union/merge behavior of `links`+`parent`, the refusal of an empty array, and equivalence of the `fields` selector with list_tasks/get_task. Minor params like sortKey and cssSelector alias are left to the schema, keeping it short of a 5.

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

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

States a specific verb and resource ("Create a new task with title, description, and metadata") and immediately contrasts it against update_task (change existing) and add_comment (discuss without editing). An agent can distinguish it from every sibling without opening the schema.

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

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

Explicit routing: "Use it for a new unit of work; use update_task to change an existing task, and add_comment to discuss one without editing it." It also gives when-to-use guidance for dryRun (validate without writing) and fields (compact response), leaving little to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds meaningful runtime context beyond them: it works offline, falls back to a default port, and surfaces a serverRunning:false flag. This is exactly the kind of state-dependent behavior annotations cannot express.

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

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

Two sentences, front-loaded with the outcome and artifact list, then the server-state caveat and the corrective action. Every clause carries information; nothing is padding.

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 volunteers the return contents (script tag, console snippet, bookmarklet, /inject URL, serverRunning flag) and the condition affecting them. An agent has everything needed to call it and interpret the result.

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 the schema baseline applies; there is nothing to document. The description correctly adds no parameter chatter, keeping the text focused on behavior.

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

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

States a specific verb (get) and resource (overlay/bookmarklet integration instructions) and enumerates the exact artifacts returned: script tag, console snippet, bookmarklet, /inject URL. It is clearly distinguishable from siblings like export_prompt or start_kanban.

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

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

Explicitly says it works whether or not the server is running, explains the degraded case (guide built against default port, serverRunning:false), and names the alternative to call first (start_kanban) to get real URLs. No inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so 'Read-only; takes no input and changes nothing' mostly restates them. The description still adds real value by disclosing the server-scoped resolution behavior and the exact returned fields (name, absolute root, branch, mode), which annotations do not cover.

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 compact sentences: purpose and return fields first, safety second, usage trigger last. No filler, and the most important information is 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?

There is no output schema, so the description's enumeration of the returned values is exactly what an agent needs to decide whether to call it. Combined with annotations covering safety and a zero-parameter schema, nothing material is missing.

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

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

With zero parameters the baseline is 4, and the description correctly confirms 'takes no input,' aligning with the empty schema. There is no parameter meaning left to add.

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 ('Return') and resource ('the resolved project this server is attached to'), then enumerates the returned fields: name, absolute root, git branch and mode. That scope cleanly separates it from the task-oriented siblings such as get_task and list_tasks.

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

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

Explicitly says when to call it: 'when you need board location or branch context before operating on tasks.' That gives a clear triggering condition, though it names no alternatives or exclusions for cases where project context is already known.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so 'Read-only; changes nothing' is largely redundant. It does add value beyond structured data by disclosing the payload shape (comments and files are returned by default, and can be suppressed via fields), which matters for response size.

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 what it does, then the projection option, then routing. No filler and nothing 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?

No output schema exists, yet the description conveys the return shape (full task with comments and files, or a compact projection), which is exactly the gap it needs to fill. Parameters are fully covered by the schema, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100% and both parameters are documented with equivalent examples (the fields example is literally identical in schema and description). The description correctly frames the compact-vs-full tradeoff but adds no syntax, format, or edge-case detail the schema lacks.

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 ('Get') plus resource ('a single task by ID') and explicit scope ('full details including comments and files'). It is immediately distinguishable from list_tasks, claim_next_task, and update_task named in the same paragraph.

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

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

States the triggering condition ('when list_tasks gave you an id or you already hold one') and routes to the alternatives by name: list_tasks for board search, claim_next_task for pulling the next unit of work. Both when-to-use and when-not-to-use are covered.

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

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

Annotations already cover read-only/idempotent safety, yet the description goes further with non-obvious behavior: 0-limit falls back to default 20 and is echoed in `limitNotice`, offsets are 0-based, `remaining` is scope-dependent, `nextCursor` is null exactly when exhausted, and the cost of full listing (~900 tokens/task, ~450k for a 500-task board). This is exactly the context annotations cannot express.

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

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

Front-loaded and every clause is informative, but it is a single semicolon-chained wall of text that duplicates schema details (the 0-limit rule and the field projection caveat appear in both). Structure would improve with the response-field semantics broken into a short list rather than one dense paragraph.

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

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

There is no output schema, and the description compensates by naming and explaining every response field (totalMatching, totalRoots, hiddenChildren, returned, limit, truncated/hint, offset, remaining, nextCursor, order). An agent can consume the result correctly without guessing.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description contributes cross-parameter semantics the schema keeps separate: `children` only matters when no status/type/user/tag filter is given, and `fields` projections never hide commentCount/fileCount. It restates some limit/0-fallback detail already in the schema, hence not a 5.

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

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

States a specific verb+resource ('list tasks with optional filters') and immediately gives the distinguishing scope rules: unfiltered = roots only, filtered = every match including children. An agent can tell exactly what this returns without opening the schema, and it is clearly separable from get_task and claim_next_task.

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

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

Explicitly routes: 'Use it to browse or search the board; use get_task when you already hold an id, and claim_next_task when you want the next unit of work claimed rather than just listed.' Also states the when-not for unbounded listing ('there is no unbounded mode, page with nextCursor').

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 say only that it is non-destructive and idempotent; the description earns its keep by spelling out the merge model (field-by-field, local-only data retained), the conflict-resolution rule with the `status` exception, and that a repeat pull is a byte-no-op. That is exactly the behavioral detail annotations cannot express.

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

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

Front-loaded with the core action and the additive guarantee, and each subsequent sentence carries a distinct rule. It runs long as a single dense paragraph, and the nesting of preferLocal/preferRemote/status takes re-reading, costing a point.

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-param, no-output-schema tool, the description covers mutation semantics, conflict policy, idempotency and dryRun preview. The remaining gap is what the dryRun report or pull result actually contains, which nothing else documents.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value the schema cannot: how preferLocal and preferRemote interact on conflicting fields and that `status` is the exception. It doesn't explain `out` beyond what the schema already says, so not a 5.

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

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

States a specific verb and resource ('Pull the online board into the local task store') and immediately frames it as 'the inverse of a push', which anchors it against a sibling. An agent can distinguish it from push and list_tasks without inspecting any schema.

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

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

Explicitly names the situations to use it (after working in another checkout or on the web) and routes the agent to alternatives: list_tasks for browsing without writing, push for sending work up. This is genuine when/when-not guidance, not implied usage.

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

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

Annotations declare idempotentHint=true and destructiveHint=false, but the description goes further by explaining the mechanism: one server per process, a second call returns alreadyRunning:true rather than 'fighting for the port.' It also discloses that the server is local, that 0.0.0.0 yields an extra localhost URL, and that host/port are ignored once running — behavioral detail not encoded in any structured field.

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

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

Front-loads the core action and return contents, then layers idempotency, dryRun, and routing guidance in descending priority. Slightly dense — the return-field enumeration and the sibling guidance compete for the opening — but nearly every clause carries operational weight.

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

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

No output schema exists, and the description compensates by naming exactly what comes back, including the conditional localhost URL and the alreadyRunning flag. For a zero-required-param server-start tool, nothing an agent needs to decide whether to call it is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description earns a bump by linking parameters to consequences — dryRun reports URLs 'without binding anything,' and binding 0.0.0.0 changes the return payload. It stops short of adding anything the schema's own per-property descriptions don't already cover for host and port.

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 ('Start the local kanban board server') and immediately enumerates the four things returned (kanban URL, localhost URL, agent prompt, overlay guide). It also carves out its position relative to siblings by naming get_integration_guide, so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use ('Call it once before get_integration_guide so the guide carries real URLs') and explicit when-NOT ('skip it entirely for remote or Docker setups where a localhost server is unreachable'), plus the dryRun escape hatch. That is the full when/when-not/alternative triad.

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

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

The annotations declare destructiveHint=false, but the description says clearLinks is 'the only destructive path' and that clearLinks removes EVERY link from the task. That is a direct contradiction of the structured safety metadata, so it must be scored 1 despite the otherwise rich detail about gates, error codes, and merge behavior.

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

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

The purpose is front-loaded and the review-gate rules are organized with clear caps and error codes. It is long, but the complexity justifies most of the length; the repeated CLI cross-references are the main trimmable content.

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

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

For a 16-parameter mutation tool with no output schema and several hard gates, the description covers the critical preconditions, error codes, and interaction rules an agent needs. It is nearly complete, though the destructiveHint contradiction undermines trust in the safety profile.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics: it explains that links/addLinks merge and preserve unnamed links, that clearLinks is the only wholesale removal path, and that clearLinks is applied before the merge sequence. This helps an agent reason about link operations beyond the individual field descriptions.

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 and enumerates the editable facets (status, title/description, comments, links). It explicitly distinguishes itself from add_comment and verify_task, so an agent can select it without opening sibling schemas.

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

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

Explicitly says when to use this tool versus add_comment (discuss without changing fields) and verify_task (actually run visual verification). It also specifies when dryRun, fields, branch, and the review-gate parameters matter, leaving little to inference.

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

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

Annotations only declare readOnlyHint=false and non-idempotency; the description adds the actual side effect (every run appends a system comment), the dryRun escape hatch for a side-effect-free preview, timeout default and ceiling, and the specific refusal codes E_NO_BASELINE / E_NOT_FOUND / VERIFY_TIMEOUT. That is well beyond what the annotations convey and matches their non-read-only claim.

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

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

Front-loaded with the operation, then a clearly flagged "MUTATES:" clause, then per-parameter notes and error codes — no wasted sentences. It is a dense single paragraph, so a reader must parse several compound clauses, but nothing is redundant.

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

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

For a mutating tool with no output schema, it covers side effects, preview mode, error codes and parameter overrides. The only gap is the return payload shape of a successful run (what the appended comment/outcome looks like), which the agent must discover by calling it.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds semantics by tying `url` to a run-only override, `timeoutMs` to the VERIFY_TIMEOUT refusal, and `dryRun` to the no-write guarantee. It largely mirrors the schema, hence 4 rather than 5.

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

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

States a concrete verb+resource: run visual verification on a task with Playwright, loading the annotated page (url + selector) and comparing the live element against the baseline. It also explicitly contrasts with update_task's setVerify ("this tool never sets it"), so an agent can distinguish it from the neighbouring task tools.

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

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

Gives both when-to-use ("check an annotated task before review") and the alternative for the adjacent job ("use update_task's setVerify to record the human verdict"). It also names a preview path (dryRun) and the precondition failure (no baseline → re-annotate in `vibeflow kanban`).

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