openclaw_device_pair_list

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

No annotations are provided, so the description carries the full burden. It states the underlying API call (`device.pair.list` (operator scope)) and that it lists both pending and paired devices. However, it does not disclose any potential side effects, authentication requirements, rate limits, or response structure. The description provides basic context but lacks depth.

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 extremely concise with three sentences that front-load the purpose, include a practical usage hint, and mention the underlying API. Every sentence earns its place with no wasted words.

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 the tool's simplicity (list operation, one optional parameter, no output schema), the description is nearly complete. It explains what is listed (pending and paired devices), suggests a workflow context, and references the underlying API. Minor gaps include lack of specification about pagination or response format, but these are not critical for a straightforward listing tool.

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 100% for the single parameter 'instance', which already has a detailed description in the schema. The tool description adds no additional meaning beyond what is already in the schema, so it meets the baseline of 3.

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 function: 'List pending and paired devices known to the gateway.' It uses a specific verb (list) and resource (devices), and distinguishes it from sibling tools like openclaw_device_pair_approve and openclaw_device_pair_reject by focusing on listing rather than mutating device pairings.

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 provides a specific use case: 'Useful for confirming that this MCP's device shows up in ''pending'' before approval.' This implies when to use the tool (before approval) but does not explicitly state when not to use it or mention alternatives beyond the implicit flow.

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