Quote clip job cost

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

Annotations cover the read-only/idempotent/no-destructive profile, but the description adds substantial behavioral context beyond them: the pricing formula (1 credit per started minute, minimum 1), that options like caption style/hooks/B-roll do not affect price, the 30-minute job cap, and the upper-bound case where credits_exact is false because the API does not reveal a recut's original range.

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 key value proposition ('without spending anything', 'Free and read-only') and organized into pricing/usage/return paragraphs. It is dense and slightly long, with a few return-value details that partly overlap the output schema, but almost every sentence carries actionable information.

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 pre-flight quoting tool this is complete: it covers when to use it, the cost model, the interaction between job_id and the range parameters, the credit-exactness caveat, and the failure mode for unmeasurable direct links. The output schema exists, so return-value enumeration is a minor redundancy rather than a gap.

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 coverage is 100%, so the baseline is 3, but the description genuinely extends semantic meaning: it explains that a recut without start_sec/end_sec reuses the original job's range and yields an upper-bound quote, that omitting both defaults to the whole video (requiring a length lookup), and that the 30-minute cap forces splitting long videos.

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+resource ('Calculates the credit cost') and explicitly names the sibling operations it prices (create_clip_job, recut_clip_job) while distinguishing itself as a no-cost simulation. An agent can tell this apart from create_clip_job/recut_clip_job without opening either 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 explicit routing: pass source_url to price a new video, job_id to price a recut, and states the prerequisite workflow ('Show the credits to the user and get their agreement before calling create_clip_job or recut_clip_job with max_credits of at least this amount'). It also notes a fallback when the length cannot be determined.

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