Find stock footage

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

Annotations already declare readOnlyHint=false, openWorldHint=true and destructiveHint=false, but the description adds real value beyond them: the budgetUsd hold-and-release mechanic, the explicit 'Needs the write scope' auth requirement, and the B-roll restriction. It says less about failure/refund behavior or what happens on partial matches, which keeps it short of 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?

Terse, front-loaded with the action, then constraints, then cost/auth. Every clause carries information, though the long parenthetical source list makes the opening sentence dense.

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, return values need no explanation, and the annotations plus description cover the write/scope and cost profile. For a mutation tool with an external budget, it is nearly complete, missing only explicit routing to sibling generation tools.

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 all five parameters including source enums and orientation behavior. The description largely restates budgetUsd's default/max and the query word-count guidance already in the schema, adding no new syntax or edge-case meaning, so the 3 baseline holds.

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 (fetch one licensed video clip) and resource, enumerates the source libraries, and notes the destination (media library as a media key). An agent can distinguish this from generate_footage or edit_footage without reading 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?

Provides concrete constraints (B-roll only, no faces/logos/branded property; search in two to four words) that imply appropriate usage, but never names an alternative such as generate_footage, edit_footage or find_photo or states when to prefer them. Usage is implied, not routed.

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