Session Doctor

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

The description discloses key behavioral traits beyond annotations: read-only by default with opt-in modification via repair=true, specifics of repair (only touches specific contradiction state), legacy artifact handling, and terminal findings enumeration. This adds valuable context not present in annotations (which only hint at idempotency and non-destructiveness).

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 verbose and dense with technical details (e.g., 'v3.6.0', 'pre-v3.2.0 corruption', '~38% rate'). While every sentence adds value, the length and jargon may hinder quick comprehension. Structuring with bullet points or shorter sentences would improve conciseness.

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 (6 parameters, multi-faceted audit), the description covers major behaviors: read-only default, repair mechanics, legacy enumeration, terminal findings. It lacks description of output format (beyond noting the 'repaired' array) but adequately addresses the core functionality. The absence of an output schema raises the burden, but the description meets most requirements.

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 0%, so the description bears full burden. It explains repair, include_legacy, and include_terminal_findings parameters with precise semantics. However, limit, caller, and response_format are not described, leaving gaps. The explanation for the explained parameters is clear and adds meaning beyond the schema enum/default values.

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 clearly states the tool performs an 'operational audit' across durable sessions, enumerating specific categories like open/stale/blocked cases, legacy metadata, evidence asks, Grok errors, and token noise. This distinguishes it from sibling tools like session_list or session_read by being a comprehensive health check rather than a simple listing or retrieval.

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 implies usage for auditing session health and troubleshooting, but does not explicitly state when to use this tool versus alternatives. It lacks direct comparisons or exclusions, though the detailed behavior (read-only default, repair opt-in) provides contextual guidance.

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