seedfast_doctor

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the tool surfaces misconfigurations early and returns a multi-line summary with specific fields. While it doesn't explicitly state that it has no side effects (e.g., is read-only), the diagnostic nature implies this, and the description provides enough behavioral context for the agent to use it correctly. It could be slightly more explicit about not modifying anything, but it is quite informative.

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 two sentences, both highly informative. The first sentence states the purpose and the return content, and the second provides crucial usage guidance with the next step. It is front-loaded with the purpose and then flows into usage. There is no wasted words or redundancy; every sentence earns its place.

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 that the tool has no parameters, no output schema, and no annotations, the description must be self-contained. It fully explains what the tool does, what it returns (including specific fields), and how it fits into the workflow (first step, then connections_test). The agent has everything it needs to invoke the tool correctly and interpret the result. The description is complete for a zero-parameter diagnostic tool.

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 the baseline for parameter semantics is 4. The description doesn't need to explain any inputs; it focuses on the output and usage, which is appropriate. It does describe the return content in detail, but that's not parameter-related. The schema already covers the fact that there are no parameters, and the description adds no unnecessary parameter information.

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's purpose: diagnosing the health of the Seedfast CLI environment. It specifies the verb ('diagnoses'), the resource ('Seedfast CLI environment'), and the outcome ('ready to run seedings'). It also distinguishes itself from sibling tools by being the mandatory first check, and explicitly lists the information it returns.

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 gives explicit usage instructions: 'Call this FIRST before any other seedfast_* tool' and tells the agent exactly what to do next: 'if status is OK, call seedfast_connections_test to verify database reachability before seedfast_plan or seedfast_run.' This clearly differentiates when to use this tool versus the siblings and provides a decision tree for the agent.

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