Audit submitted HTML against the web-interface rubric

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

Beyond the readOnly/openWorld/idempotent/destructive annotations, the description discloses that nothing is persisted, that URL fetching and browser rendering are server-side opt-ins, and that the report includes an explicit list of what the audit cannot verify. That last point is genuinely useful behavioral framing an agent would not infer from annotations. It stops short of noting whether the audit is deterministic or how partial HTML is handled.

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 sentences, front-loaded with the action and result, then the no-storage guarantee and opt-in caveats. Every sentence carries information, though the closing opt-in sentence slightly duplicates the schema's url and mode descriptions.

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 takes on the job of describing return shape (guideline id, severity, evidence, fix, plus a list of unverifiable items), which is exactly what an agent needs. All five optional parameters are covered by the 100%-covered schema, and the destruction/storage question is answered outright.

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 every parameter is already documented with limits and env-var gating. The description adds only a light restatement ('a fetched URL, when the server allows it') and no new meaning about interactions between html and url, or what maxTokens trades off. 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 names a specific verb and resource ('Check submitted HTML ... against the pinned web-interface guidelines') and describes the return payload (findings with guideline id, severity, evidence, fix). It separates itself from taste_guidelines/taste_get by framing this as an evaluation rather than a retrieval, though it never names a sibling explicitly.

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

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

Usage context is implied through the opt-in caveats: URL auditing only when the server sets TASTEPRO_AUDIT_ALLOW_URL_FETCH, browser mode only with TASTEPRO_AUDIT_BROWSER, and default static parsing. There is no explicit statement of when to pick this over taste_guidelines or taste_search, nor any exclusion beyond the server flags.

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