devices_list

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

Annotations already declare readOnly/idempotent/non-destructive, so the burden is light, and the description adds real value by disclosing the returned fields per device — slot, name, kind (builtin/plugin/script), bypass, and parameter count — plus that results come back in signal order. That return-shape and ordering information is nowhere in the structured data and is exactly what an agent needs to plan a follow-up call such as devices_set_params.

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 compact sentence with no filler, but it is grammatically a fragment and front-loads an abstract phrase ("The effects of a chain in signal order") ahead of the actual operation. The per-device field list is the most useful part and arrives last.

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 one fully documented parameter and no output schema, the description partially compensates by enumerating returned fields and their meaning. It still leaves open what happens for an empty chain or invalid track id, whether MIDI effect chains are included, and whether devices add more fields than the five listed.

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% and the schema description already spells out {"track": <id or index>}, {"return_bus": <index>} and "master", including the stability caveat for indices. The description restates the same three forms without adding syntax or edge-case semantics, so it does not exceed the baseline for a fully documented parameter.

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 never states the verb ("list") or the resource ("devices"); it opens with "The effects of a chain in signal order," which is a noun phrase about the chain rather than about the tool. An agent can infer it enumerates devices in a track/return/master chain, but only after parsing the parenthetical forms, and nothing distinguishes it from devices_get or devices_types.

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 statement of when to call this rather than devices_get, devices_types, params_list, or mixer_get, despite those siblings sitting in the same namespace. No prerequisites, no context cues — the agent must guess from the names.

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