shelly_get_info

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

Annotations already declare readOnlyHint=true, and 'Safe, read-only' largely restates that rather than adding new behavioral detail. The description does add that the device may be addressed by id or configured name, which is operationally useful, but says nothing about failure behavior or lookup cost.

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, front-loaded with the purpose and the returned information, then the parameter clarification, then the safety note. No filler; every sentence earns its place.

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?

An output schema exists, so return-value documentation is not required, and annotations cover the safety profile. The only notable gap is error/not-found behavior and how the identifier forms differ, which would help an agent recover from a bad lookup.

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 0%, so the description carries the burden for the single parameter, and it does so: '``device`` is a device id or a configured name' explains the accepted identifier forms beyond the bare 'string' type in the schema. It stops short of format examples or how to obtain a configured name.

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 specific verb ('Identify') and resource ('one device') and enumerates what the response covers (generation, model, firmware, online state, capabilities). It implicitly contrasts with the list-style siblings ('one device'), but never names an alternative such as shelly_list_devices or shelly_get_status to make the boundary explicit.

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 phrase 'one device' hints that this is the single-device lookup as opposed to the list tools, and the field enumeration implies a low-level inventory use case. However, there is no explicit when-to-use statement, no guidance on choosing this over shelly_get_status or shelly_get_config, and no mention of what happens for an unknown device.

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