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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it discloses the credit cost ('SPENDS THE ACCOUNT OWNER'S CREDITS'), that a new copy is saved and the original retained, expected latency (5 min for 15 s, up to 15 min for 60 s), and the deliberate no-retry policy on ambiguous outcomes. This is exactly the extra context annotations cannot carry.

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 cost warning is front-loaded in caps, followed by the ordering constraint, side-effect guarantee, latency, and retry rule. Every sentence carries distinct actionable information with no padding.

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 paid, non-idempotent, no-output-schema mutation tool, the description supplies the cost, the prerequisite quote, the parameter-consistency rule, the side-effect guarantee, latency expectations, and the exact recovery tool. Nothing an agent needs before invoking or after failing 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds relational semantics the schema cannot: the four values must match the quote exactly, requestId is the quote's id and must be reused on repeats, and expectedCredits is treated as a verified price rather than a request. That meaningfully elevates it above the schema-only 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?

The description states a specific verb and resource (add effects to a video), and immediately distinguishes this operation from its siblings by naming soclo_motion_effects_quote and soclo_motion_status as the prerequisite and the recovery path. An agent can tell what this tool does and where it sits in the workflow without opening any 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?

It gives explicit when-to-use ('Only after the owner approves the price from soclo_motion_effects_quote'), when-not-to-use ('If the outcome is unknown, do NOT make again'), and names the exact alternative (soclo_motion_status with the original requestId). That 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.