list_innerspace_devices

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

With no annotations, the description takes on full responsibility for behavior disclosure. It explains what is returned (placement fields, device meta.mac/meta.ip, returned verbatim), defines the rotation semantics (pov = heading/yaw, base = mount tilt), and clarifies how mode changes the output coordinates. This is much more informative than a typical list tool description.

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 organized and front-loaded: a one-sentence purpose, then useful details about fields, mode behavior, and parameters. Each sentence adds necessary information. It is slightly dense, but nothing is redundant or irrelevant.

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?

Given that an output schema exists (so return value structure is already formalized), the description adequately covers the tool's scope, host identification, mode semantics, and field meanings. It omits potential error cases or prerequisites, but for a read-only listing tool in a larger family, the provided context is sufficient for correct invocation.

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 input schema provides only 'string' types and a default for mode, with 0% schema description coverage. The description fully compensates by explaining host formats (console name, ID, or MAC:numericId composite) and mode values ('3D' or '2D') with their effects. This gives an agent all the necessary parameter-level understanding.

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's purpose: 'List placed device shapes from a console's InnerSpace floor-plan.' It specifies the resource type and context, and the additional field details (mount, productId, title, position, rotation) help distinguish it from general inventory or network listing tools. However, it does not explicitly name sibling tools, so some differentiation relies on the reader inferring from wording.

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 gives clear operational guidance: host can be a console name, ID, or composite ID, and mode has two options with explained behavior. It does not explicitly state when to use this tool versus competing InnerSpace tools (e.g., list_innerspace_inventory), but the description's focused context makes the appropriate use case evident.

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