doctor

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context that env/compat/cache fold related validation tools and includes an operational warning ('Do not grep the Zeus engine tree for first green'), which is useful, but it does not clarify what the output looks like or what 'first green' means.

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 compact and front-loads the detail values early. It avoids fluff, and each section adds some information, though the phrasing 'fold' and the telegraphic 'Health / doctor.' make it less polished than ideal.

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 simple optional-parameter tool with read-only and idempotent annotations plus an output schema, the description is mostly sufficient. The main gaps are ambiguity about what 'fold' means and the unexplained reference to 'first green,' as well as no explicit differentiation from the diagnostic sibling tools.

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 single parameter detail has no schema description and no enum, but the description supplies the allowed values: health | env | compat | cache | all. It also maps env/compat/cache to validate_env, compat_check, and semantic_cache_status, giving the parameter more meaning than the schema alone. It does not spell out what each value returns, though an output schema exists.

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 noun fragment, 'Health / doctor,' which mostly restates the tool name and the domain rather than stating a specific verb and resource. It does enumerate detail options (health | env | compat | cache | all), which give partial purpose, but it does not distinguish doctor from sibling tools like diagnose_error, readiness_check, or smoke_test_agent.

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 provides a follow-up workflow condition ('If the user already gave a Zeus URL or sample name, next call set_prereq...'), but it does not say when to use doctor versus the diagnostic sibling tools. The line about env/compat/cache folding validate_env, compat_check, and semantic_cache_status hints at coverage but never explicitly states selection criteria or exclusions.

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