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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description still adds real value: the BYOK credential requirement, the exact failure mode (byok_key_required, not charged), the fact it never fetches, and the source-attribution obligation when presenting results. What is missing is any hint about non-LLM extraction behaviour (heuristics, formats, evidence) so the agent cannot predict output shape when extraction_prompt/schema are omitted.

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 purpose, then when-to-use, when-not, prerequisite, and an output caveat — a logical order. It is dense but nearly every sentence carries operational weight; the closing attribution instruction is the only sentence that leans toward incidental housekeeping.

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 13-parameter, no-output-schema tool the description covers the high-stakes concerns: no fetching, the sibling alternative, the credential gate and its error, and a presentation constraint. It is not fully complete because the non-LLM extraction path and the roles of the remaining parameters (formats, evidence, cache, source_url, model/provider/profile/template) are left unexplained.

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 only 46% across 13 parameters, so the description should compensate more than it does. It clarifies extraction_prompt and extraction_schema (LLM dependency, BYOK, rejection behaviour) but says nothing about content_type, formats, evidence, cache, source_url, extraction_model, extraction_provider, extraction_profile or extraction_template, leaving most of the surface to the sparse schema.

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?

Opens with a specific verb and resource: 'Turn content you already hold (HTML, text or markdown) into structured JSON fields'. It also enumerates concrete field categories (prices, product info, contact details, custom fields) and explicitly separates itself from alterlab_scrape, so an agent can route correctly without opening either 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 when-to-use ('Use when you have content and need specific fields') and an explicit when-not plus alternative ('Does not fetch a URL: to fetch and extract in one step, use alterlab_scrape with extraction_schema'). It also names the prerequisite that unlocks the LLM path, which is the main selection risk for this tool.

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