Brain doctor — is this brain current, wired, and in sync?

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It explicitly states 'Never writes' and 'Read-only', clarifies that SESSIONS is never recent-chat history, and warns that a clean HARNESS reading does not mean other hosts have loaded the files. These caveats prevent real misinterpretation of the tool's behavior.

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 dense but each sentence earns its place: it front-loads the read-only nature and output shape, then covers scope caveats and the CLI twin relationship. It could be slightly better organized with bullets, but it is not bloated and the important caveats are included.

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 diagnostic tool with two well-documented parameters and no output schema, the description provides the core verdict categories, the intended use case, and key limitations. It does not spell out exact verdict values or failure behavior such as network errors from `check_npm`, so it is strong but not fully exhaustive.

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%, so the schema already fully documents both `project` and `check_npm`. The description's references to 'optional npm currency' and 'projection drift' add mild context but do not materially extend what the input schema provides. Baseline 3 is appropriate because the description adds only peripheral color.

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 states a specific verb and resource: 'Read-only self-check of the installed klypix brain' delivered as one verdict covering VERSION, CLAUDE, CODEX, TOOLS, SESSIONS, and HARNESS. It makes the tool's diagnostic role unmistakable and distinguishes it from sibling tools like brain_ask, brain_sync, or project_map_scan by focusing on installation health, synchronization, and liveness.

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 gives a clear trigger question: "Use to answer 'is my brain current, correctly installed, in sync, and who is actually live?' without file-spelunking." It also provides important scope guidance about HARNESS and which components get behavioral verdicts. It does not explicitly name sibling alternatives or say when not to use it, but the usage context is clear and not misleading.

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