Review Broll Placements

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it rejects overlapping approved placements and enforces explicit decisions, and the schema clarifies that unselected entries remain pending. It stops short of describing revision-mismatch handling in detail.

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 tightly packed sentences: the first defines the operation and inputs, the second states the overlap rule, and the trailing clause lists excluded behaviors. Front-loaded and largely waste-free, though the single dense sentence carries a lot of clauses.

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?

An output schema exists, so return values need not be explained. For a decision/review tool the description covers scope, overlap rejection, and non-insertion clearly; combined with rich annotations and full schema coverage, the agent has enough to call it correctly.

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 itself documents all four parameters thoroughly (including revision requirements and pending/approval semantics). The description restates the field categories (quote, reason, alternatives, revisions, decisions) without adding syntax or format detail beyond the schema, which is the expected baseline.

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 ('Review') and resource ('caller-proposed owned-footage B-roll picks'), then enumerates the evidence considered (quote, reason, alternatives, source/sequence revisions, explicit decisions). It also names what it is not, distinguishing it from review_dialogue_candidates and stock-search tools.

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 scope boundaries ('Does not infer visual content, search stock, inspect track occupancy or insert clips') that tell the agent when this tool is the wrong choice. However, it never explicitly names a sibling alternative or the condition that would route the agent to review_dialogue_candidates instead.

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