spine_doctor

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

No annotations exist, so the description carries the burden. 'Check' implies a non-mutating read and the text discloses what it inspects, but it never explicitly states there are no side effects and doesn't explain behavior when Spine is absent or the CLI probe fails.

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?

Two short sentences: what it checks first, then when to call it. No filler and the content is front-loaded.

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?

An output schema exists, so return values needn't be described, and zero parameters mean no schema gaps. The only missing piece is how this differs from spine_cli_info, which matters for a diagnostic tool in a crowded sibling set.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly signals no input is required.

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 set: checks Python/MCP SDK versions plus detected Spine CLI paths and versions. Clear what it reports, but it does not distinguish itself from the sibling spine_cli_info, which plausibly overlaps in reporting CLI information.

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 an explicit triggering condition — call first when export or import fails — and a discovery use case (is the editor installed and usable from the CLI). It lacks any when-not guidance and never routes the agent away from the similar spine_cli_info sibling.

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