Custom models

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.