get_device_routings

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

No annotations are provided, so the description carries full responsibility for disclosing behavior. It states that the tool returns available routing types and channels plus current selections, which clarifies the read-only nature and output. However, it does not mention potential errors, side effects (though likely none), or permissions. For a getter, this is sufficient but not exceptional, hence a middle score.

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 concise and well-structured: it opens with the core purpose, then states the return value, provides usage guidance, and lists parameters. Every sentence adds value; there is no fluff or repetition. The parameter list is necessary given the lack of schema descriptions.

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 simple gadget with no output schema, the description provides sufficient context: what it does, what it returns, when to use it, and param definitions. It lacks details on error behavior or exact output structure, but these are not critical for a discovery tool. The explanation of return content ('available routing types and channels... plus current selections') is adequate.

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 0%, but the description fully compensates by explaining each parameter: track_index ('Track containing the device'), device_index ('Position in the chain'), and track_kind with allowed values and default. This adds meaningful semantics beyond the bare schema, though it could be more detailed (e.g., zero-based indexing), it's effective.

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 clearly states the tool inspects available input routings for a device, specifically for discovering sidechain sources. The verb 'Inspect' combined with the resource 'input routings' makes the purpose unambiguous. It also distinguishes itself from the sibling tool set_device_routing by being the getter counterpart.

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?

Explicit guidance is given: 'Use this BEFORE set_device_routing so you know what type/channel names are valid.' This directly tells the agent when to invoke this tool and provides an alternative (set_device_routing) for the subsequent operation. This is clear, actionable usage direction.

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