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

While the annotations already indicate a read-only, harmless operation, the description adds critical behavioral context by revealing endpoint-specific limitations (URL capture disabled) and disclosing the operational constraint that 'nodes' is the only supported input in this environment. It could have been a 5 but the description is somewhat verbose in its repetition of the URL warning, and it doesn't disclose any potential performance considerations.

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 information-dense but somewhat bloated with repetition: the URL-disabled warning appears twice, and the caveat could have been stated once cleanly. The opening sentence is front-loaded, but the repeated 'audit_typography url-capture is disabled on the hosted (remote) endpoint. Pass a 'nodes' snapshot instead of 'url'.' is redundant duplication.

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 the tool's moderate complexity with an array input with nested properties, both the description and schema work together to cover the two parameters completely. The description compensates for potential misuse by the super-user (URL) being unavailable, and the output structure is clearly defined. The sibling differentiator (audit_page) is also named.

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%, with a clear description for each of the two parameters. The description itself adds conceptual rationale for 'nodes' by explaining it's for pre-collected snapshots, but the main semantic value of the parameter purpose comes from the schema. The description primarily repeats the URL rejection warning already present 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?

Clearly states it audits typographic scale with three specific checks (modular scale, line-height, weight ladder) and names the sibling tool (audit_page) it extends. The inclusion of output structure and the explicit scoping to nodes vs URL further clarify its exact purpose.

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 tells users when to use this tool (to go beyond audit_page's pass/fail checks) and provides a strong, repeated warning that URL mode is disabled on the hosted endpoint and that nodes should be passed instead. This is excellent when-not-to-use guidance considering the schema already documents each parameter in detail.

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