Get Hubitat device

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

Annotations already cover readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well established. The description adds that it returns 'details and current attributes,' but doesn't elaborate on what the response format is (though output schema exists) or any rate-limit/auth nuances. Slight value-add over annotations 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?

Three short sentences, zero waste. The purpose statement, 'Use when' scenario, and exclusion with sibling reference are all packed efficiently. Perfectly front-loaded and 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?

For a single-parameter read tool with full annotations (readOnly, idempotent, non-destructive), good usage guidance, and an output schema present, the description is quite complete. It could mention pagination or the shape of returned attributes, but the output schema presumably covers return values, so this is adequate. The brief mention of 'battery, level' gives a flavor of what attributes to expect.

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 100% so the schema already documents the single device_id parameter. The description reinforces that device_id maps to a Maker API device for fetching a single device's state, which complements the schema. With only one parameter and full coverage, the description doesn't need to overshare; baseline 3 plus the context that the ID identifies the specific device for state retrieval justifies 4.

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 uses a specific verb+resource ('Get a single device's details and current attributes'), clearly distinguishing it as a read operation for a single device. It's not explicitly differentiated from hubitat_list_virtual_devices but does state it covers current state attributes, which helps differentiate from hubitat_list_devices.

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?

Excellent guidance: explicitly states 'Use when' for current state (switch, level, battery, etc.) and 'Do NOT use when' for just needing IDs (alternatively naming hubitat_list_devices). This is an explicit when/when-not/alternatives pattern—exactly the gold standard for this dimension.

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