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

Annotations already cover the read-only/idempotent safety profile, and the description adds substantially beyond them: the API key requirement, the 15-minute expiry of catalog=mine links and the links_expire_in_sec field, divergent return shapes per catalog, the fact that shared items are downloaded off-site, and that provider text is wrapped in <untrusted_source_text>. This is unusually rich operational detail an agent needs to sequence calls correctly.

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-loaded with the action and the key routing decision in the first sentence, then the catalog-specific return details. Dense but every sentence carries information; it is slightly longer than strictly necessary because the return-value details duplicate the output 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?

Given the presence of an output schema, the description need not explain returns, yet it still clarifies the divergent shapes per catalog plus the expiry semantics and untrusted-text handling. Everything an agent needs to call this correctly and interpret the result is present.

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 both parameters are already documented in the schema. The description's constraint that 'catalog must be the catalog the asset_id came from' reinforces the pairing but largely restates the schema's own wording, adding no new syntax or format information. Baseline 3 is appropriate when the schema carries the load.

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 ('Returns one B-roll item by asset_id with fresh links') and immediately distinguishes itself from the sibling search_broll, which is a finder rather than a fetcher. An agent can tell exactly what this does 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?

Gives an explicit when-to-use rule ('right before downloading an item found with search_broll'), the reason (catalog=mine links expire after 15 minutes), and an explicit when-not-to-use routing ('to find items use search_broll instead'). This is the full when/when-not/alternative triad.

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