List Ideogram operations

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

With no annotations, the description carries the full burden, and it does well: it discloses the shape of what each mode returns (families, operation attributes like model/class/support/quotable, and fields/file limits/rules). It does not confirm read-only semantics or mention auth/rate limits, but the extensive return-content disclosure is strong for a discovery tool.

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?

A single front-loaded sentence using semicolons to enumerate the three modes; nearly every clause carries information. Dense but not wasteful, though the parenthetical attribute list is slightly crammed.

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 two-optional-param catalog tool with no output schema and no annotations, the description adequately covers both invocation modes and the return contents. Minor gaps remain (error behavior for invalid family/operation, no explicit read-only confirmation), but nothing essential to calling 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning by explaining the hierarchical relationship between the two params (omit both for all families, give family for its operations, give operation for one). This drill-down semantics goes beyond the terse schema descriptions.

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 (Discover) and resource (Ideogram's API family/operation catalog) and explains the tiered model, clearly distinguishing it from the operation-execution siblings like ideogram_generate. It stops short of naming those siblings outright, but the 'ready for ideogram_api' phrasing signals its role as the discovery precursor.

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 usage patterns for both modes: no input returns every family, providing family drills into its operations, and providing operation returns one operation's details. It implies the workflow (discover, then feed into ideogram_api) but never states when to prefer this over inspecting ideogram_api directly.

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