ddflow_reviewers_detect

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

No annotations are present, so the description carries the disclosure burden. It clearly states the probing/reporting behavior and the conditional side effect of write=true (adding findings to .ddflow/config.toml). It does not cover error or timeout behavior, but for a simple one-flag tool this is adequate.

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 sentences with no wasted words: the operation is front-loaded, then the use case, then the parameter behavior. Every clause contributes to correct invocation.

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 tool with no output schema, the description states what will be reported (serving model servers and pretraining families), why it matters (critic gate), and how to persist findings. It does not specify return format or no-server-found behavior, but the core facts needed to invoke correctly are present.

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 schema has 100% description coverage for the single write parameter, so the baseline is 3. The description adds slight extra context by naming the exact config file path, but the parameter meaning is already well documented in the schema.

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 names a specific action ('Probe well-known local ports'), a concrete target (OpenAI-compatible model servers), and a distinctive deliverable (each model's pretraining family). It clearly differentiates this from siblings like ddflow_reviewers_list by emphasizing local detection rather than listing known reviewers.

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?

It explicitly frames when to invoke the tool: 'Use this to find a reviewer from a DIFFERENT family than yourself — which the critic gate requires.' This is clear usage context, though it does not name alternatives or state when not to use it, so it stops short of a 5.

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