site_health

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that the operation is a read ('Get'), enumerates the status layers, and adds the exact-match input constraint. However, it doesn't describe error behavior for mismatched site names, the output/return format, or any side effects — though for a low-risk read operation the risk profile is modest. Adds useful context but has gaps.

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 with zero waste. The primary purpose is front-loaded in the first sentence, and the operational constraint follows in the second. Every word earns its place with no redundancy or filler.

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 no output schema and no annotations, the description covers the essentials: what the tool does and what the parameter requires. It could add the return format of the health status values, but the core calling information is complete and an agent can invoke this tool correctly with what's provided.

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 must compensate, and it does: the second sentence clarifies that the 'site' parameter is a name that must exactly match one from list_sites. This adds meaningful semantic information beyond the bare schema, which only types it as a required string. The description fully compensates for the coverage gap for the sole parameter.

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 ('layered health status') and enumerates exactly which layers are covered (circuit, power, core, access). This distinguishes it from siblings like list_sites (which lists sites) and degraded_sites (which finds problem sites), though it doesn't name them explicitly. Clear purpose with minor room for explicit sibling differentiation.

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 second sentence gives a concrete, actionable constraint: 'site must exactly match a name returned by list_sites.' This tells the agent to call list_sites first and use an exact name value. It implies usage context well but stops short of stating when not to use this tool or naming alternatives as the preferred choice for other scenarios.

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