diagnose_contam_project

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

No annotations are provided, so the description carries full disclosure burden. It states the tool 'inspects' but fails to clarify if it's read-only (likely) or produces side effects, and omits what the tool returns (file list? diagnostics report? missing references?).

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?

Single sentence is efficiently structured with the conditional clause first. However, it may be overly terse given the lack of schema documentation; an additional sentence explaining parameter relationships would improve utility without violating 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?

For a 4-parameter diagnostic tool with zero schema descriptions and no output schema, the description is incomplete. It covers the high-level purpose but lacks necessary details about how to use the parameters (e.g., relationship between projectPath and workingDirectory) or what diagnostic output to expect.

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?

With 0% schema description coverage, the description must compensate for all 4 parameters. While 'referenced support files' hints at projectPath and 'nearby candidate matches' implies workingDirectory/searchRecursively, it provides no explicit parameter documentation, types, or constraints (e.g., maxMatchesPerReference is completely unaddressed).

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 identifies the trigger condition ('when a CONTAM project fails to run') and specific actions ('inspect referenced support files and nearby candidate matches'). It implicitly distinguishes from sibling 'inspect_contam_project' by focusing on failure diagnosis and candidate file resolution rather than general inspection.

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?

Provides explicit when-to-use guidance ('Use this when...') with a specific failure condition. While it doesn't explicitly name alternatives, the context ('fails to run') naturally routes away from successful-run tools like 'run_contam_simulation' or general 'inspect_contam_project'.

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