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

Goes well beyond the readOnly/openWorld annotations by disclosing that the call is free, that `quote_id` expires after 15 minutes, that the key must carry the `read` scope, and that the returned price is the exact charge if the id is reused. Rate/TTL/auth/cost traits are all surfaced.

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-loads the most decision-relevant fact ('Free') and keeps sentences tight. Slightly diluted by the trailing 'Prices are the service defaults; `quote` returns the exact price,' which largely restates the earlier pricing sentence.

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?

No output schema exists, yet the description names the return shape (price, per-video lines, per-source rejections), the pricing basis, the id lifecycle, and the auth requirement. An agent has everything needed to call and interpret it without guessing.

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, but the description adds constraints the schema does not encode: 'At least one of url, urls, channel_url, channel_urls' on a schema whose required list is empty, plus the rule that videos already in a supplied collection are free. It does not explain `max_videos_per_channel` defaults beyond what the schema already says.

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+resource+output: 'Expand YouTube URLs exactly as an ingest would and return the price, the per-video lines and the per-source rejections.' The mapping to POST /v1/quote and the pricing semantics make it unmistakably distinct from transcribe (which actually charges) and query_channel/query_collection.

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 clear operating context: it's free, the `quote_id` is passed to `transcribe` or `add_sources` to lock in the price, and `collection_id` prices against an existing collection. It does not explicitly state when NOT to bother quoting (e.g., trivial single-video flows) or contrast against sibling pricing paths, so it stops short of full routing guidance.

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