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

Annotations cover the safety profile (readOnlyHint, destructiveHint=false, openWorld), and the description adds value beyond them: it discloses the return payload shape, a lint verdict against a pinned linter version, token/styleheet counts, and names five concrete error codes with the promise each one indicates the next input. The only soft spot is the word 'Writes', which is clarified a sentence later as returning markdown text rather than persisting a file.

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 verb and artifact, then ordered Best for / Returns / how to pass url / Do not use for / Errors. Dense but every clause carries routing information; the url example duplication is the only mild 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?

An output schema exists, yet the description still summarizes the payload categories and enumerates the failure modes and their classes, which is exactly what an agent needs to pre-decide feasibility. Nothing needed to call 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 description coverage is 100%, so url grammar, bare-host defaulting, and the include_raw_css/max_stylesheets limits are already documented. The description restates the url example and bare-host rule but says nothing about include_raw_css or max_stylesheets, so it adds little beyond the schema — baseline 3.

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 and artifact ('Writes a starter DESIGN.md file from the CSS of one public webpage'), and scopes it to exactly one page. It also names the sibling it is not (lint_design_md), 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 an explicit 'Best for' trigger (user supplies a website address and wants colors/fonts/spacing/radii/components as DESIGN.md) plus explicit exclusions: login pages, private/local addresses, robots-disallowed pages, and existing DESIGN.md files, with the alternative named for the last case. When/when-not and the routing rule are all present.

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