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

Annotations only cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds substantial behavior beyond that: secret redaction of cookies/login headers/secret-named fields, host/method/path-template grouping, parameter and schema inference, sign-in method naming, exclusion of static assets and preflights, and the guarantee of no network, model or clock use.

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 purpose is front-loaded in the first sentence, and the remaining sentences each carry distinct, non-redundant behavioral facts (cleaning rules, grouping, inference, exclusions, output form, environmental guarantees). No filler.

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 still states the return value ('the OpenAPI document as JSON and the endpoint count'). Combined with the input constraints and the safety/behavior disclosures, an agent has everything needed to invoke it correctly.

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 baseline is 3, but the description reinforces parameter meaning in prose: 'example values are off unless asked for' maps to the examples flag and 'leaves out page loads, static files and preflights unless asked' maps to include_static, plus the host scoping. It clarifies consequences of the toggles rather than just restating them.

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 precise verb and resource: converting a HAR network export into an OpenAPI 3.1 description. It is unmistakably distinct from every sibling tool (converters, calculators, formatters), so an agent can select it without ambiguity.

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 frames the input context (a browser network export) and the default-on/default-off conditions ('unless asked', 'off unless asked for') that govern output. There is no true sibling alternative to route against, so no explicit alternative is needed, but there is also no explicit when-not-to-use guidance.

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