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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the mutation/safety profile is covered structurally. The description adds only the CLI flag/field-name correspondence, not duplicate handling, auth needs, or the dryRun behavior, so it is modest added value rather than rich 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?

Two short sentences with the core action front-loaded and no filler. The CLI-flag aside is marginally useful for naming consistency but is the weakest sentence in an otherwise tight description.

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

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

For a 4-parameter mutation tool with no output schema, the description covers the required payload but leaves dryRun (a behavior-changing flag) and author (an enum with a default) unexplained anywhere. Annotations cover safety, but an agent still cannot tell what dryRun does 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 description coverage is 50%: id and comment are documented in the schema, while author and dryRun are not. The description reinforces that comment carries the body and must be supplied, but adds nothing on author or dryRun, so the undocumented half is not compensated.

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'), which is unambiguous and clearly distinct from siblings like create_task or update_task by its narrow action. It does not explicitly contrast with a sibling to say why you'd comment rather than edit, so it falls short of the 5 tier.

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

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

No when-to-use, when-not-to-use, or alternative guidance is given. The mention of update_task is only about field-name consistency, not about choosing between the two tools. An agent gets no routing context beyond the literal action.

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 a non-read-only, non-idempotent, non-destructive write, and the description adds useful state-behavior context about the research gate refusal. However it says nothing about whether re-attaching the same filename overwrites, duplicates, or is refused — a real gap given idempotentHint=false and destructiveHint=false are the only signals on that front.

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

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

Two sentences with the core action front-loaded and the gate mechanics second; nothing is padded. The second sentence is dense and clause-heavy, but each clause carries actionable information about the failure/recovery loop.

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

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

The description covers the primary workflow and the research-gate recovery well, and there is no output schema to explain. But `dryRun` — a fourth parameter documented nowhere in the schema either — is never mentioned, so an agent cannot learn from the definition that a preview mode exists. That leaves a meaningful hole for a mutation tool.

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

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

Schema coverage is 75% and the three documented parameters already carry rich descriptions with their refusal codes (TASK_NOT_FOUND, UNSUPPORTED_FILE_TYPE, input validation). The description merely restates the base64 and `.md` facts already in the schema and adds no new parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Attach a file to a task') plus the key encoding contract (base64), which is exactly what an agent needs to know before calling. No sibling tool attaches files, so there is no ambiguity to resolve; the definition is self-distinguishing.

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 a concrete when-to-use scenario: attaching a `.md` is the recovery path for a `type:"Research"` task blocked with RESEARCH_REPORT_REQUIRED. That is clear triggering context. It stops short of explicit when-not guidance (e.g. whether non-.md attachments are ever useful), so it lands at 4.

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

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

Annotations declare a non-read-only, non-idempotent, non-destructive mutation; the description adds genuinely new behavior by specifying the return contract (object = claimed, null = nothing to claim) and that an empty board is success, not an error. It does not address claim atomicity/concurrency, permissions, or why it is non-idempotent, leaving some mutation behavior 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?

The core claim rule is front-loaded and efficient, but the null/empty-board case is restated three times (null result, the CLI `task:null` exit-0 comparison, and the filter case), which is redundant padding for a single concept.

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

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

With no output schema, the description correctly fills the gap by explaining the return value shape and the empty-result case, which is the most failure-prone aspect of this tool. It remains incomplete on filter parameter behavior and dryRun, but the critical call contract is covered.

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

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

Schema description coverage is 0% across four parameters (tag, type, user, dryRun), so the description carries the full burden. It only obliquely references filtering ('A valid filter that matches no task'), giving no meaning for tag/type/user semantics or for what dryRun actually does.

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 with scope: 'Claim the highest-priority ROOT task in todo and set it to in-progress.' It also distinguishes itself from the sibling set (create_task/update_task/list_tasks) by defining the root-vs-child rule, so an agent can tell it apart 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 clear usage context: use it to pull the next unit of work, then work through the claimed task's children rather than claiming children directly. It does not explicitly name alternative tools or state when-not-to-use (e.g., vs. list_tasks/get_task), so it stops short of full routing guidance.

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

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

Annotations already declare the safety profile (not read-only, not idempotent, not destructive), so the bar is low. The description still adds substantial non-obvious behavior: links are merged as a union with parent, duplicate pairs are no-ops, and `links: []` is refused rather than treated as 'no links'. It omits dryRun semantics, which is a notable behavioral gap for a mutation tool.

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

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

The purpose is front-loaded in one short sentence, followed by a dense but purposeful paragraph on link semantics. It is appropriately sized for the subtlety it explains, with no filler, though the link paragraph is packed tightly enough to require careful reading.

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 13-parameter creation tool with no output schema and almost no schema descriptions, the definition covers only the creation act and the links nuance. Nothing tells the agent what dryRun does, what the tool returns, or what a successful call looks like, leaving clear gaps given the schema's richness.

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 only 8% across 13 parameters, so the description must carry the load. It thoroughly explains the `links`/`parent` union and the empty-array refusal, but leaves the majority of parameters (dryRun, url, tags, sortKey, selector, cssSelector, status, priority) undocumented, and much of the link text echoes the existing schema property description.

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

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

The opening sentence gives a specific verb and resource ('Create a new task') plus the primary fields it accepts, so an agent immediately knows what the tool does. It also implicitly differentiates itself from update_task by referencing that tool's merge semantics, though it never explicitly states the create-vs-update 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?

Usage is implied by the verb 'create' and the note that a new task has nothing to preserve, which gently explains why links behave as a pure union. However, there is no explicit 'use this when you need a new task, not update_task/get_task' routing guidance despite eleven sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds only 'for LLM consumption' and says nothing about the board-wide default scope, the exact-match refusal/skip behavior, or output differences between formats — context that would be genuinely additive here.

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 zero filler, which is structurally clean. But the brevity reads as under-specification rather than disciplined conciseness for a tool with this many behavioral nuances.

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 three parameters, no output schema, and a scope that can silently expand to the whole board when ids are omitted, the description omits information an agent needs to call this safely and predictably. The schema carries most of the load, but the description does not close the remaining gaps.

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 67%, with the `id` and `ids` parameters already documenting exact-match semantics and the whole-board default. The description contributes no parameter meaning at all, and `format` has no description in either place, so the description fails to compensate for the coverage 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?

Names a specific verb (export) and resource (task(s)) plus the output artifact (a formatted prompt for LLM consumption), which is concrete enough to distinguish it from list_tasks/get_task. However, it never contrasts itself against those siblings, so the agent must infer the boundary on its own.

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

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

There is no when-to-use guidance and no named alternative. Nothing tells the agent when to prefer export_prompt over get_task or list_tasks, or that omitting ids exports the entire board.

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 the safety profile (readOnly, idempotent, not destructive, closed-world), and the description adds real behavioral context beyond them: the tool functions with or without a running server, and in the stopped case the guide falls back to the default port and the result reports serverRunning: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?

A single dense sentence, but it is front-loaded with the core purpose and then layers the output contents and the server-state caveat in a logical order. Every clause carries information; minor tightening is possible 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, and the description compensates by naming the returned artifacts (script tag, snippet, bookmarklet, URL) plus the serverRunning flag field. For a zero-parameter read tool, an agent has everything needed to call and interpret 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?

The tool takes zero parameters, so there is nothing to disambiguate; the baseline for a no-param tool is 4. No parameter semantics are needed or 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?

States a specific verb and resource ('Get the overlay/bookmarklet integration instructions') and enumerates exactly what the payload contains: script tag, console snippet, bookmarklet, and /inject URL. This is unmistakably distinct from sibling tools like list_tasks 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?

Gives an explicit sequencing rule: call start_kanban first when you need real URLs, and explains the tool still works otherwise. It doesn't describe any other alternatives, but the prerequisite and fallback behavior are clearly spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description's 'Read-only; takes no input' largely restates those structured fields; the one bit of added value is the 'resolved' framing, hinting the server computes/derives the project rather than reading it verbatim.

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 waste, with the resource and its returned fields front-loaded before the read-only affirmation.

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

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

With no output schema, the description carries the burden of describing the return value and does so completely: name, absolute root, git branch and mode. Nothing an agent needs to invoke or interpret this tool 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?

There are zero parameters, which sets the baseline at 4. The description's 'takes no input' reinforces the empty schema, and no additional parameter meaning is needed.

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), and enumerates the returned fields (name, root, git branch, mode). No sibling tool (all task/comment/kanban operations) overlaps with project resolution, so the agent can distinguish it immediately.

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

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

Usage is implied rather than stated: 'Return the resolved project this server is attached to' makes clear this is the project-context lookup, and 'takes no input' confirms it is a simple retrieval. However, there is no explicit when-to-use framing or named alternative, so an agent is left to infer the call condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds that the response expands to include comments and files, which is genuine behavioral context, but says nothing about pagination, size limits, or failure modes.

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 front-loaded sentence with the core action first and the payload detail second. No filler, no redundancy.

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

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

For a 2-param read tool with no output schema (so return values need not be described), the description is adequate on scope but leaves the 'fields' parameter unexplained and gives no guidance on when this beats the sibling readers. Functional but with visible gaps.

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 50%: the required 'id' param is richly documented (prefix matching, TASK_NOT_FOUND), but 'fields' has no schema description and the tool description never explains it. At this coverage level the description only marginally compensates, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a single task by ID') and scopes it as single-record retrieval with 'full details including comments and files'. The word 'single' implicitly separates it from list_tasks, but 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?

The description gives no when-to-use guidance, no prerequisites, and names no alternative. The only routing hint (get an id from list_tasks) lives in the schema's id description, not in the tool description, so the description itself leaves usage 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, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: default filtering to root tasks and the hiddenChildren field that reports omitted matches — context an agent could not derive from annotations or schema.

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

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

Four short sentences, front-loaded with purpose, then defaults, then response behavior. 'Returns task list with configurable fields' is mildly redundant with the schema's fields parameter, but nothing else 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?

For a 7-param listing tool with no output schema, the description covers the critical default (root-only) and a returned field (hiddenChildren), which are the main non-obvious behaviors. Gaps remain around valid values for the fields array and ordering, but the essential calling context is present.

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

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

Schema coverage is only 14%, so the description must carry weight. It explains children's default and effect and references configurable fields, and limit is documented in the schema, but tag, user, status, and especially the fields array (which fields are valid) get no elaboration — 'optional filters' is a blanket phrase rather than per-parameter meaning.

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) and immediately identifies the tool's distinctive scope: ROOT tasks only by default. It does not name a sibling such as get_task or claim_next_task to differentiate, but the read/list semantics are 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?

It gives a concrete condition for one parameter ('children:true to include' non-root tasks), which is useful usage guidance. However, it never says when to use list_tasks versus get_task or claim_next_task, nor any prerequisites, so tool-level selection guidance is only implied.

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 idempotentHint=true, readOnlyHint=false, openWorldHint=true, so the safety profile is covered. The description goes beyond them by explaining what idempotency actually looks like in practice (second call returns the running instance with alreadyRunning:true instead of contending for the port) and enumerating the returned payload. It does not mention how the server is stopped or any auth/CORS implications.

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 tightly packed sentences, front-loaded with the core action and return value, then idempotency, then the ordering constraint. No filler or repetition.

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

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

With no output schema, the description carries the burden of return-value disclosure and does so (URL, localhost URL, agent prompt, integration guide). Annotations cover the mutation/safety angle. Minor gap: lifecycle concerns such as stopping the server or port-conflict behavior on the first call are unaddressed.

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

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

Schema description coverage is 100%, so host, port and dryRun semantics (defaults, 0.0.0.0 LAN behavior, ignore-when-running) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides; 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?

Specific verb + resource ('Start the local kanban board server') plus an explicit statement of what it returns (URLs, agent prompt, overlay guide). It is clearly distinguishable from the neighboring get_integration_guide, which it names, and from task CRUD siblings.

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

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

Gives explicit sequencing: 'Call it once before get_integration_guide so the guide carries real URLs,' and reassures that a second call returns the running instance rather than failing. No explicit when-not-to-use case (e.g. in remote/Docker setups), but the ordering guidance is well 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?

Goes well beyond the annotation hints: it discloses that links/addLinks both MERGE and cannot destroy by omission, that re-sending a pair is a no-op, the exact application order (clearLinks -> links+addLinks -> removeLinks), that clearLinks is the only wholesale-destructive path, and the refusal modes (links: [] refused, TASK_NOT_FOUND changes nothing, verifyReason alone refused as E_USAGE). None of that is derivable from readOnlyHint/destructiveHint/idempotentHint.

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

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

Purpose is front-loaded, a dryRun-style LINKS block separates the dense link rules, and every sentence about merge/surgical/clear semantics earns its place. The final sentence describing CLI flag parity (--set-parent/--relates/etc.) is length the MCP caller cannot act on and is the one trimmable element.

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-param mutation with no output schema and only one required field, the risky link and verification paths are documented thoroughly enough to call correctly. The omissions are dryRun (does it validate or no-op?) and commitMessage, plus no statement of what the tool returns after a successful update.

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 only 50% schema description coverage across 14 params, the description carries real weight: it fully explains links, addLinks, removeLinks, clearLinks, setVerify, and verifyReason, including the ordering contract and empty-array refusal. It leaves branch, dryRun, and commitMessage entirely undefined in both schema and description, which is the remaining 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?

"Update an existing task" states a specific verb and resource, and the follow-up enumerates the updatable surfaces (status, title/description, comments, links). It stops short of naming the siblings it overlaps with — add_comment and verify_task — so an agent must infer that the `comment` and `setVerify` params here are alternatives to those 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?

Strong condition-based guidance for each mode: merge vs surgical remove vs wholesale clear, and the three setVerify verdicts with the requirement that "cannot" needs verifyReason and that "pass" is required for annotated tasks at the review transition. It does not route among sibling tools (e.g. when to call add_comment or verify_task instead), so it is clear context without explicit alternatives.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the agent knows this is a mutating, non-idempotent, non-destructive call. The description hints that it persists a baseline artifact, but omits what side effects occur, whether repeat runs re-capture the baseline, auth requirements, and timeout/timeoutMs impact.

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, purpose front-loaded, no filler or repetition. It is arguably under-specified rather than concise, but structurally it is tight.

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?

A four-parameter tool with no output schema and no annotations covering side effects or errors, yet the description says nothing about what the verification returns, how failure is surfaced, or how the three optional parameters change behavior. Too thin for the tool's complexity.

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 only 25%: `id` is richly documented, but `url`, `dryRun`, and `timeoutMs` have no descriptions. The description mentions none of these parameters, so it fails to compensate for the coverage gap and 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?

States a specific verb+resource: 'Run visual verification on a task,' and adds the mechanism ('captures baseline and compares'). No sibling tool does verification, so it is distinguishable in practice, but it never explicitly differentiates itself from the surrounding 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?

No when-to-use guidance, no prerequisites (e.g. does a baseline need to exist first?), and no mention of alternatives or when not to run it. The agent must infer all of this.

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