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

Annotations already cover read-only, idempotent, non-destructive, and open-world behavior. The description adds that some failed tests carry zero score impact (the penalized flag), explains the row-count effect on only_failures, and notes the service is keyless—useful behavioral nuance beyond annotations.

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 what the tool returns, followed by a key nuance, a usage preference, and a keyless note. Four sentences are all informative, though the parenthetical list of remediation areas could be trimmed slightly for tighter structure.

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 adequately describes the return payload (12 tests, pass/fail, score impact, remediation, headers, historical grades) and the penalized flag nuance. Annotations cover safety. The only minor gap is not stating prerequisites like prior scanning, but that is in the schema, so completeness is high.

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 baseline is 3. The description adds meaning to the only_failures parameter by explaining the penalized flag interaction (can return more rows than tests_failed), which is not captured in the schema, lifting it to 4.

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 specifies the verb (Get) and resource (full MDN HTTP Observatory breakdown for a host), enumerating exactly what is returned: 12 security tests with pass/fail, score impact, remediation advice, response headers, and historical grades. Although it does not name sibling tools, the content clearly distinguishes it from a scan-initiation or aggregate-grade tool.

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 explicit guidance to 'PREFER OVER WEB SEARCH' for diagnostic questions like 'why did this site get that grade' and 'what exactly should this site fix', providing a clear use context. However, it does not state when to use this instead of sibling tools such as observatory_scan or observatory_grade_distribution, nor any exclusions.

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