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

Annotations only say it is a non-read-only, non-destructive write with no idempotency guarantee; the description adds far more — the 402 credits_required shape with 3 packs and buy_url, the rights/terms refusal codes, the returned credits balance structure, and the retry rule of reusing the same idempotency_key and quote_id after a timeout. No contradiction with idempotentHint=false: the client-supplied key is exactly how a non-idempotent call is made safe to retry.

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 first sentence front-loads the verb and the idempotency retry rule is well placed, but the middle is a dense run-on of nested parentheses mixing credits, rights and error codes. The trailing raw JSON argument dump largely restates the 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?

For a nested, expensive, side-effecting tool with no output schema, the description covers the return payload ('credits' with balance, videos_5s_left, low, expires_next, buy_url, message), the failure paths, and the consent/rights lifecycle. Nothing an agent needs to call this safely and report back correctly is missing.

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?

With reported 0% top-level schema coverage, the description compensates by spelling out the argument envelope and the meaning of confirmed, quote_id, max_credits (expressed in credits, taken from the quote) and rights_confirmed. It leaves english, quality, ai_label, resolution and max_charge_cents to the (rich) nested schema, so the marginal value is real but not complete.

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 — "Create one approved video and return its job ID" — and ties it to the approval precondition (confirmed=true after price approval), which cleanly separates it from kelpo_quote_scene (quoting) and kelpo_get_job (polling). An agent knows exactly what this call produces 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 explicit preconditions ('after explicit price approval', quote_id and max_credits come from the quote) and explicit when-nots: 'Kelpo never buys credits by itself', rights_confirmed=true only after the user declared rights, 'already declared files need nothing', and 'never announce a launch from an error response'. It also routes to siblings (kelpo_quote_scene / kelpo_input_requirements) for the requirement lists.

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