quote_frames

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

With no annotations supplied, the description carries the full burden and does so well: it discloses zero deduction, the exact return fields, price tiering by model/resolution, price_breakdown content, and the consequence of mismatching image_model. It also reveals the default model/level assumption when image_model is omitted.

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?

The description is front-loaded with the core purpose, then presents return values, frame_type options, and the pricing caveat in a compact, scannable format. Every sentence contributes necessary information with no filler.

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 tool with no output schema and no annotations, the description covers the important operational details: what is returned, what costs nothing, how frame_type selects shots, and how to keep pricing consistent with generate_frames. It could be slightly stronger by stating explicitly that the returned quote_id is meant to be used with generate_frames, but the connection is strongly implied.

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 schema already covers frame_type and image_model, and the description adds meaningful detail: the precise conditions for first_frame/last_frame/both and why image_model must match generate_frames. episode_id remains lightly described, but the purpose statement identifies it as the episode being quoted.

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 clearly states the operation: quoting how many points are needed to batch-generate frames for an episode, and names the key response fields (frames_to_generate, estimated_points, quote_id). It is specific enough to distinguish from shot-level or scene-level quotation siblings, though it does not explicitly name an alternative.

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 actionable context: explains frame_type semantics with default behavior, and instructs that image_model must match the one later passed to generate_frames or the prices will differ. It does not explicitly state when to use quote_frames versus quote_shot_frame or quote_scene_images, so it stops short of a full 5.

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