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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the description is not carrying the safety burden. It adds genuinely structured context the annotations do not: the required read_usage scope, the exact meaning of credit_cost (what the generate call will debit per provider), and the is_default fallback rule for unpinned items.

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?

Three sentences, front-loaded with purpose and cost, then field semantics, then prerequisite scope. The dense parenthetical about credit_cost earns its place because the tool has no output schema to explain the field elsewhere.

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?

With no output schema, the description must describe the payload — and it does, listing the fields returned and the is_default rule. Auth scope, cost semantics, and cross-endpoint relationships are all present, leaving nothing an agent needs to call this correctly.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and schema coverage is moot. The description instead spends its space documenting the response shape, which is appropriate, though field-level semantics are partial (release_stage and format values are not explained).

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?

First sentence states the specific resource (generation options for this account) and the key attribute (credit cost), which clearly separates it from listCreditLedger, getMe, and startGeneration. It also enumerates what each option carries (credit_cost, release_stage, image limits, output formats, is_default), so an agent knows what it gets without opening anything else.

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?

"Read before spending" gives an explicit trigger tied to the paid generation path (POST /v1/items/{id}/generate), and the note that GET /v1/items/{id} returns generation.estimated_credit_cost tells the agent when per-item costing should come from getItem instead. Both the when and the alternative are named rather than inferred.

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