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

With no annotations supplied, the description carries the full burden and does so well: it declares 'Read-only', explains that divergent DB copies are KEPT and the repo file is deliberately NOT served (citing ADR 0042), and warns that `fait: false` is a defect rather than silence. Missing pieces are narrower — it never states the response shape (structured rows vs. prose) or anything about scope of the scan.

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?

Purpose and source of truth are front-loaded, and the defect triple is presented in a scannable, parenthesized form with remediation inline. The closing motivation ('a served guide that lags the repo makes every agent apply gestures that no longer exist') is rhetorical but earns its place as the reason an admin should care; the density of internal codes makes it heavier than ideal.

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 annotations and no output schema, the description effectively describes the return payload by enumerating the report's fields (seeded, updated, unchanged) and the three defect codes plus the `fait` flag. The only real omission is any indication of output format or how large the report can be.

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% for the single optional `_org` parameter, and the description never mentions it, so nothing is added beyond the schema. The gap is limited because `_org` is an optional, conventionally named platform scoping parameter used across sibling tools and the description's 'this server's boot' framing already implies instance-level scope.

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 names a specific resource and scope: the boot-time seeding outcome for `oto_mcp/guides/*.md`, reported as seeded/updated/unchanged. That is far more precise than the name alone and separates it from `oto_guide` / `oto_guide_v2` (consumer-facing guide reads). It stops short of explicitly distinguishing itself from the sibling `oto_admin_instance_health`, so an agent must infer the boundary from the 'PLATFORM GUIDES' qualifier.

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?

Usage is implied rather than stated: an admin reads this to diagnose why served guides are stale, and the description gives concrete remediation for one case ('run `scripts/aligner_guides_plateforme.py` once'). There is no explicit 'use this when X, use `oto_admin_instance_health` when Y' routing, and no stated prerequisites for the two other defect codes beyond naming them.

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