load_device_on_return

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention side effects (e.g., whether it replaces an existing device), error conditions, or prerequisites such as the need for the return track to already exist. This is a significant gap for a mutation 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?

The description is concise and well-organized: a single opening sentence stating the action, a brief discovery hint, and a clearly formatted argument list. Every sentence earns its place, with no redundancy or fluff.

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?

The description covers the main inputs and the URI discovery step, but it omits important contextual details such as whether the return track must already exist, what happens if the index is invalid, and any side effects. Given the lack of annotations, the description leaves notable gaps for an agent to use the tool 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?

The description fully explains both parameters: 'Zero-based index of the return track' and 'The browser URI of the instrument or effect to load'. This adds crucial meaning beyond the schema's bare titles and types, effectively compensating for the 0% schema description coverage.

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 specific action ('Load a device onto a return track') and the method ('using its browser URI'). It distinguishes this tool from sibling loading tools like load_device_on_master by explicitly targeting return tracks. The additional reference to browser discovery tools reinforces its purpose.

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 provides clear usage guidance by instructing the agent to use get_browser_tree or get_browser_items_at_path to discover available URIs before invoking this tool. This establishes a clear prerequisite workflow. However, it does not explicitly mention when not to use this tool or compare with loading tools for other track types, so it lacks exclusions.

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