get_replication_divergence

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

With no annotations at all, the description carries the full burden and does much of it: it discloses the internal state vocabulary ('behind' for sub-threshold lag or an event left open by a restart, 'unobserved' for a disconnected replica) and explicitly warns that 'eventsUnavailable: true' means unreadable events, not absence. It does not mention permissions, whether it reads live or historical data, or scrape cost, but it is the tool's only behavioral source and is unusually candid about failure semantics.

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?

Front-loaded with the verb and resource, then the output shape, then the usage trigger — a sensible order. The parenthetical return-value enumeration is dense and long, but every sentence carries information; nothing is 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?

There is no output schema, so the description must explain return values, and it does: the offset-gap series fields, the event stream, the 'behind'/'unobserved' states, and the eventsUnavailable caveat. A read tool with zero required parameters needs little more; only return units/pagination and any auth or connection context are 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%, including per-field defaults, so the baseline is 3. The description adds no parameter-level meaning beyond the schema and never mentions limit, startTime, or instanceId or the differing default windows (1h vs 24h).

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 opens with a specific verb+resource+scope ('Get replication divergence for a primary') and enumerates the returned series fields and divergence events, so the agent knows exactly what this produces. Differentiation from most siblings is implied by the replication-specific framing, and the explicit 'Companion to get_anomalies' line separates it from the generic anomaly tool, though no other siblings are named.

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 gives a concrete trigger condition ('when a replica is falling behind under write load') plus the diagnostic question the tool answers ('whether the gap is growing, at a ceiling, or not closing after the burst'). It names one alternative/complement (get_anomalies) but offers no explicit exclusions or guidance versus get_latency_regressions or get_retry_amplification.

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