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

No annotations are supplied, so the description carries the full disclosure burden, and it does so well: it explains the state transition (out of findings, counts and grade), persistence in the `acknowledged` list 'where it stays visible with your reason', and the reversal mechanism ('undo=true puts it back'). It also notes the site-scoping constraint ('Works on reports filed under a site'). It does not mention permissions/authorization or idempotency of repeat acknowledgements, keeping it below 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?

Front-loads the core action and effect in the first sentence, then adds usage guidance, parameter passing, and undo in a tight sequence. Every sentence is functional, though the em-dash-heavy compound sentences and the trailing site-scoping note reduce crispness slightly.

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 annotations and no output schema, the description covers purpose, effect, usage constraints, and reversal, which is close to what an agent needs. It omits the response shape and whether the report must be a site report in all cases beyond the terse 'Works on reports filed under a site' note.

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

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

Schema description coverage is 100% and every parameter (report, rule, selector, reason, undo) is documented in the schema itself, so the baseline is 3. The description mostly restates that set ('Pass the report (URL or id), the rule and the selector exactly as the finding gives them, and a reason') with only slight added guidance about copying values verbatim from the finding.

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 ('Mark ONE finding as a known false positive for this site') and immediately describes the downstream effect on findings, counts, grade, and the acknowledged list. This is unmistakably distinct from audit_url, get_report, get_shot, and verify_fix 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 an explicit precondition ('only after you've checked the finding is wrong on this page (the rule misread it)') and an explicit exclusion ('never to silence a real problem you'd rather not fix'), which is strong when/when-not guidance. It does not name an alternative tool (e.g. verify_fix) for the case where the problem is real, so it stops short of full 5-level 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?

With no annotations, the description carries the full burden and does so: it discloses that interaction probes navigate/read/click, that discovery skips action-word labels, that write probes need an unreachable --allow-mutation flag, that declared tests SUBMIT forms and may DELETE items, and that credentials come from uxlint.toml personas. Mutation and side-effect risks are stated plainly.

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?

It is long, but it is organized into labelled WORKFLOW/SAFETY/SETUP/AUTH blocks with the purpose and return shape front-loaded, and each block carries decision-relevant content rather than filler. A few sentences could be tightened, 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 7-parameter, zero-annotation tool with mutation-capable probes, no output schema, and a setup prerequisite, the description covers return shape, workflow, safety, auth, and setup. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents base, crawl, judge, tests, detail, routes, and states with defaults and constraints. The description adds output-format detail (RULE, SOURCE file:line, SELECTOR, FIX, EDIT) but little beyond the schema on the parameters themselves, 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?

Opens with a specific verb+resource ('Audit a website's UX/design') and enumerates the concrete dimensions checked (contrast, tap targets, type scale, copy clarity). It also describes the shape of each finding and explicitly routes to siblings (verify_fix, ux_guidance, acknowledge_finding), so the agent can distinguish it from the rest of the toolset.

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

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

Provides an explicit numbered WORKFLOW with when-to-do-what ordering (ux_guidance before changes, open source line, smallest fix, verify_fix, iterate), plus the acknowledge_finding escape hatch for false positives and the conditional lint_feedback path. Alternatives and their triggering conditions are named rather than 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?

No annotations exist, so the description carries the full burden, and it delivers: it labels the operation as a read, discloses that timed-out reports preserve partial findings and say so, and notes reports are private and read with the user's uxlint login. It also commits to a stable output shape by enumerating the returned fields.

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

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

The description is front-loaded with the core purpose, and each sentence adds a distinct fact: use cases, input formats, return payload, and privacy/auth. It is longer than minimal but dense and without filler, though the parenthetical examples could be slightly tightened.

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 compensates by enumerating the returned grade, deltas, and each finding's fields, and by explaining timeout behavior and auth requirements. It does not cover error cases or exact formatting, but the schema handles parameter formatting, making this complete enough for correct invocation.

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 input schema already documents both parameters with 100% coverage, so the baseline is 3. The description restates the report parameter's accepted URL/path/id forms but adds no new semantic detail beyond the schema; detail's full-vs-compact behavior is delegated to audit_url and already covered in the schema.

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

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

The description opens with a specific verb-resource pair ('Read an EXISTING report's findings') and immediately distinguishes the tool from siblings by mentioning audit_url and verify_fix. It makes the scope explicit: existing reports, including timed-out ones, not new audits.

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 clearly identifies when to use get_report: reports started in the dashboard, lost audit_url calls, or timed-out runs. It does not explicitly say 'use audit_url for new audits', but 'EXISTING' and the audit_url reference make the boundary inferable, giving clear context without a formal when-not clause.

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?

No annotations are provided, so the description carries full burden. It discloses that reports are PRIVATE, reads requires the user's uxlint login, returns image inline (if client supports MCP images), and always writes to a local file. This adds significant behavioral context beyond what an annotation might provide, such as side effects (writing a file) and authentication requirements. The only minor gap is not detailing the exact file path or cleanup behavior, but the description is quite transparent.

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

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

The description is concise (about 3 sentences) and front-loads the core action. Every sentence provides essential information: purpose, why it's needed, what to pass, and what happens. No fluff or redundancy. The structure is logical: what, why, how, outcome.

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

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

Given that there is only one parameter, no output schema, and no annotations, the description is complete. It covers the tool's purpose, usage, parameter source, return behavior (inline and local file), and the limitation about private reports. This is sufficient for an agent to select and correctly invoke the tool.

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

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

Schema description coverage is 100% and it already explains the screenshot_url parameter clearly. The description adds contextual meaning by tying the parameter to the finding's screenshot_url and specifying the source (audit_url/verify_fix). It also clarifies that the URL can be a full URL or a /r/… path. This adds value beyond the schema, so a slightly above baseline score is warranted.

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 clearly states the tool's purpose: to view a report's annotated screenshot, with the flagged element boxed. It also distinguishes it from siblings by explaining why a plain GET won't work and that it requires the finding's screenshot_url. The verb 'View' and specific resource 'report's annotated screenshot' are precise.

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 explicitly explains when to use this tool (to fetch a screenshot_url from audit_url/verify_fix findings) and why it's necessary (reports are private, plain GET won't work). It also provides context that the screenshot URL comes from specific sources, serving as an alternative to direct fetching. This is exactly the kind of usage guidance expected.

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 no annotations, the description carries the behavioral load and does so well: it re-reads the nearest project's uxlint.design.json on each call, only approved versioned decisions steer edits, and it never auto-approves or rewrites the contract. The implicit read-only nature is conveyed rather than stated outright, but the governance constraints are unusually explicit for a retrieval 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 governing instruction (read before building) is front-loaded in the first clause, and the closing loop sentence ties usage together. It is on the long side and the enumerated topic catalogue slightly pad it, but every sentence carries operational information.

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

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

No output schema exists, so the description must characterize returns, and it does: guidance items each name the uxlint rule that catches a miss. Combined with the read-before-build workflow and the config source, an agent has enough to invoke and interpret it. Return format granularity (single topic vs index) is only implied by the topic parameter.

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

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

Schema coverage is 100% and the single topic parameter is fully documented in the schema, including the alias and fallback behavior, so the schema does the heavy lifting. The description's topic list largely restates the schema enum values and adds little parameter-level meaning beyond the schema itself. Baseline 3 is appropriate.

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

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

States a specific verb+resource (read UI/design guidance before building or changing UI) sourced from uxlint's audit corpus and the project's uxlint.design.json. It also distinguishes itself from siblings by defining the loop that terminates in audit_url. An agent can tell exactly what this tool returns versus audit_url or get_report.

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 to read BEFORE building or changing UI, names the alternative audit_url as the confirmation step after building, and states the exclusions: only explicitly approved versioned decisions guide edits, and never auto-approve or rewrite the contract. When-to-use, when-not, and the sibling handoff are all present.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does a good job: discloses that the tool only reports observed failures for rules not in the supported passing list, that unknown rules and missing evidence never clear, and that a cleared finding is not a user endorsement of the fix. It also explains the regression guard behavior. It does not explicitly state whether the operation is read-only or has side effects, but given the described behavior (a check), this is implicit. One might argue for a 5, but the lack of explicit mention of side-effect-freeness or any destructive potential is a tiny gap; still, it's quite thorough.

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

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

The description is a solid paragraph, slightly long but information-dense. It front-loads the purpose, then adds critical caveats. It could be split into bullet points for readability, but every sentence earns its place — no filler. The length is justified given the complexity (supported rules, evidential requirements, regression guard, exclusions).

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 no output schema and no annotations, the description does an excellent job of covering everything an agent needs: what it does, when to use it, what the return statuses mean, what constitutes a pass (explicit server evidence for the requested route and both viewports), which rules are supported for passing, what happens for other rules, and how to handle judge/interaction/site checks. It also mentions the regression guard, covering the risk of a fix breaking something else. Very complete.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context about the rule parameter (which rules are supported for passing) and hints at the interaction states for state/form/interaction rules, but does not add substantial new semantics beyond what's in the schema. The description does not mention default values or relationships that are not already present in the schema. Baseline 3 is appropriate.

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

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

The description states the specific verb ('re-check'), resource ('ONE rule on ONE page'), and purpose ('did my fix land?'). It clearly distinguishes itself from a full re-audit by naming the alternative (audit_url) and explaining the difference (one route, no crawl, no judge). The description is not a tautology; it explains the tool's role in the fix-verify workflow.

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 explicitly states when to use this tool (after editing to fix a finding, to verify a specific fix) and when not to use it (for judge, interaction and site checks — says to re-run audit_url for those). It also names the sibling tool audit_url as the alternative. It provides clear conditions: a pass requires explicit server evidence for the requested route and both viewports, and unsupported rules cannot pass. This is explicit and actionable.

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