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

Goes well beyond the annotations by enumerating the exact writes it performs (registering LMCP in apps that lack it, repairing entries whose command no longer exists) and by defining the failure contract: anything it can't fix comes back in `needs_you` with the exact step. It does not say whether repairs are reversible or what it needs permission-wise to write, so the destructiveHint=true profile is softened but not fully explained.

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 scope statement, then the fix behavior, then the `needs_you` escape hatch, then the trigger — every clause earns its place despite the length. It is one dense block rather than separated lines, which costs a bit of scannability but no content is wasted.

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 broad self-repair tool with an output schema present, the description covers scope, mutation limits, and the shape of the unfixable-results channel, which is enough to call it correctly. It stops short of describing how long a full check takes or whether it should be run before any other troubleshooting step.

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?

The single parameter `confirm` is fully documented in the schema as ignored/legacy, and the description correctly stays silent about it rather than adding noise. With 100% schema coverage and nothing extra to say, this is the baseline case — the description neither helps nor misleads on parameters.

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 (checks ... and fixes) over a specific resource set (AI app connections, macOS permissions, integrations, pending LMCP update), and the breadth of scope implicitly separates it from narrow siblings like permissions_status or lmcp_state. It never names an alternative though, so an agent must infer the boundary against run_diagnostics / lmcp_upgrade_diagnostics itself.

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?

"Use it when LMCP 'doesn't work' in some app" gives a concrete, recognizable triggering condition, which is exactly the entry point an agent needs. There are no exclusions or named alternatives (e.g. when to prefer run_diagnostics or list_missing_permissions), so routing among the several diagnostic siblings is still left to inference.

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