Embedfinder

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.

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and open-world. The description adds genuinely useful context beyond them: the call costs no quota and the reset window varies by plan. It does not describe the return shape or edge cases like exhausted quota.

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?

Two short sentences, front-loaded with the core question and followed by the plan-dependent period and cost note. No padding or redundancy.

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 zero-parameter read tool with no output schema, the description covers the essential semantics: what is counted, the period, and that it is quota-free. Only the exact return format or exhaustion behavior is left unstated, a minor gap.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds that the period granularity is determined by the plan rather than an argument, which preempts any attempt to pass one.

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 quantity (remaining extractions) and the period it applies to (day or month depending on plan). It is clearly distinct from the siblings extract_video_metadata and list_page_entries, though it doesn't explicitly name them.

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 implies usage ('how many left in the current period') and notes the call is free, which hints at when to check before running extractions. It doesn't explicitly say when to call it versus other tools or how to act on the returned number.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so safety is covered. The description adds genuinely new behavioral facts: billing cost ('Uses 1 extraction') and a plan-dependent truncation rule ('On the free plan it returns the first 10 entries and the total'), which an agent cannot infer from structured fields. It stops short of describing ordering guarantees beyond 'site order' or failure behavior for non-listing URLs.

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 short sentences, zero filler, with the resource and scope front-loaded and the chaining instruction placed before the cost/limit caveats. Every clause carries operational information.

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?

There is no output schema, so the description must describe the return payload, and it does: entry URLs in site order, the next page if present, and the total on the free plan. Combined with the cost disclosure and the handoff to extract_video_metadata, an agent has everything needed to invoke and chain it.

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% and the single parameter is documented as a URI, so the baseline would be 3. The description earns the extra point by constraining what that URL may be — a category, archive, playlist, or listing page — narrowing the accepted input beyond the schema's generic 'Public URL of the listing page'.

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 and resource ('return the URLs of the individual entries' of a 'category, archive, playlist or listing page'), and enumerates the page kinds it accepts, which no sibling does. An agent can distinguish it from extract_video_metadata because the description explicitly frames this tool as the producer of URLs that the other consumes.

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 context for when to reach for this tool and names the follow-up step ('Pass those URLs to extract_video_metadata'), so sequencing is unambiguous. It does not state any exclusion or when-not-to-use condition, which keeps it short of a 5.

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