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

With no annotations, the description carries the whole burden and does well: it discloses per-request cost (€0.005), the 4,000-character billing unit, and that charges hit the API key in the Authorization Bearer header. It also states output conventions (nulls for missing values, ISO dates, numeric numbers). Remaining gaps are failure modes and what happens with no source input, since all four parameters are optional.

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 output shape and input modes come first, pricing and auth next, then a compact parameter glossary. It is telegraphic but every clause carries information. Slightly dense, with list-style parameter notes rather than prose, but nothing is wasted.

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?

The tool has an output schema, so return values need not be described, and the description correctly spends its space on inputs, cost, and auth instead. For a four-parameter, all-optional extractor, the only meaningful omission is guidance on required input combinations and error behavior.

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, and it does: all four parameters get meaning, including the important insight that schema accepts either a JSON Schema object or a comma-separated field list, and that url is an alternative to text. It doesn't resolve the all-optional ambiguity or specify character limits per source.

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 names the action and resource concretely: pull structured data out of free text, email, or a web page, shaped by a JSON Schema or field list. That separates it from fixed-schema siblings such as invoice_parse or table_extract. It stops short of explicitly naming which sibling to prefer, so it sits at 4 rather than 5.

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 establishes the input alternatives (text vs. url as 'alternative') and the schema-vs-field-list choice, which is real usage guidance. It never states when to prefer a specialized sibling over this generic extractor, nor what happens if both text and url are omitted. Usage is implied rather than prescribed.

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