detect_testfly

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

With no annotations, the description carries the full burden, and it does well: it discloses the detection mechanisms, that it walks up parent directories, and that the result gates the generation framework. It doesn't explicitly state the tool is read-only or describe error cases, but for a detection tool this is sufficient behavioral context.

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 dense sentences with no filler. The core detection semantics come first, followed by actionable downstream guidance. Every clause 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?

The description covers what the tool detects, how detection works, and what the agent should do with the result. Since there is no output schema, it could go slightly further in describing the exact return shape for both true and false cases, but the key decision signal is clearly stated.

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 input schema already documents project_dir with 100% coverage, including the optional path and default to the server's working directory. The description reinforces the current-working-directory concept but adds little beyond the schema, so the baseline of 3 is appropriate.

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 uses a specific verb with a concrete resource: it detects whether the working directory is inside a TestFly project. It names exact evidence files and dependency coordinates, making the purpose unambiguous and clearly distinct from sibling tools like detect_selenium_boot or the code generators.

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 gives explicit guidance to call this tool before generating Java code and tells the agent exactly how to respond to detected=true. It doesn't spell out what to do when detection returns false, but the conditional is clear enough for correct tool selection.

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