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

With no annotations, the description carries the full behavioral burden, and it does so thoroughly. It discloses the return metadata (qualityScore, grounding, progress, credits), clarifies the limits of grounding ('does not establish factual truth or correct field association'), states authentication requirements, explains rendering behavior and its credit cost, and notes caching nuances (via the maxAge parameter). This is a model of transparent disclosure.

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 dense but well-structured: it leads with the core action, then lists return fields, then covers auth and exceptions, and finally notes limitations and costs. Every sentence adds information; there is no fluff. It is longer than typical because the tool is complex, but it earns its length. A minor deduction for density, but it remains efficient.

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 tool with six parameters, one nested object, and no output schema, the description covers almost everything an agent needs: how to specify extraction, what is returned, grounding limitations, authentication, rendering options, caching, and credit charges. It even mentions the /llms.txt special case. The only minor gap is error handling, but that is not essential for correct invocation. It is effectively complete.

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. The description adds value beyond the schema by explaining the two complementary ways to specify extraction: natural language (extract) and JSON Schema (schema), and how they can be combined ('and/or'). It also adds auth context not present in the schema. This exceeds the baseline but doesn't dive into each parameter's format since the schema already handles that.

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 opens with a precise verb and resource: 'Extract structured data from one public web page.' It also explicitly disambiguates from related tools by stating 'Not a crawler or a search engine: one page per call,' which clearly separates this extraction tool from any sibling that might handle crawling or broad searching. The purpose is unmistakable.

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?

The description gives clear context for when to use the tool: it is for single-page extraction, not crawling or searching. It also specifies a conditional usage: 'Eligible JavaScript shells can use bounded browser rendering,' and notes that exact recorded requests from /llms.txt work without an API key. However, it does not explicitly name sibling tools or contrast with contrie_read or contrie_verify, so the guidance is strong but not fully explicit about alternatives.

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