list_devices

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. The 'refresh' parameter implies a network call to the Wyze API, but the description doesn't disclose auth requirements, rate limits, potential latency of the refresh operation, or what 'current status' means (cached vs live). For a tool that hits an external API, this is a significant gap.

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?

Two sentences that are concise and front-loaded with the primary action. The description is efficiently sized with zero filler. It loses a point only because mentioning the optional type filter in the description is somewhat redundant with the schema's enum documentation.

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 listing tool with no output schema and no annotations, the description is reasonably adequate but could do more. It doesn't describe the return format/structure of device data, doesn't mention pagination or volume concerns when listing 'all' devices, and doesn't explain what the refresh parameter actually changes behaviorally. Given it's a simple listing tool, this is minimally 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 100%, with both parameters (type and refresh) well documented in the schema. The description adds the 'filter by device type' context that maps to the type parameter, but doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate given full schema 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 verb (List), the resource (all discovered Wyze devices), and what's returned (current status), with optional filtering by device type. It distinguishes the listing scope from the sibling control/status tools since none of the siblings list all devices. A 5 isn't earned because it doesn't explicitly differentiate from get_device_status, which is a related status-focused tool.

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 implies this is the entry-point tool for discovering devices, which differentiates it from the control_* and get_device_status siblings. However, it doesn't explicitly say WHEN to use this vs get_device_status (which also reports device status) or when-not to use it. The filter option hints at selective use but no explicit guidance on choosing alternatives is present.

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