List a page's images and videos

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds genuinely non-redundant behavior: the cost model ('Free', budgetUsd held while it runs and released) and the auth requirement ('Needs the write scope'). The write-scope note sits in tension with readOnlyHint and the 'Free' framing next to a held budget is slightly ambiguous, which keeps it from a 5.

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?

Roughly 45 words, front-loaded with the resource and scope, then the handoff, then cost and auth. Nothing is padding, though the clipped telegraphic fragments ('fetch_asset the one you want', 'Free: ...') require a beat of parsing rather than reading cleanly.

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 an output schema present the description needn't explain return encoding, and it still adds useful output context (ordering, pixel sizes, per-asset purpose). Required param, cost behavior and auth scope are all covered, leaving only pagination/truncation (>40 entries) unaddressed.

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 100%, so the schema already documents url, viewport, budgetUsd and max_assets in full. The description only restates the budgetUsd default/max, and output-ordering facts like 'largest first' are not a parameter at all, so it adds little beyond the schema — the baseline 3 applies.

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 concrete resource returned (images, videos, logos, social preview card) plus its scope and ordering ('largest first, with real pixel sizes'), so an agent knows exactly what comes back. The verb 'list' is carried by the title rather than the description, and there is no explicit differentiation from near-neighbours like probe_media or screenshot_page, which keeps it just below a 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?

'fetch_asset the one you want' gives a clear follow-on action and effectively routes the agent to the correct sibling once the list is in hand. It states the intended workflow context but gives no exclusions or conditions for choosing this over probe_media or screenshot_page when the goal is merely to know what media exists.

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