watchface_list_devices

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

With no annotations, the description does disclose that this is a network fetch against a specific cloud endpoint and that non-matching hardware is silently filtered out. It does not cover auth/network requirements, latency, failure modes, or what the discovered entries look like, which matters for a discovery tool with no output schema.

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?

Three tightly packed sentences with the core capability and supported hardware front-loaded, followed by scope and port notes. The port sentence is awkwardly worded but not padding.

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 zero-required-param discovery tool with no annotations and no output schema, the agent still needs to know the shape of the returned device list (names, model identifiers, LAN vs cloud) and the meaning of timeoutMs. The description covers supported hardware and the source endpoint but leaves the return contract and one of two parameters unexplained.

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 only 50%: `port` is documented well in the schema, but `timeoutMs` is undocumented anywhere except its 45000 default, and the description never explains what it times out or what happens on expiry. The sentence 'PIXOO64/TimeGate targets include Hardware and version-specific ports' is vague and reads more like return-value commentary than parameter guidance, so it fails to compensate for the coverage gap.

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?

States a concrete verb (List) and resource (selectable devices), enumerates the exact supported model families, and names the upstream endpoint. It is clearly distinguishable from siblings like watchface_get_device_info, which target a single device.

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?

Usage is implied: you call this to discover devices before targeting them with the per-model tools. However, there is no explicit 'use this when...' statement, no ordering guidance (e.g., call before get_device_info), and no when-not condition beyond the hardware filter.

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