list_devices

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

With no annotations provided, the description carries the full burden. It discloses the nature of the data ('data that changes rarely') and the return categories (identity, hardware info, location, configuration), but does not explicitly mention that the operation is read-only or cover edge cases like pagination, permissions, or empty results. This is adequate but not rich.

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 compact and well-structured: a purpose sentence, a return-value clarification, and an explicit alternative. The Args block is cleanly separated. Every sentence earns its place without 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 essential aspects: purpose, alternative usage, parameter meaning, and output content. An output schema exists, so return details need not be fully spelled out. The only gap is missing info about pagination or result limits, which is often relevant for a list operation, but the tool is simple enough that this does not undermine completeness.

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 0%, so the description must compensate. It provides an Args section that explains 'organization_id: The organization ID to list devices for,' adding meaningful semantic context beyond the schema's bare string type. For a single parameter, this is sufficient, though it could include format hints or examples.

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 opens with a clear verb and resource: 'List devices in an Orb Cloud organization with stable configuration details.' It specifies what the tool does and the scope of data (stable configuration), distinguishing it from sibling tools like get_device_telemetry.

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?

The description explicitly names an alternative: 'For real-time connectivity and performance scores, use get_device_telemetry instead.' This tells the agent when not to use this tool and directs to the correct sibling, satisfying the highest bar for usage guidance.

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