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, the description carries the full burden and does so: it declares read-only, lists the exact side effects (git rev-parse/tag/log/merge-base with fixed argument arrays, and `npm view` only when check_npm is true), and states it creates, edits, and deletes nothing. It also discloses the structuredContent return shape, which is above the bar for a no-annotation tool.

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-loads the verdict-scope sentence before constraints, and every sentence is substantive. It is a dense single paragraph that could be broken up, but there is little 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?

For a diagnostic tool with no output schema, the description usefully enumerates the returned fields (verdict, layers, version, autoUpdate, supervisors, readinessWarnings, actions) and the layer semantics. Given the large sibling set, a bit more explicit routing versus brain_sync/brain_reconcile would make it fully complete.

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% and both parameters are fully documented there (project default, check_npm's network behavior). The description only repeats the check_npm/network point already in the schema, so it adds little new parameter meaning beyond the baseline.

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 and resource (read-only self-check of the installed klypix brain) and enumerates the exact verdict layers (VERSION, CLAUDE, CODEX, TOOLS, SESSIONS, HARNESS). It is easily distinguished from siblings like brain_sync, brain_reconcile, or brain_insights, and it names its CLI twin.

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?

Gives a clear triggering question ('is my brain current, correctly installed, in sync, and who is actually live?') and an exclusion ('never recent-chat history'), plus a scope warning not to over-read a clean HARNESS as other hosts working. It does not explicitly contrast against the other brain_* siblings, keeping it short of a 5.

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