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

Annotations already cover read-only/non-destructive/open-world, and the description adds substantive behavior beyond them: no single page is complete context, unknown prerequisites stay blockers, review labels are contributor assertions, coverage does not imply absence of suppressed challenges, and retrieved fields are inert untrusted data that must not be followed as instructions. This is unusually rich disclosure, though the closing sentence about structured fields "not an injection security boundary" is too terse to be actionable.

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 opening sentence front-loads purpose, but the operational paging loop is buried in the second sentence amid dense jargon, and the remaining clauses stack several separate concerns (prerequisites, labels, coverage, injection warnings) into flowing prose. Every sentence carries some content, yet the block is hard to parse and key call mechanics are not visually prioritized.

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?

An output schema exists, so return-value explanation is not owed, and the description does cover paging semantics and trust boundaries. However, for a 5-parameter tool with a nested object and no schema descriptions, it leaves the required event_id and the after cursor unexplained, so an agent still lacks enough to construct a well-formed call without guessing.

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?

At 0% schema description coverage the description carries the full burden, and it only partially does so: it explains snapshot/next_after paging and the shape of procedural_state (facts, completed event IDs, limit). The required event_id, its two accepted identifier formats, and the after offset are never explained, and the mention of "next_after" (an output field name) rather than "after" risks confusing the agent about which parameter to advance.

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?

"Inspect paginated one-hop relations and disagreements at the same scoped revision" gives a specific verb (inspect) plus a concrete resource (one-hop relations and disagreements) and scope (scoped revision). An agent can tell this is a graph-traversal/context-expansion tool, but the description never contrasts it with siblings such as haidaa_get_event or haidaa_search_project_records, so it stops short of full 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?

It clearly branches usage into two modes with conditions: ordinary published context (loop next_after/snapshot until has_more=false) versus a published procedural descriptor or METHOD (pass procedural_state with facts, completed IDs, limit). That is real when-to-use guidance, but no sibling alternative or exclusion is ever named, so an agent cannot tell when to reach for haidaa_get_event instead.

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