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

Annotations already indicate read-only and idempotent behavior, but the description adds substantial non-obvious constraints: no page fetch, no JavaScript execution, no live-price verification, no orders, a maximum of 3 offers, input byte limits, and the need to inspect truncated output and warnings. These details go well beyond the 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?

Three tight sentences pack in cost, access, scope, limits, behavioral exclusions, and a routing rule without redundancy. Key selling point 'FREE, no key' is front-loaded, and the alternatives are clearly stated.

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 an output schema present, return values are already covered. The description captures all major constraints and the alternative tool, so an agent can operate safely. The only notable gap is the under-specified baseUrl, which prevents full completeness.

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 0%, so the description must compensate. It explains html by emphasizing 'supplied HTML only' and the 16384-byte limit, and it clarifies maxOffers defaults to 3. However, baseUrl is not described at all, leaving its purpose (likely URL resolution) implicit.

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 resource: 'Extract declared Product/Offer JSON-LD from supplied HTML only.' It also distinguishes itself from siblings by highlighting the free, no-key nature and the limitation to declared JSON-LD without fetching or executing JavaScript, making it clearly different from commerce_offer_extract and html_jsonld.

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?

Provides explicit usage context: 'FREE, no key' and 'No paid fallback.' It also names the alternative route for larger inputs: 'Larger HTML uses commerce_offer_extract after separate spending approval.' This gives an agent clear guidance on when to choose this tool versus a sibling.

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