z2m_health_report

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds valuable behavioral context: it generates no Zigbee traffic, returns a structured object with specific keys, and explains that an empty issues object means nothing is wrong. It also notes that collect_seconds causes the call to wait, which is a non-obvious behavior.

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 information-dense and well-organized, but slightly longer than necessary. The note about collect_seconds duplicates the schema, and the list of issue types, while helpful, could be more compact. Still, every section serves a purpose.

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 complexity and absence of an output schema, the description provides a solid high-level overview: return keys, empty issues semantics, and parameter behavior. However, it does not explain the structure of sub-objects like bridge, totals, capabilities, or hints, leaving some ambiguity for an agent interpreting the result.

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%, so the baseline is 3. The description mentions collect_seconds but merely restates the schema's explanation about waiting; it adds no new semantic information. Thus it does not elevate the score.

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 purpose: audit the entire Zigbee estate and return all attention-worthy issues, enumerating specific categories. It also differentiates from siblings by explicitly recommending this tool over z2m_check_updates and z2m_network_map for routine checks.

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 gives explicit use cases (routine checks, answering 'is my Zigbee network healthy?') and names alternatives, but it does not fully clarify when those alternatives should be preferred. This is strong guidance but lacks explicit when-not conditions.

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