select_tests

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

With no annotations, the description carries the full burden and does well: it discloses the return content (command + reason per test), the scope of the change (committed and uncommitted), and what an empty result means. The main flaw is that it references a 'mode' value that does not appear in the input schema, leaving the agent unsure how mode is set or discovered.

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?

Three sentences, front-loaded with the call condition and the instruction to prefer the returned command over the full suite. The trailing 'mode' sentence slightly muddies an otherwise tight structure by introducing a term the schema never defines.

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?

An output schema exists, so return values need not be explained, yet the description usefully adds the outcome semantics an agent needs before invoking (selective vs full, empty command). The only completeness gap is the unbacked 'mode' reference, which the schema does not expose as a parameter.

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?

Schema description coverage is 100%, so all four parameters (base, max_tests, repo_path, include_uncommitted) are already well documented in the schema, making 3 the baseline. The description adds no parameter-level meaning and instead introduces an unexplained 'mode' concept not present 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 uses a specific verb+resource ('select tests', 'returns the command that runs only the tests your change can affect') and even describes the output shape (command plus per-test reason). It does not name or contrast the siblings triage_failure and explain, so it stops short of full sibling differentiation.

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 states explicit timing ('Call this before running tests after changing code') and an explicit alternative to avoid ('Run that command instead of the full test suite'). It also covers the edge behaviors: full mode means run the whole suite, and an empty command in selective mode means no tests are affected.

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