get_aria_health

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds critical behavior beyond that: it explains that the tool reports OFFLINE on a 503 response from the platform and 'never raised,' meaning it remains usable even when Aria is down. It also discloses return fields (overall_status, healthy, system_time_ms, details), which the annotations do not cover.

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 well-structured with a summary line, a usage/behavior paragraph, and an Args section. It is somewhat verbose (e.g., repeating '[READ]' despite readOnlyHint annotations) but every sentence carries relevant information, and key points are front-loaded. A slight trim could make it tighter, but it is not wasteful.

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 tool with one optional parameter and no output schema, the description covers purpose, return values, edge-case behavior, and usage context. The only gap is that 'details' in the return value is not elaborated, but given the tool's simplicity and the use cases provided, this is a minor omission.

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 0%, so the description carries the full burden. The 'Args:' section states 'target: Aria target name from config; default when omitted,' which adds meaning beyond the schema's bare property. This clearly explains the parameter's purpose and optionality, though it could be more specific about where config names come from or how to list valid targets.

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 states a specific verb and resource: 'Check Aria Operations platform node status (ONLINE/OFFLINE).' It clearly distinguishes this from sibling tools like get_resource_health by focusing on platform-level health and explicitly noting that per-service breakdown is not exposed. The scope is unambiguous.

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?

Provides explicit when-to-use guidance: 'Use this to verify Aria Operations is functioning before investigating monitoring blind spots.' It also gives an alternative: 'When status is ONLINE but data looks stale, check list_collector_groups next.' The limitation 'per-service breakdown is not exposed by the public API' effectively states when not to use it, offering alternatives and exclusions.

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