timps_flaky_test_detective

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

No annotations are provided, so the description must carry the full behavioral transparency burden. It mentions reading pytest failure cache and scanning for specific flake sources, but doesn't disclose whether the tool only analyzes the pytest cache or also runs tests, what side effects (if any) exist, or what the output format looks like. For a diagnostic tool, the agent would benefit from knowing whether this is read-only or might execute tests.

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 concise at two sentences, front-loading the purpose with the verb 'identify.' The first sentence is actionable, and the second provides context about the data source. No wasted words, but it's minimal.

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?

There is no output schema and no annotation, and the only parameter is unexplained. The description tells the agent what it does but not how to invoke it, what inputs are expected, what outputs are produced, or what side effects might occur. For a tool that presumably needs a repo path going into a pytest cache, this is insufficient for reliable invocation. It also doesn't differentiate from timps_flaky_test_hunter or other similar 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 input schema has one parameter (repo_path) with no description, and schema coverage is 0%. The description never mentions repo_path or what it should contain (e.g., a path to the project root). The description assumes a context but provides zero parameter guidance. With only 0% schema coverage)Skip, the description must compensate, but it doesn't address the parameter at all.

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: identifying flaky tests by scanning for timing dependencies, random data, and external HTTP calls. The verb 'Identify' plus the specific resource ('flaky tests') and the three detection heuristics make the tool's function clear. It's distinct from siblings like timps_test_intelligence or timps_log_pattern_analyzer, though not explicitly differentiated.

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 mentions it reads the pytest failure cache but provides no guidance on when to use this tool over alternatives like timps_flaky_test_hunter or timps_test_intelligence. There's no mention of prerequisites (e.g., needing a configured repo_path), limitations, or exclusions. A specialized tool like this would benefit from clear advice on when to choose it over the similarly-named timps_flaky_test_hunter.

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