z2m_bridge_info

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

Annotations already state readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description reinforces this with 'Read-only' and adds useful context about the return format (JSON object) and the large size of the full configuration when include_config is true. This goes slightly beyond the annotations, though it doesn't disclose any safety-relevant edge cases.

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 three sentences, front-loaded with the purpose, then usage guidance, then parameter caution. Every sentence carries necessary information with no redundancy or fluff.

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 simple read-only status tool with one optional parameter and no output schema, the description is complete: it lists return fields, provides usage context, differentiates from siblings, and warns about the large config. No important information is missing.

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% for the single parameter, so the schema already fully explains include_config. The description adds the hint to use it 'only if you need' the full config, which is mildly helpful but does not add substantive semantic meaning beyond the schema.

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 ('Get') and resource ('Zigbee2MQTT bridge status'), enumerating the exact attributes returned (version, coordinator, channel, PAN ID, etc.). It clearly distinguishes itself from siblings by positioning itself as the starting point and explicitly naming alternatives for different tasks.

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 provides explicit when-to-use guidance: 'Start here to understand the estate' and tells the agent to use z2m_health_report for problems or z2m_list_devices for individual devices. It also advises to 'set include_config only if you need the full configuration', giving clear conditional usage.

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