Hermoso models, options and credit costs

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real context: the snapshot is live ('RIGHT NOW'), costs are estimates while renders are charged actual cost, and the call is free. It also signals no permissions or side effects are involved. Only the redundancy of 'Read-only' with readOnlyHint keeps it from a 5.

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 capability payload, then the usage trigger, then the negative constraint. Every clause carries information — the field enumeration and the 'not a prerequisite' caveat both earn their space; no filler or restated title.

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 and no parameters, the description compensates by listing the returned capability fields and clarifying the estimate-vs-actual charge semantics, which is the one thing an agent could misread when budgeting credits. Nothing needed to call it 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?

The tool takes zero parameters, so there is nothing to disambiguate and the schema is trivially complete. The description correctly spends no space on parameter explanation and instead describes the result shape.

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?

Names a specific verb and resource ('Probe what this Hermoso account can do') and enumerates exactly what is returned: model ids, credit costs, aspect ratios, video durations, recipe ids, canEdit/canAvatar flags. This lets an agent distinguish it from hermoso_credits (balance), get_settings (config) and find_tools 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?

Explicit trigger conditions ('when you need a specific model id, a credit cost, or a capability you are not sure of') plus an explicit exclusion: it is NOT a prerequisite for rendering because generate_image, generate_video and render_ad route to a server default when `model` is omitted. That prevents the most likely misuse.

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