list_effect_catalog

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds genuine behavioral content beyond them: the exact return shape at each mode, the notion of a 'default layout' with label/unit/range, and the non-obvious semantic that models User 1…User 10 (ids 200…209) are bound to Samples slots rather than being real amp models. It stops short of noting ordering, size limits, or whether the sample binding is editable.

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 resource, then structured as clean 'Without arguments: … With type: …' mode branches, which is easy for an agent to pattern-match. Every clause carries information; the only weak spot is the telegraphic User 1…User 10/id 200…209 sentence, which packs a dense cross-reference into one line.

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 fields for each mode, which is the main thing an agent needs to plan a call. With zero required parameters and total annotation coverage, the remaining gaps (ordering, whether model requires type, format of the range values) are minor but real.

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% and both parameters are already documented, including the enumerated type names, so the baseline is 3. The description's mode sentences largely restate what the schema says about type and model, adding only the detail that the returned parameter set covers label, unit and range. Useful reinforcement, but not much meaning 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?

The description names the specific resource (effect types and models) and lays out exactly what each call shape returns: types with model counts, or every model with id/name plus its default layout parameters. The verb is implicit rather than stated ("Effect types and models" is a noun phrase), and it doesn't directly contrast itself with nearby siblings like get_settings or list_presets, but an agent can still tell it is the lookup/catalog endpoint.

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 explicitly distinguishes the call modes: no arguments lists types with counts, passing type enumerates models, and passing model shows that model's exact layout. It also routes the agent elsewhere for mutation ("Parameters are edited by label with edit_effect") and for the sample mapping ("see list_samples"), which is real alternative-naming. There is no explicit statement of when NOT to use it versus catalog-like siblings such as get_settings.

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