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

With no annotations, the description carries the full burden and largely meets it: it discloses that results are written to an output directory, that long jobs return a generation_id rather than blocking, and that quoting is available before calling. It omits any note on permissions or cost of the num_images outputs, which the schema covers only in passing.

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 core purpose and appropriately sized for a multi-parameter tool, though the semicolon-chained phrasing packs several distinct ideas into single sentences and is dense to parse. Every clause is informative, so little is wasted.

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 11-parameter tool with no annotations, no output schema, and a nested asset identifier, the description covers purpose, accepted inputs, output destination, and the async follow-up path. It is close to complete, missing only explicit required-parameter guidance and any auth/permission note.

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 baseline is 3, but the description adds real meaning by explaining the per-language semantics of `language`, the accepted sources for `image` (local file, https URL, Ideogram asset), and the line-by-line `original => replacement` shape of exact_copy. It goes modestly beyond the schema rather than merely echoing it.

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 definition states a specific verb and resource — translate an ad's copy into one target language — plus a precise scope (one language per request). It clearly separates this from siblings like ideogram_ad_resizer and ideogram_ad_variations by naming exactly what is preserved (layout, logos, brand type, product).

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 concrete usage context: one request per language, Arabic renders right-to-left, exact_copy pins pre-approved wordings, and ideogram_quote prices a call first. It routes to ideogram_generation for long-running jobs, but never states when to prefer this over sibling ad tools such as ad_variations, so it stops short of explicit alternatives.

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

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

With no annotations, the description carries the burden and does a decent job: it states that results are written to the output directory rather than returned inline, and that long-running jobs surface as a generation_id rather than a finished image. It doesn't disclose billing/permission implications or what happens to the source creative, but the operational behavior is well covered.

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 dense sentences, front-loaded with the core action before input formats and downstream routing. Every sentence carries information, though the parenthetical lists make it slightly heavy.

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 10-parameter tool with no output schema, the description covers input formats, output destination, async fallback, and the related pricing/generation tools. The main omission is guidance on sibling selection among the other ad/edit tools.

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 schema already documents all ten parameters in detail. The description reinforces a few points (resolution must come from the list, platform selects the safe zone, the creative can be a file, https URL, or Ideogram asset) but adds little beyond what the schema states. Baseline 3 is appropriate.

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 and resource ('Reframe an ad to a platform's exact ad size') and scopes it tightly to ad sizing with the platform safe zone, which separates it from the general ideogram_reframe sibling. An agent can identify the job without opening the 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?

Gives clear routing context: use ideogram_quote to price first, and that long jobs hand back a generation_id for ideogram_generation. It does not explicitly say when to prefer this over ideogram_reframe or ideogram_ad_localizer, so the sibling distinction is left implicit.

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

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

With no annotations, the description carries the full load and does meaningful work: results land in the output directory, long jobs return a generation_id to continue via ideogram_generation, and the job is never resubmitted or billed twice. Missing are permission/enterprise nuances and any failure-mode notes, but the async/billing contract is disclosed.

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 paragraph leads with the operation and its invariant, then moves to I/O and async behavior. Nearly every clause earns its place, though the source-format list slightly duplicates the schema's own image description.

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?

There is no output schema, and the description compensates by explaining where results are saved and what a generation_id means for long jobs. For a 9-parameter, no-annotation tool this is close to sufficient; minor gaps remain around the asset-identifier path and billing for num_images (covered only in the schema).

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 already 100%, so the bar is a baseline 3, but the description adds real semantics beyond the schema: only one axis is varied while aspect ratio and product are preserved, and the image can be a file, URL, or Ideogram asset. The oneOf/required-variation_type structure is not explained, but the core parameter intent is enriched.

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 first sentence gives a specific verb (vary) and resource (an ad) plus the exact axes (people, setting, group_size, scene) and what is held constant (aspect ratio, product). That is enough to distinguish it from siblings like ideogram_ad_localizer, ideogram_ad_resizer, or the plain ideogram_generate 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 states the operative constraint up front ('vary an ad along ONE axis'), names the accepted source forms (local file, public https URL, Ideogram asset), and notes there is no price quote or dry run, which implicitly routes costing questions to ideogram_quote. It stops short of explicitly naming alternative siblings or stating when to prefer remix/edit over this tool.

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

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

With no annotations, the description carries the full burden and does disclose real behavior: the request is validated against the operation's own schema before anything is sent, and dry_run prices instead of executing. It stops short of stating auth requirements, that this path bypasses curated safety rails, or what happens on validation failure — meaningful gaps for a tool that can dispatch arbitrary (potentially mutating) operations.

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 dense paragraph, front-loaded with the routing condition before the mechanics, and every clause carries information. Slightly compressed — the params/files/validation/dry_run points run together — but nothing is wasted.

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?

No output schema exists and the description does not describe return shape, but for a generic dispatcher whose response depends on the target operation that omission is understandable. Invocation mechanics, pre-flight validation and the dry_run alternative are all covered; error behavior and result-retrieval expectations are the main unaddressed items.

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 schema already documents operation, params, files, wait_s, dry_run, inline_images and allow_undocumented. The description explains the params split into path/query/headers/body and the files path-or-URL mapping, but this largely restates what the schema's own descriptions say. Baseline 3 is appropriate.

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 precise verb and resource — call an Ideogram operation by id — and immediately positions it as the escape hatch ('when no curated tool covers it') against the 35+ curated siblings. An agent can tell instantly that this is the generic fallback, not a competing generator.

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 selection criteria: use when no curated tool covers the case, for an undocumented model (allow_undocumented), or when the call needs webhook_url / target_collection_id. It also names where the operation id comes from (ideogram_operations), so the agent knows the prerequisite call.

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

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

With no annotations, the description carries the full burden and does well: it discloses the auth requirement ("an API key whose owner is an organization admin"), the redaction of key material, the sort order, and the read-only nature ("Reads only"). Pagination and rate limits are unmentioned, keeping it out of the top band.

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 carrying scope, ordering, redaction, auth, and read-only status with no filler. Every clause earns its place.

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 zero-param listing tool with no annotations and no output schema, the description covers return shape (redacted material, ordering, join key to usage) and safety (read-only) sufficiently. Minor gaps like pagination remain but are not critical.

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 the parameter baseline is 4. There is no parameter information the description could add or omit.

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 names a specific resource ("The API keys in your organization") and adds scope and ordering ("newest first"), so an agent knows this is a listing of org API keys. It differentiates itself from the usage report by explaining the id/prefix cross-reference, but the phrase is noun-led and doesn't sharply distinguish from sibling ideogram_api.

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?

Usage is implied rather than stated: the admin-owner prerequisite and the cross-reference to the usage report hint at when this tool is relevant. However, there is no explicit when-to-use/when-not or routing to an alternative sibling.

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

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

With no annotations, the description carries full burden. It discloses input formats, that results are saved to the output directory, that long jobs return a generation_id for ideogram_generation, and that ideogram_quote prices a call first. However, it omits permissions, reversibility, rate limits, and whether the original photo is modified.

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 description is compact, front-loaded with the core action, and every sentence adds useful information about inputs, outputs, and related tools. No filler or redundancy.

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 complex tool with no output schema, the description covers what it does, accepted input formats, where results go, and async handling. It does not describe the output artifact format (e.g., image files vs. base64), but the key operational details are present.

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 schema already documents all parameters; baseline is 3. The description adds minor value by reiterating the mask-to-colour positional pairing and accepted input types, but does not introduce meaning beyond the schema.

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 and resource ('Recolor a product photo') and details the mechanism (up to 4 masks paired with hex colours, everything outside preserved). It does not name or contrast with any sibling tool, so it falls short of the highest tier, but an agent can still identify the task unambiguously.

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?

The description offers no guidance on when to use this tool versus alternatives like ideogram_material_swap or ideogram_edit. It provides procedural notes about long jobs and quoting, but nothing about selection criteria or exclusions.

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

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

With no annotations, the description carries the full burden, and 'Reads only' usefully declares the non-mutating nature. It also discloses the shape of returned data, but omits pagination/limit behavior, ordering, and what happens when a search or id matches nothing.

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 dense sentence that front-loads the resource and separates the list mode from the detail mode with no wasted words. Nothing to trim.

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 correctly compensates by naming what a dataset record contains (files, captions, trained models) and flags read-only behavior. Missing only edge-case behavior (empty results, large lists) for a low-complexity two-parameter read tool.

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%: the schema already documents search as a case-insensitive substring and dataset_id as the single-record selector. The description restates these without adding syntax, format, or defaulting details, so the baseline 3 applies.

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 resource (training datasets) and two clear modes: list or single-dataset-by-id, with the returned payload enumerated (files, captions, models). It distinguishes itself from ideogram_dataset_upload implicitly, but never names a sibling to route between them.

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?

'Optionally searched by name' and 'one dataset by id' imply when each mode applies, so usage is inferable. However, there is no explicit when-to-use vs alternatives (e.g., ideogram_dataset_upload for writing, ideogram_models for model listings) and no stated prerequisites.

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

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

No annotations, so the description carries full burden. It usefully discloses the accepted-vs-failed reporting behavior and accepted source types, which is genuine context. It omits permissions, per-file size limits, and rate constraints, so coverage of behavioral traits is partial.

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 verb and kept to one dense sentence plus a short one, with every clause (formats, caption pairing, dataset modes, path types) doing work. The opening sentence is long but not padded.

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 multi-mode file-upload tool with no output schema and no annotations, the description covers inputs, accepted formats, target-dataset selection, and the shape of the result (what was accepted/failed and why). Missing only minor operational details such as auth and file-size limits.

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 all three parameters are already documented with the dataset_id/name relationship, the caption-pairing rule, and the 100-image cap. The description mostly restates this framing rather than adding syntax or format details beyond the schema, so the baseline 3 applies.

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 (Upload) and resource (training assets into a dataset), and enumerates accepted file types. It is unmistakably distinct from the generation/editing siblings, though it never names an alternative, so no explicit sibling differentiation.

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?

Explains the two upload modes (existing dataset via dataset_id vs new one created from name) and supported sources (local paths or public https URLs), implying when to use each. However there is no guidance on when to reach for this versus ideogram_datasets or ideogram_train, and no prerequisites are stated.

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

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

No annotations are supplied, so the description must carry behavioral load, and it does disclose two non-obvious traits: the output format depends on the model (words vs structured JSON), and there is no dry-run/price quote for this operation. It stops short of auth needs, rate limits, or return-shape detail.

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 short sentences with the core purpose front-loaded. The parenthetical model-versioning and the pricing aside are slightly digressive but each carries information an agent needs, so the size is justified.

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 6-parameter tool with branchy oneOf variants and no output schema, the definition is adequate but thin: it never characterizes the return value beyond 'words' or 'structured JSON prompt,' and leaves the ideogram-4 flags (include_bbox, include_tags, include_style_descriptions) entirely to the schema. Nothing critical is missing, but the description does not fully compensate for the absent output schema.

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 already 100%, so the baseline is 3, but the description adds meaning the schema lacks: it states the accepted input sources (local file, public https URL, Ideogram asset) and, more importantly, that the 'model' value determines the output form. That is genuine added value over the variant schema, which only says 'each takes the fields of its variant below.'

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 and resource ('Describe an image') and crucially distinguishes the two model modes: Ideogram 3.0 returns words while 4.0 returns a structured JSON prompt. It does not, however, name or differentiate itself from near siblings such as ideogram_magic_prompt or ideogram_generation.

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?

Usage is only implied by the operation itself. The one routing hint given is indirect ('Describe has no price quote'), which tells the agent not to expect pricing but does not say when to choose describe over other text-producing or generation tools.

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

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

No annotations are provided, so the description must carry full behavioral disclosure. It discloses deprecation and equivalence to ideogram_inpaint, but omits the actual action, side effects, permissions, or reversibility, leaving the agent to consult the referenced 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 that delivers the deprecation status, compatibility window, and pointer to the canonical schema with no filler.

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 deprecated alias with no parameters and no output schema, the description provides enough to route the agent: deprecation, compatibility window, argument equivalence, and schema reference. A direct operation statement is left to the title.

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 is empty (0 parameters). The description notes arguments and models are the same as ideogram_inpaint and points to its schema, which is valuable since this schema carries no field definitions. Baseline for 0 params is 4.

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 it is a deprecated alias of ideogram_inpaint, which clearly defines its role and distinguishes it from siblings. However, it does not state the actual operation (inpainting an image) in the description itself, relying on the title and the referenced tool.

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?

Specifies it is kept through 2.x for 1.x callers, clearly indicating the narrow backward-compatibility use case. It implies new callers should use ideogram_inpaint, though it does not explicitly forbid use or name the alternative in a directive sentence.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that results are written to the output directory, that ideogram_quote does not generate, and that each model branch has its own field set. It omits billing semantics (per-image cost), permission/auth requirements, and the polling path implied by wait_s, leaving notable gaps for a mutation tool of this complexity.

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 with the action and scope front-loaded, then model coverage, then the pricing/default caveats. The long model enumeration is dense but earns its place by telling the agent which families are wired up.

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 32-parameter, oneOf-heavy tool with no annotations and no output schema, the description covers the essentials: what is created, which models exist, the default, where output lands, and the related pricing tool. It stops short of explaining the wait/polling flow, but that is documented in the wait_s schema field rather than being strictly required here.

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 list/enum details are already covered and the baseline would be 3. The sentence 'Each model takes its own fields (one variant per model in this schema)' adds genuine structural value over the raw oneOf, warning the agent that fields are model-specific. The default-model statement overlaps with the schema's model description, slightly limiting the gain.

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?

Opens with a specific verb+resource ('Create images from a text prompt') and enumerates the exact model families the tool can drive, so an agent immediately knows this is the general-purpose generation entry point. It is also implicitly distinguished from siblings like ideogram_edit, ideogram_precise_edit and ideogram_quote, which are named in the text.

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?

Explicitly routes price-checking to ideogram_quote ('prices a call first (nothing is generated)') and states the default model. However it never says when to prefer this over the sibling edit/remix/inpaint tools, so the generation-vs-manipulation boundary is left to inference.

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

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

With no annotations, the description carries the full burden and does disclose meaningful traits: it waits up to wait_s, saves images or videos, is free, and never re-runs the generation. It stops short of saying where files land or what a timed-out collect returns, but the non-obvious side-effect and cost behavior is covered.

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 leads with verb and resource, and the parentheticals each add useful routing detail. Slightly dense, but no sentence is wasted.

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 three-parameter collect tool with no annotations or output schema, the description covers purpose, cost, idempotency and wait behavior. Remaining gaps (save location, timeout return shape) are minor for correct invocation.

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 schema already documents all three parameters. The description adds only marginal meaning, clarifying that generation_id may come from an earlier session and tying wait_s to the waiting behavior, so the baseline 3 holds.

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 (Collect) and resource (the result of a generation) keyed on generation_id, and clarifies it is the retrieval counterpart to a generation that is 'still running'. It implicitly separates itself from the generating siblings, though it never names ideogram_generate directly.

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 a concrete trigger: use when a tool answered 'still running' or when resuming from an earlier session. This is clear context for when to reach for it, though there is no explicit statement of when NOT to use it or a named alternative.

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

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

With no annotations, the description carries the full burden and does well: results are written to the output directory, long jobs return a generation_id for ideogram_generation, and the schema further documents that jobs are never resubmitted or billed twice, plus the private-feed default. Missing are auth/permission requirements and any rate-limit or failure behavior.

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 core operation is front-loaded in the first clause, and the second sentence carries all the lifecycle/routing facts efficiently. The first sentence is a dense, semicolon-heavy run-on, but nothing is redundant given how much ground it covers.

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 17-parameter, no-output-schema tool, the description covers the transformation, input forms, output destination and async result handling, which is most of what an agent needs. It leaves the many per-angle parameters to the 100%-covered schema, so nothing critical is silently 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 schema already explains view, metadata, instruction, garment_images and the per-angle image/asset pairs. The description adds only framing context (view options, factual product metadata, multi-angle reconstruction) rather than new syntax or format detail beyond the schema, so the baseline 3 applies.

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 names a specific transformation — garment photos turned into a ghost mannequin render on a clean white studio background — plus the supported input forms and requested view. It clearly distinguishes this from siblings like ideogram_sketch_to_render and ideogram_model_pose_variants, which perform different transformations.

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 routes the agent to ideogram_quote for pricing and ideogram_generation for polling a long job, and implicitly scopes usage to garment-photo inputs. It never states when to prefer this over near-neighbours such as sketch_to_render or precise_edit, so exclusions are weak, but the alternatives it does name are explicit.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the mask convention (black = repaint), accepted input sources, and where results are saved, and warns that ideogram_quote generates nothing. It omits key behaviors such as per-image billing, the async wait_s/generation_id handoff, and privacy defaults, which matter for a 25-parameter generation 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?

Two dense sentences with no waste, front-loading the core action and mask semantics before the input requirements and the pricing alternative. Every clause earns its place.

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 annotations, the description must compensate for a complex tool with three model variants and 25 parameters. It covers the essential call semantics and result location but leaves async behavior, billing, and privacy handling to the schema, leaving the picture incomplete for an agent.

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. The description adds meaning beyond the schema by explaining the mask convention (black = repaint) and that image/mask may be a local file, https URL, or Ideogram asset, details not present in the field descriptions. It adds value but covers only a subset of the many parameters.

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 and resource ('Repaint the masked part of an image') and pins down scope precisely, distinguishing it from siblings like ideogram_edit, ideogram_remove_object and ideogram_replace_background. An agent can tell exactly what this does without opening the 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?

Gives input prerequisites ('Needs the source and the mask') and routes pricing to ideogram_quote, which is useful context. However it never states when to choose inpaint over the many adjacent edit/background siblings, so alternative selection is left to inference.

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

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

With no annotations, the description carries full burden and does disclose two behaviors that matter: it requires an API key owned by an organization admin, and it is read-only ('Reads only'). It omits pagination, billing period scope, and result limits, but the auth and safety profile are covered.

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?

Two compact sentences with the resource identified first and constraints trailing. The em-dash clause 'the billing record the usage reconciles against' is slightly indirect but carries real information about the tool's role.

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?

No output schema and no parameters, so the description must convey what comes back: it names invoices and their line items, plus the auth prerequisite. It stops short of stating time-range or pagination behavior, which is the only remaining gap for a zero-parameter read tool.

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, which is the baseline-4 case. The schema is empty, so there is nothing for the description to clarify or compensate for.

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 resource ('your organization's invoices with their line items') and a verb-like operation implicitly (retrieval/read). An agent can distinguish it from ideogram_usage and ideogram_quote, though the description never names those siblings to sharpen the boundary.

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?

The clause 'the billing record the usage reconciles against' implies this is used alongside ideogram_usage, giving implied context rather than an explicit when-to-use/when-not or named alternative. No exclusions or prerequisites beyond the auth note.

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

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

With no annotations, the description carries the full disclosure burden and does reasonably well: it explains what the operation produces (text blocks with matched fonts/sizes/colours, a text-free base image that is saved), that font matching is optional, and that ideogram_quote can price the call beforehand. It omits anything about credits/billing side effects, failure modes, or the async wait_s job model that the schema hints at.

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?

Two dense sentences, front-loaded with the transformation and its outputs, then the optional-input and pricing notes. Nothing is wasted, though the second sentence is packed tightly enough that the font and quote hints feel appended rather than integrated.

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 9-parameter, zero-required tool with no output schema and no annotations, the description fills the most important gap by describing the return shape (text blocks plus a saved base image), which the schema cannot convey. It still leaves the async generation_id/wait_s flow and the relationship to sibling tools unexplained, so it is not fully self-sufficient.

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% across all 9 parameters, so the schema already documents seed, image, model, prompt, private, wait_s, inline_images, font_candidate_files and image_asset_identifier. The description only echoes the font-file parameter and adds nothing on the remaining eight, so the baseline 3 applies.

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+resource (turn a flat image into an editable design) and details the exact outputs: positioned text blocks with matched fonts, sizes and colours plus a saved text-free base image. That is far more than a restatement of the name. It stops short of distinguishing this tool from the similarly named sibling ideogram_layerize_logos, which an agent would have to resolve on its own.

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?

Usage is only implied: the description notes font files are optional and points at ideogram_quote for pricing before a call, which hints at a paid, opt-in workflow. It never says when to choose this over ideogram_layerize_logos, ideogram_edit or the other edit-family siblings, and gives no prerequisites or exclusions.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: it removes detected elements, saves a text-free base image, and returns layers tagged with the matched reference. It also flags that there is no dry run and no price quote, which matters before invoking an irreversible-seeming operation. It omits auth requirements and failure behavior, keeping it short of 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?

The purpose is front-loaded and the whole thing is only three sentences. However, the middle sentence ('The design and the references as local files or public https URLs') is a verbless fragment that reads as garbled, slightly hurting structure without being wasteful.

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 annotations, the description fills most of the gap by describing the returned base image and matched layers, plus the no-dry-run caveat. It still lacks detail on no-match outcomes or error handling, but for a 3-parameter operation it is largely complete.

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 schema already documents all three parameters, including the REF_n ordering and local-file/https-URL input. The description largely restates the input formats ('as local files or public https URLs') and adds little beyond what the schema provides, so baseline 3 is appropriate.

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 and resource: detect reference logos/image elements in a flat design, remove them, and save a text-free base image. It clearly scopes itself to logo layerization, distinguishing it from the generic sibling ideogram_layerize and from ideogram_remove_object.

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?

There is no explicit guidance on when to choose this tool versus alternatives like ideogram_layerize or ideogram_remove_object. The 'No price quote / no dry run' caveat is a note about the operation, not a routing condition, so the agent must infer usage.

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

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

With no annotations, the description carries the full burden. It usefully discloses non-effects (no generation, no dry run, no price quote) and states what is returned (JSON prompt plus aspect ratio), but is silent on whether the call itself consumes credits, what auth is required, or latency behavior for a rewrite operation.

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 with no filler; the what-it-does clause comes first and the scope caveats follow. The parenthetical 'no price quote (the v1 operation offers no dry run)' is slightly tangled but still earns its place as a safeguard against misuse.

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?

No output schema or annotations exist, so the description must stand alone; it does state the return payload (structured JSON prompt and aspect ratio) and the absence of side effects. The gap is that inline_images' base64/file-path return behavior, a real client-facing consequence, is left entirely to the schema.

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. The description reinforces the AUTO behavior ('the aspect ratio the model picks for it, or the one you pin'), which the schema already documents, and never mentions inline_images, so it adds little beyond the structured fields.

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 and resource ('Rewrite a natural-language prompt into an Ideogram 4.0 structured JSON prompt') plus the secondary output (chosen/pinned aspect ratio). It also explicitly separates itself from the generate family with 'Nothing is generated', so an agent can distinguish it from siblings like ideogram_generate 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?

Gives a clear boundary condition: 'Nothing is generated; no price quote (the v1 operation offers no dry run)', which tells an agent not to reach for this when it wants an image or a cost preflight. It stops short of naming the alternatives (ideogram_generate, ideogram_quote) explicitly, so it is clear context rather than full when/when-not routing.

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

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

With no annotations, the description does real work: it discloses the async contract (job accepted first, generation_id returned if still running, never resubmitted or billed twice), where results land (output directory), asset-vs-file inputs, and the positional pairing of masks to materials. It doesn't cover permissions or account requirements, but the operational profile is well conveyed.

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 tight sentences, front-loaded with the core action and its field-level detail, then the input mediums, then the async/quoting follow-ups. No filler or repetition.

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 11-parameter, no-output-schema, no-annotation tool, the description covers mechanism, pairing limits, input mediums, result location, and async/quoting handoffs — enough to invoke it correctly. It stops short of stating prerequisites or how mask/material counts must align on failure. Minor gaps only.

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, and the description largely restates what the schema already says (files/URLs/assets, pairing by position, max 4). It adds no extra format detail on wait_s, quality, or inline_images beyond the schema text.

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 precise verb and resource — applying reference-image material (colour, texture, pattern scale, orientation) to masked regions of a product photo — plus scope limits (up to 4 masks/materials, paired by position). This is clearly distinguishable from sibling edits like ideogram_colorways or ideogram_replace_background.

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 points to the surrounding workflow (long jobs return a generation_id for ideogram_generation, ideogram_quote prices first) which implies when to poll and when to price, but it never states when to pick this tool over an adjacent edit tool such as colorways or remix. Usage is implied rather than contrasted.

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

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

With no annotations the description carries the full burden, and it delivers meaningful behavior: outputs are written to the output directory, long-running jobs return a generation_id rather than a result, and there is no dry run or price quote. It stops short of noting billing implications or permission requirements, but the async/retry model is clearly disclosed.

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 the purpose before operational notes, with no filler. Slightly dense in the third sentence (output dir, generation_id handoff, no dry run packed together) but each clause earns its place.

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 ten-parameter generation tool with no annotations and no output schema, the description covers purpose, accepted source forms, output destination, and the long-job resumption path. It omits billing and authentication context, but nothing critical for correct invocation 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 schema already documents all ten parameters; the description only restates source formats (local file / https URL / Ideogram asset) and the pose reference, largely duplicating the schema. Baseline 3 is appropriate.

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 and resource ('Re-pose the model of a fashion image') plus the governing input ('plain-language pose or camera instruction') and the optional pose reference. This distinguishes it cleanly from siblings like ideogram_ghost_mannequin, ideogram_material_swap and ideogram_precise_edit.

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?

The narrow scope implies when to use it, and it notes the async handoff to ideogram_generation and the absence of a dry run / price quote. However it never explicitly contrasts with alternatives or states when NOT to use it, so the agent must infer selection.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the key safety trait ('Reads only') and one useful output behavior (training runs are returned only when the model is yours), but says nothing about pagination, result limits, or what a list response looks like versus a single-model response.

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?

One dense sentence that front-loads the resource and then the two retrieval modes, with the read-only guarantee trailing as a compact clause. Nothing is padded, though the mid-sentence colon splice makes the mode distinction slightly harder to parse than it needs to be.

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 3-parameter, fully-documented read tool this is roughly adequate, but with no annotations and no output schema the description is the only source for behavioral and return-shape information, and it does not say whether a list returns an array, whether results are paginated, or what fields a model carries.

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 scope, status, and model_id are already documented in the schema, and the 3 baseline applies. The description adds a small amount beyond the schema by noting the list-vs-single duality and that training runs come back only for owned models, but adds no syntax or format detail for the parameters themselves.

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 the resource (custom models owned or shared with the organization) and the two access modes: list by scope/status, or fetch one by id with its training runs. The verb is implicit ('the list ... or one by id') rather than a crisp 'list/get', and it does not explicitly distinguish itself from siblings like ideogram_datasets or ideogram_train, but an agent can still tell what it returns.

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?

The parenthetical 'the list (by scope and status), or one by id with its training runs' implies which parameter combination selects which mode, but never states when to reach for this tool over ideogram_train or ideogram_datasets, and gives no prerequisites or exclusions.

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

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.

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

No annotations are provided, so the description carries full burden; it does disclose key behavior: results are saved to the output directory, nothing is generated by the quote, mask semantics (black = edit), reference images are not themselves edited, and a max of 4 (3 with mask). It does not disclose billing/rate behavior or failure modes, but covers the important operational traits.

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?

Two dense sentences, front-loaded with the core distinguishing trait (exact size, unchanged pixels preserved) before enumerating inputs and the sibling quote tool. No filler, though the second sentence is a heavy clause stack.

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 15-parameter generation tool with no output schema and no annotations, the description gives the essentials an agent needs: input roles (image, mask, reference images, context_window), what changes and what doesn't, and the pricing sibling. Missing details on output format and billing, but the schema descriptions cover most parameters.

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 schema already carries parameter meaning. The description reinforces the most error-prone semantics: mask color convention, context_window purpose, reference-image count limits, and the image+mask condition. It does not add meaning beyond schema for most parameters, keeping it near the 100%-coverage baseline, but the reinforced constraints add real value.

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+resource (edit an image with Ideogram 4.5) and defines the distinguishing scope: pixels not changed stay as they are, at the exact size. Among many image-editing siblings (ideogram_edit, ideogram_inpaint, ideogram_remove_object), the 'exact size, unchanged pixels preserved' framing differentiates it.

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?

Explains the conceptual model of the operation (black = edit in mask, context_window confines the edit, reference images guide but are never edited) which implies when this tool is right. It names ideogram_quote as the pricing alternative, but does not explicitly exclude the many overlapping edit siblings (inpaint, remove_object, replace_background), so routing is only partly disambiguated.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully discloses the return fields and the zero cost, plus the caveat 'as Ideogram answers it,' but says nothing about authentication, rate limits, or what happens when the image is not Ideogram-generated (presumably an invalid validation state).

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 short sentences, front-loaded with the purpose and the returned record. The closing 'Free of charge; no price quote' is mildly redundant but does add routing value, so nothing is seriously wasted.

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 helpfully enumerates the returned provenance fields, and it covers both accepted input forms and cost. The main remaining gap is failure behavior for images with no Ideogram provenance, which an agent would want to know before calling.

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 both parameters are already documented in the schema; the description only restates the accepted content forms. The inline_images flag and its base64/3.75 MB caveat are left entirely to the schema, so baseline 3 is correct.

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 and resource — 'Check whether an image was created by Ideogram' — and enumerates exactly what the answer contains (provider, system version, generation id, creation time, validation state). This clearly separates it from content-reading siblings such as ideogram_describe and from the generation/edit tools.

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?

The description names the accepted input forms (local file or public https URL) and states 'Free of charge; no price quote,' which implicitly routes the agent away from ideogram_quote. It never says when to reach for this tool versus other inspection tools, and gives no exclusions or prerequisites.

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

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

With no annotations, the description carries the full load and does well: it guarantees 'nothing is generated or billed,' explains the answer comes from the API's own dry run, and discloses that results are either exact or an estimate with an upper bound. It stops short of covering errors, argument validation, or auth requirements.

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 tight clauses with the core action front-loaded, then the inputs, then the output guarantee. No sentence is filler; each adds a distinct fact.

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 usefully describes the return content (USD and credits, exact or upper-bounded estimate) and the no-side-effect guarantee. For a two-parameter costing tool fully covered by the schema, nothing an agent needs to invoke 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% — both 'tool' and 'arguments' are already documented in the schema, including the enum of curated tools. The description restates the same meaning ('tool's name and the arguments you would pass it') without adding syntax, format, or constraint detail beyond the schema, so the baseline 3 applies.

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 and resource — asking Ideogram what a call would cost — with an unmistakable pre-flight framing ('before making it'). It implicitly separates itself from siblings like ideogram_usage and ideogram_invoices (post-hoc records) and from the generation tools it prices.

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?

The trigger is clear: use this before making a call, supplying the curated tool's name plus the arguments you would pass it. It does not name alternatives (e.g., ideogram_usage for historical spend) explicitly, so it falls just short of full routing guidance.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that results land in the output directory and that ideogram_quote is non-generating, but says nothing about billing (per-image charges), the async job lifecycle, or what happens on timeout – facts that exist only in the schema.

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?

Two compact sentences: the operation and models come first, the output-location and pricing-tool note second. Every clause carries information; nothing is 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 16-parameter tool with no annotations and no output schema, the description covers the essentials (what it does, where output goes, that ideogram_quote only prices). It leans on the exhaustive 100%-coverage schema for parameter detail, which is acceptable, though it omits the asynchronous/billing behaviour the agent would want.

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% with rich per-parameter descriptions and enum lists, so the baseline is 3. The description adds only the model names (Ideogram 3.0 / Nano Banana 2) which map to the existing model enum, adding no syntax or constraint detail beyond the schema.

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 and operation ('Extend an image... by outpainting') plus the two supported models, which cleanly separates it from siblings like ideogram_upscale, ideogram_inpaint, and ideogram_precise_edit.

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 a clear usage context by pointing at ideogram_quote as the pre-flight pricing step and clarifying that quote generates nothing. It does not state when to prefer this over e.g. reframe-adjacent siblings, so no explicit alternative routing beyond that one mention.

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

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

With no annotations, the description carries the full burden. It usefully discloses that results are saved to the output directory and that quoting generates nothing and is not billed. It is silent on the cost per generated image, permission/asset requirements, or failure behavior, which matters for a paid generation tool with 29 optional parameters.

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?

Two dense sentences that are front-loaded with the core operation before the model list and the output/quote details. Given the tool's complexity this is compact and no sentence is filler, though the model parenthetical is slightly cluttered.

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 29-parameter tool with a five-branch oneOf schema, no annotations, and no output schema, the description is thin. It omits how the model choice changes required fields (e.g. custom_model_uri, rendering_speed availability) and says nothing about the mutually exclusive resolution/aspect_ratio options the schema encodes.

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 schema already documents every parameter, establishing a baseline of 3. The description adds only the meaning of image_weight and the model list, both of which are effectively mirrored in the schema, so it contributes little beyond structured fields.

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 concrete verb and resource: making new images from a source image plus a prompt, which is a distinct image-to-image operation. It names supported models and explains what image_weight controls. It does not explicitly distinguish itself from remix-adjacent siblings like ideogram_precise_edit or ideogram_inpaint, so an agent must infer the boundary.

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 usefully routes the agent to ideogram_quote for pricing before generating, which is a genuine usage hint. However there is no guidance on when to prefer remix over ideogram_generate, ideogram_edit, or ideogram_precise_edit, and no exclusions or prerequisites for the source image.

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

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

With no annotations provided, the description carries the full burden, and it does disclose real behavior beyond the schema: the output is a transparent PNG foreground, results land in the output directory, and quoting a call generates nothing. It omits billing/cost behavior of the actual call, whether the source image is left untouched, and synchronous-vs-async semantics (though wait_s in the schema covers the latter).

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?

Two tightly packed sentences that are front-loaded with the action and result, then inputs, then side effects. Every clause earns its place, and the ideogram_quote pointer is a genuinely useful aside rather than filler.

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 6-parameter tool with no annotations and no output schema, the description covers purpose, output artifact, accepted inputs, and where results are saved. Missing only cost/permission expectations and an explicit statement that the operation does not alter the source image.

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. 'Takes a local file, a public https URL or an Ideogram asset' usefully maps to the image vs image_asset_identifier variants, but the description adds no detail on model, private, wait_s, or inline_images beyond what the schema already states.

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 ('Remove the background of an image') and adds the concrete result ('the foreground comes back as a transparent PNG'), which an agent can immediately act on. It does not explicitly contrast itself with the sibling ideogram_replace_background, but the verb choice makes the distinction largely self-evident.

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 implies when the tool applies and enumerates the three acceptable input sources (local file, public https URL, Ideogram asset), and it points to ideogram_quote for pricing. It stops short of explicit when-to-use/when-not guidance or naming a competing sibling such as ideogram_replace_background or ideogram_precise_edit.

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

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

With no annotations, the description carries the full burden. It usefully discloses the mask convention, that results land in the output directory, and that ideogram_quote prices a call without generating. It omits billing/auth implications of the real call, failure behavior, and async polling expectations beyond what the schema already states for wait_s.

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?

Two tight sentences, front-loaded with the core action and mask convention, followed by required inputs and output/pricing behavior. No filler; every clause carries a fact the agent needs.

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 9-parameter, no-output-schema tool, the description covers the essential mechanics: mask semantics, accepted input forms, output location, and pricing path. Remaining gaps (error handling, cost of the billed call, async polling) are partially covered by the schema's wait_s description, so the definition is largely self-sufficient.

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 baseline is 3. The description does add genuinely schema-absent detail — the white-equals-remove mask convention and the same-size constraint between mask and source — but otherwise the per-parameter meaning is already fully documented in the schema.

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 and resource ('Remove a masked object from an image') and adds the operating convention (white in the mask = remove, fill the gap). The masked-object mechanism implicitly distinguishes it from siblings like ideogram_remove_background or ideogram_inpaint without needing to name them.

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?

Points the agent to ideogram_quote for pricing and clarifies the input requirements (source + same-size mask, local/URL/asset), which is useful routing. However, it never says when to choose this over closely related siblings such as ideogram_inpaint, ideogram_remove_background, or ideogram_edit, leaving the primary selection decision to inference.

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

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

With no annotations, the description carries the full burden. It does disclose two useful traits: results are written to the output directory, and ideogram_quote performs pricing without generating (no cost/side effect). It omits billing implications of num_images, the async wait/generation_id behavior, and privacy defaults, all of which only appear in the schema.

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?

Two sentences, no filler. The core action and subject-preservation constraint lead, followed by where output lands and the free pricing precheck. Every clause carries information.

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 10-parameter, annotation-free, output-schema-free tool, the description covers the essentials an agent needs: what it does, what the prompt means, where results go, and the quote precheck. Remaining gaps (billing, async polling) are already documented in the schema fields.

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 a 3 is the baseline. The description goes beyond it by explaining what the prompt actually controls here — it describes the new background, not the whole image — which is non-obvious for a background-replacement tool and guides prompt authoring.

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+resource pair (replace an image's background) and adds a scope qualifier — the subject is preserved — which implicitly separates it from remove_background/remove_object. It also names the two supported models. It does not explicitly name a sibling to route against, so it falls short of a 5.

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?

The description implies usage context (image editing where the subject stays and the background changes) and helpfully points at ideogram_quote as a free pricing step. But it never says when to pick this over remove_background, inpaint, precise_edit or edit, which are the genuinely confusable siblings in this list.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses where results land (output directory), the async fallback (generation_id for ideogram_generation), and that no price quote or dry run is available. It does not state permission/auth requirements or what happens to existing assets, leaving some behavioral gaps.

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 dense sentences, front-loaded with the core purpose and followed by input forms and output/async behavior. Nearly every clause earns its place, though the parenthetical about the dry run is slightly compressed and the sketch input forms are repeated from the schema.

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 9-parameter generation tool with no output schema and no annotations, the description supplies the essential return behavior (files to the output directory, generation_id for long jobs) and input-source flexibility. It stops short of covering auth, billing specifics, or how the async path is resumed, so an agent may still need the schema and sibling tools.

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 schema already documents all nine parameters, making 3 the baseline. The description adds modest value by restating that the sketch may be a local file, a public https URL, or an Ideogram asset (sketch_image vs sketch_asset_identifier), but introduces no format or syntax detail beyond the schema.

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 ("Render") and resource ("a fashion sketch as a product photo"), and adds the transformation's intent (material/rendering direction plus construction details the sketch omits). This distinguishes it from siblings like ideogram_ghost_mannequin or ideogram_material_swap in substance, though it never names an alternative explicitly.

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?

Usage is implied by the sketch-based input rather than stated: nothing says when to pick this over ghost_mannequin or material_swap for a similar fashion workflow. It does provide useful routing context ("long jobs come back as a generation_id for ideogram_generation") and a caveat about pricing, but no explicit when-not guidance.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the result is written to the output directory as a PNG, mask polarity is defined (white ≥ 128), and it explicitly states there is no price quote / no dry run for this v1 operation. It stops short of stating permission requirements, cost, or failure behavior.

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 core action and output are front-loaded and every sentence carries information (polarity, downstream consumers, inversion rule, no dry run). The final 'No price quote' sentence is somewhat orphaned and the second sentence is long, but nothing is wasted.

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 annotations, the description fills the key gaps: it explains the return artifact (PNG, white = object, saved to output directory) and its intended consumption. Remaining gaps around authorization, cost and error handling are minor for a mask-snapping utility.

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 image, mask and inline_images are already documented in the schema, including the mask's polarity and the inline_images base64/size caveat. The description only restates that inputs may be local files or public https URLs, adding no syntax or format detail beyond the schema.

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 ('snap a hand-drawn binary mask to the object it marks') and immediately characterizes the output (PNG, white = the object, saved to the output directory). It is clearly distinguishable from siblings like ideogram_inpaint and ideogram_remove_object, which it explicitly names as downstream consumers.

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 routing instructions: use the result as-is for ideogram_remove_object, colorways and material swap (white = region to change), and invert it for ideogram_inpaint (black = region to repaint). This tells the agent exactly when the tool fits and how its output must be transformed for each alternative.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that training is tracked asynchronously via the returned model id and that the resulting custom_model_uri feeds ideogram_generate, but omits cost, permissions, rate limits, and how to poll training status.

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?

Two dense sentences, appropriately front-loaded with the purpose and constraints, then the follow-up tool chain. The 'hyperparameter routes to the advanced operation' phrase is the only bit of wasted/confusing text.

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 complex training tool with no annotations and no output schema, the description compensates by explaining the return value (model id) and downstream usage. Gaps remain around auth, cost, and async completion checking, but the call-and-follow workflow is complete enough to invoke 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?

Schema description coverage is 100%, so the schema already documents all ten parameters (batch_size, lora_rank, learning_rate, etc.). The description adds only the dataset size range, which is already in the schema, so it earns the baseline 3.

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 and resource ('Start training a custom Ideogram 4.0 (default) or 3.0 model from a dataset of 15-100 images'), which is easy to distinguish from generation/edit siblings. The clause 'a hyperparameter routes to the advanced operation' introduces minor ambiguity, but the core purpose is unmistakable.

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?

Usage is only implied through the workflow chain ('follow with ideogram_models', 'generates through ideogram_generate') and the 15-100 image dataset constraint. There is no explicit when-to-use or when-not-to-use statement, and the 'advanced operation' routing is left unexplained, so the agent must infer conditions.

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

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

With no annotations, the description carries full behavioral burden. It usefully discloses that results are written to an output directory and that ideogram_quote prices a call without generating anything, implying upscale does incur generation/billing, but it omits cost, async/wait behavior, and reversibility.

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-loads the core action, then packs the model options, output behavior, and pricing path into a compact two-clause sentence with no wasted words. Every clause adds usable information.

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 complex 10-parameter tool with seven model variants and no output schema, the description covers purpose, model choice, result destination, and the pricing entry point reasonably well. It could say more about when a result is deferred to a generation_id, though the schema's wait_s field documents that.

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 real value by explaining that model variants exist and that "each model takes its own controls" — which frames the oneOf structure for the agent. The friendly model names ("Topaz Bloom") map only loosely to the enum values, slightly weakening the mapping.

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+resource ("Enlarge an image") and enumerates the available model backends, so the agent immediately knows what the tool does. It does not explicitly contrast itself with edit-oriented siblings like ideogram_precise_edit or ideogram_remix, but the purpose is unambiguous.

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?

The description names ideogram_quote as the pricing-before-generation path, which clarifies a related tool, but gives no explicit when-to-use/when-not guidance against the many editing and generation siblings. Choice of model is implied by the list rather than explained.

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

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

With no annotations, the description carries the full burden and does well: it discloses 'reads only', the org-admin API key prerequisite, and that the buckets are written unchanged to a file in the output directory (and printed when small). It stops short of stating rate limits, failure modes, or file naming.

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?

It is a single, heavily parenthesized run-on sentence that packs a lot in but is hard to parse; the most important facts (what it returns, the file output) are buried mid-sentence. Information density is high, but front-loading and readability suffer.

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?

There is no output schema, and the description compensates by describing the returned buckets, the per-product/unit/currency aggregation, and the file artifact. For a 4-parameter read tool with an org-admin auth requirement, this covers most of what an agent needs to call it 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?

Schema description coverage is 100%, so all four parameters (sources, start_time, end_time, bucket_width) are already documented in the schema. The description restates the default window and the summing dimensions but adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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 resource (billed API/org usage) and what it returns (time buckets of line items summed by product, unit, currency), which separates it from ideogram_invoices, ideogram_quote and ideogram_generation. It never names a sibling explicitly, so the discrimination is inferential rather than stated.

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 useful context -- default range of the last 7 days by day, and the need for an API key owned by an org admin -- but never says when to prefer this over ideogram_invoices or ideogram_generation, nor any exclusion. Usage is implied by the resource rather than spelled out.

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

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 disclose the output medium (saved as mp4) and the async fallback (long jobs return a generation_id). However, it omits the wait_s polling/accept-then-resume behavior and the private-by-default posture, both of which live only in the schema.

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 compact sentences, front-loaded with the core purpose, then inputs, then output/pricing. Little waste, though the model list and pricing pointer make it slightly dense.

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 15-parameter, four-variant tool with no output schema, the description covers source types, model choices, output format, and pricing hand-off, leaving only polling semantics to the schema. Completeness is solid, if not exhaustive.

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 schema already documents all 15 parameters, setting the baseline at 3. The description adds only the model roster and the accepted input source types (local files, https URLs, Ideogram assets), which the schema largely mirrors.

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+resource ('A video that starts from an image') and enumerates the four supported models, which cleanly separates it from ideogram_video_text (text-driven) and ideogram_video_reference. It does not explicitly name those siblings, so it stops short of a 5.

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 implied context (image-to-video, optional end image) and routes the agent to ideogram_quote for pricing, but offers no explicit when-to-use-vs-alternatives guidance against the other two video tools or the image-editing siblings.

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

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

With no annotations, the description carries the full burden and does reasonably well: it discloses the output format (mp4), the async behavior ('long jobs come back as a generation_id'), the model default, and the cost-check workflow via ideogram_quote. It omits permission/auth requirements and any rate or concurrency limits, but the core behavioral profile is disclosed.

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 purpose is front-loaded in the first clause, followed by constraints, outputs, and the pricing pointer — a sensible order for a 13-parameter tool. It is dense with parenthetical per-model details, which slows reading slightly, but almost every clause carries information an agent needs.

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 13-parameter generation tool with no annotations and no output schema, the description covers the essentials: supported inputs, model variants and default, minimum reference requirement, output format, async result shape, and the quote-first cost workflow. Remaining parameter detail is handled by the schema's own 100% description coverage, and return values are addressed via the mp4/generation_id statement.

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 baseline is 3. The description still adds value beyond the schema: it establishes the model ordering and default, the 'at least one reference image or video' constraint that the schema does not state as a rule, the per-model audio duration limits, and the prompt-order semantics for references. It is additive rather than redundant.

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 the resource and scope precisely: a video guided by reference images, audio clips, and Ideogram-stored videos, with a clear model ordering (Seedance 2.5 default, then Seedance 2, MiniMax H3). An agent can tell this is reference-to-video rather than a plain image-to-video tool. It stops short of naming the sibling it must not be confused with (ideogram_video_image / ideogram_video_text), so it is clear but not fully differentiated.

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?

Usage is implied through prerequisites ('at least one reference image or video') and a workflow hint ('ideogram_quote prices a call first'), which is genuinely useful. However, there is no explicit statement of when to choose this over ideogram_video_image, ideogram_video_text, or the other video siblings. Guidance exists but must be inferred.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose real traits beyond the schema: output is always an mp4 file in the output directory and never inline, and long jobs return a generation_id rather than the video. However, it omits permissions/auth requirements, moderation behavior beyond the single 'stricter moderation' aside, and any failure/retry semantics for a long-running paid job.

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 dense sentences that front-load what the tool does, then output format, then pricing. Every clause carries information, though the parenthetical model list and the multi-clause duration sentence push it toward density over readability.

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 11-parameter, no-annotation, no-output-schema tool, the description covers the important unknowns: where output lands, how async jobs resolve, and how duration affects cost. It leaves a few gaps (the private feed default, negative_prompt behavior) that the schema partially covers, but nothing critical 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 description coverage is already 100%, so the baseline is 3, but the description adds genuine meaning the schema does not: omitted duration causes Seedance to be quoted at its maximum length, generate_audio roughly doubles the price and the dry-run quote excludes it, and resolution tiers on MiniMax are upscaled. That pricing/default interaction is the kind of context the schema can't carry.

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 concrete verb+resource combination: generate a video from a text prompt, and names the four supported models up front. 'From a text prompt' implicitly separates it from the sibling video tools (ideogram_video_image, ideogram_video_reference), but those siblings are never named, so the distinction rests on inference rather than explicit contrast.

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?

Routes the agent to two alternatives with conditions: use ideogram_quote to price a call first, and use ideogram_generation to resume a job when a generation_id is returned. Also specifies when to supply duration (to get an accurate price). It stops short of saying when to prefer this tool over the other video-generation siblings.

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