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

Beyond the readOnly/idempotent/openWorld annotations, it discloses that each URL costs 1 extraction from the account quota and that videos are never downloaded or stored — both are behavior an agent cannot infer from annotations or schema. It stops short of saying what happens when some URLs fail or how partial failures are reported.

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 dense sentences, front-loaded with verb and payload, then supported sources, then quota cost and the no-download guarantee. No filler and nothing repeated from the schema.

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 no output schema, the description carries the burden of describing returns, and it does so thoroughly (field list plus best-first ranking of player URLs). The main omission is failure semantics for individual URLs inside a batch, which matters for a multi-URL extraction tool.

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?

With one parameter at 100% schema coverage the baseline is 3, but the description earns extra credit by defining what counts as a valid URL (public pages, named site families, specific markup formats) rather than just repeating the minItems/maxItems constraints already in the 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?

"Extract publish-ready metadata from 1 to 8 video or web page URLs" names the verb, resource and batch scope, and enumerates the output fields (title, description, thumbnail, tags, date, duration, player URLs). Supported sources and ranking order are also stated, so an agent knows exactly what it gets back without opening the 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?

It gives clear conditions for correct use: 1-8 URLs per call, public pages only, and specific site families (YouTube, Vimeo, Dailymotion, or pages with Open Graph/JSON-LD/WordPress markup). It does not point to a sibling for related needs, but get_quota and list_page_entries are not real alternatives to extraction, so the routing gap is minor.

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