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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description goes beyond them by disclosing cost (~5 credits / $0.05), the payment mechanisms (prepaid key or x402), and the failure behavior ("invalid input is refused"). It is slightly thin on what happens when the optional schema cannot be satisfied and defers the require_llm payment consequence to a billing note rather than stating it.

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?

Four sentences, zero filler: purpose, routing rule, input contract, then output/cost/error behavior. The most decision-relevant information (what it does, and the sibling it is not) is front-loaded in the first two sentences.

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?

For a 5-parameter, nested-schema, paid tool with an output schema present, the description covers everything the output schema does not: cost model, routing decision, input mutual exclusivity, and error posture. Nothing an agent needs to invoke it correctly is absent.

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 coverage is 100%, so the baseline is 3, but the description earns an extra point by condensing the critical structural constraint into prose — "exactly one of text or html" — which reinforces the oneOf in a form an agent will not skim past. It also frames the other three as optional, which matches the zero-required-parameter reality.

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 specific verb and artifact ("Extract structured JSON") plus an explicit enumeration of what can be pulled out (emails, phones, URLs, key-values, schema-shaped fields) and the source material (messy plain text or HTML). It also distinguishes itself from extract.webpage in the same breath, so an agent can route 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 positive trigger ("agent already has document text/HTML and needs machine-readable fields for the next step") and an explicit negative case with the correct alternative named ("not for fetching a live URL (use extract.webpage)"). This is the when/when-not/alternative pattern at full strength.

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