diagnostic_summary

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known safe. The description surpasses the annotation burden by disclosing: it reveals only the caller's own config (privacy boundary), it never touches fleet rows or vault secrets (so no exfiltration risk despite appearing as a diagnostic), it asserts severity rather than assuming it (naming the fleet via env vars makes shared surfaces 'named problems', naming none results in 'not_asserted' and changes nothing), and it returns a verdict with named problems and fixes. This is rich behavioral context beyond the annotations — the severity-assertion nuance in particular prevents an agent from misreading the tool's effect on other systems. No contradiction with annotations.

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 a single dense paragraph (plus a second paragraph on severity) — it front-loads the core verdict and the list of checked surfaces, which is the highest-value content. Every sentence earns its place, there's no fluff, and the key differentiators (ungated, own-config-only) are placed prominently. It's not maximally concise (the second paragraph is a nuance that could arguably be trimmed), but it is efficiently structured and information-dense without repetition.

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 (a multi-surface diagnostic) and the absence of an output schema to document the return value, the description carries the full burden. It covers what it checks (the elastic list), what it returns (verdict with named problems + fixes), its gating behavior (ungated), its privacy boundary (own config only), and the severity-assertion variant behavior. There is no output schema and no requirement to explain return values, but the description does explain the verdict shape — which is exactly what an agent needs to interpret the result. The only thin area is the app_id parameter semantics over the default, but the overall coverage is strong for a tool of this scope.

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% — the schema only has app_id (string, optional, default ''). The description adds meaning by explaining how identity bindings and app_id's manifest fit into the check ('your app_id's manifest + resolved permissions' and 'identity bindings'). It doesn't explicitly explain the semantics of 'app_id' as a filter or override, but the optional nature (default '') and the phrase 'your app_id' convey that this is the identity being diagnosed. The description compensates well for the 0% coverage by telling the agent what the app_id relates to, though it could be sharper about whether app_id can be empty.

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 identifies a precise diagnostic verb ('self-check'), the resource (the willow-mcp install), and then enumerates exact system surfaces it inspects (SOIL store, Postgres, schema mapping, manifest, identity bindings, queue, egress lease, fleet wiring). This is far more specific than the tool name 'diagnostic_summary' alone. It also carefully disambiguates: it reveals only the caller's own config, never fleet rows or vault secrets, which distinguishes it from fleet-level status tools like 'fleet_status' or 'grove_fleet_status'.

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 explicitly says the tool is 'ungated on purpose: it must answer even when your manifest or database is misconfigured' — that's a strong when-to-use statement (run it when you suspect broken wiring). The final paragraph adds depth about fleet severance assertion, explaining how to control behavior via env vars and what happens when you name none ('not_asserted'). What is missing is an explicit 'when NOT to use this in favor of sibling X' — instead it relies on being the natural diagnostic tool among siblings, and there's no direct sibling (like env_check or fleet_health) that it routes away from. Still, the guidance for when to use it is above-average.

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