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 fully carries the transparency burden and does so impressively: it states 'Never writes' and enumerates the exact subprocess side effects ('git rev-parse / tag --list / log / merge-base with fixed argument arrays, and `npm view` only when check_npm is true'), plus 'creates, edits, and deletes nothing'. It also discloses the HARNESS limitation, which is a behavioral trait beyond what a schema could convey.

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 and front-loaded with the core purpose, then adds a use case, safety guarantees, and a critical HARNESS caveat. There is minor redundancy (read-only stated multiple times), but no filler sentences; the length is justified by the tool's complexity and the lack of annotations/output schema.

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?

This is a no-output-schema, no-annotation tool with 2 parameters and a complex verdict, and the description covers the main gaps: what the verdict contains (six sections), key exclusions (SESSIONS is not chat history), and the HARNESS misinterpretation risk. It does not detail the exact verdict format or how the agent should act on each section, which would make it fully complete, but it provides solid actionable context.

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 coverage is 100% and both parameter descriptions in the input schema already fully explain `project` and `check_npm`, including defaults and the network call. The prose description adds no additional parameter-level meaning; it merely reinforces the same semantics, so the baseline 3 applies.

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 opens with a precise verb and resource: 'Read-only self-check of the installed klypix brain, as ONE verdict', then names all six verdict sections (VERSION, CLAUDE, CODEX, TOOLS, SESSIONS, HARNESS). It distinguishes itself from related tools by stating what it is not ('never recent-chat history') and by naming its CLI twin, so an agent can identify it uniquely among siblings.

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?

It gives an explicit use case: 'Use to answer "is my brain current, correctly installed, in sync, and who is actually live?"' and forbids inferring host status from HARNESS ('do not report a clean HARNESS as "Cursor/Cline/Windsurf/Copilot is working"'). It also clarifies scope limits for CLAUDE/CODEX verdicts, but it does not explicitly name alternative tools for other situations, so it stops short of a full when-not-to-use comparison.

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