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

Beyond the readOnlyHint annotation, the description thoroughly discloses complex behavior: the two-lane merging logic (SMP vs AP), the exact verdict definitions (available/degraded/unreachable/no_data), how degraded counts as available for uptime, the monthly target semantics (not contractual), and temporal attribution (pre_epoch). This goes far beyond what the annotation provides and avoids any contradiction.

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 lengthy but well-structured: a one-line purpose, then a detailed but organized explanation of semantics and return content. Each sentence contributes substantively (merge logic, verdict definitions, return fields, historical scope). It is appropriately detailed for a tool with complex behavior, though slightly verbose in the middle section.

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 the absence of an output schema, the description fully specifies the return contents (per-lane UptimeBuckets, combined lane, headline uptime ranges, service-level target, host-change markers, incidents), historical coverage, and edge cases like pre_epoch attribution. An agent has enough information to understand exactly what it will receive and how the data is derived.

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 schema already documents id, to, from, and resolution with clear meanings. The description adds minimal new semantic value—only the note about pre_epoch attribution, which is contextual but not tied to a specific parameter. The baseline of 3 is appropriate since the schema carries the parameter documentation load.

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?

States a specific verb and resource: 'Get a participant's measured availability' and elaborates on the probe-measured reachability of one Peppol ID over time. The description clearly defines what the tool does and the return structure, making it distinct from siblings like get_participant_stats or get_participant_history, even without naming them.

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 explains the tool's scope and semantics but provides no explicit guidance on when to use it versus alternative participant-related tools (e.g., get_participant_stats, get_participant_history). Usage context is implied from the function name and detailed output, but no when-to-use or when-not-to-use directives are given.

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