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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: it returns credit lines, a total and a quote_id, states no account is required, and notes the quote_id is required by the four generation tools. It does not discuss quote expiry or whether a quote locks in pricing, which is the only material gap.

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?

Purpose is front-loaded in the first clause, then kinds, then return contract, then the two operational notes. Every sentence carries distinct information with no repetition of the schema, despite covering four modes.

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 an 8-parameter tool with nested brief/storyboard objects and an output schema, the description covers mode selection, downstream consumption, auth needs, and input consistency. Return values are properly left to the output schema, though the brief/storyboard precedence could have been spelled out slightly more explicitly.

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 would be 3, but the description adds real meaning: it ties the kind enum values to their artifact types and warns "For an ad, quote exactly the fields you will submit," which is a parameter-consistency rule the schema cannot express. The storyboard/brief interaction is also clarified.

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 (price/quote) and resource (a studio job), then enumerates all four kinds and maps each to the concrete artifact it prices. It even names the sibling generators that consume the quote_id, so an agent can distinguish it from generate_ad, decode_ad, and estimate_credit_cost without opening a 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?

"Price a studio job before making it" gives clear timing context, and it explicitly names the downstream tools that require the returned quote_id, telling the agent when this call is mandatory. It does not, however, contrast itself with the sibling estimate_credit_cost, so the alternative-tool dimension is left implicit.

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