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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds value beyond them: tests are parsed from files without executing them, results are paged ('follow nextCursor'), and filters combine with AND while list values OR. It does not discuss performance or scan scope limits, but for a local read-only tool this is solid.

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?

Dense but front-loaded: the core behavior and default return shape come first, then usage triggers, then alternatives, then filter/paging mechanics, then an example. No filler sentences, though the opening sentence packs a lot into one clause chain.

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?

With an output schema present, return values need not be re-explained, and the description covers purpose, filtering semantics, paging, and alternative selection. For an 11-parameter filter tool with 100% schema coverage, an agent has everything needed to call it correctly.

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 coverage is 100% (baseline 3), and the description still adds semantics the schema does not state: AND combination across filters, OR within a list, that 'fields' picks other record keys and that 'id' is always present, plus a concrete example object. This genuinely reduces invocation error.

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?

States a specific verb and resource ('Lists a project's tests that match filters') plus the key behavioral distinction that they are read from files 'without running them', and enumerates the default returned fields. It also explicitly differentiates from siblings: test_summary for counts, get_tests for every key of a few ids.

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?

Gives concrete trigger questions ('which tests are skipped and why', 'which tests carry @smoke', 'where a .only was left in') and names the two alternative tools with the condition that selects each. Nothing is left to inference.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, non-destructive), and the description still adds real behavioral contract: no test execution, the id lifecycle ('stay the same when a test moves to another line, but change when its title, describe or file changes'), and that unknown ids surface in notFound rather than erroring. That is exactly the extra context annotations cannot carry.

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?

Purpose and workflow lead, with the id rules and example trailing, so it is front-loaded correctly and reads in one pass. The long enumeration of returned fields (location, describe path, state, condition, reason, tags, annotations, comments, parameters, body hash) is partly redundant against the existing output schema, which costs it a point.

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?

With an output schema present, an annotations-covered safety profile, and 100% schema coverage, the description only needs to carry purpose, workflow, and the id contract — all present. The one gap is guidance on when to override patterns/directory/framework versus accepting the server defaults.

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 coverage is 100% so the baseline would be 3, but the description adds semantics the schema does not: the provenance and mutability rules for `ids` plus a concrete example call, and the 20-id ceiling phrased as a usage constraint. The optional patterns/directory/framework overrides are left entirely to the schema, which is why this is not a 5.

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?

States a specific verb (returns) and resource (tests by id, with scan diagnostics), and explicitly frames it as static analysis ('read from the test files without running them'). The sibling set (find_tests, test_summary, scan_diagnostics) is addressed directly by naming the tools it follows, so an agent can place it without opening any schema.

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?

Explicit sequencing: 'Use it after find_tests or test_summary, for the details of up to 20 tests,' which tells the agent both the workflow position and the batch size limit. It does not state when *not* to use it (e.g. prefer test_summary for bulk aggregate views), so it falls short of the 5 bar.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral context beyond that: the semantic difference between error and warning levels, concrete causes for each, and the fact that answers are paged via nextCursor.

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?

Front-loads the core definition before diving into level semantics, then usage, then paging, then an example. Dense but every sentence carries information; length is justified for a tool with two enum levels the agent must interpret.

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?

With annotations covering safety and an output schema covering return shape, the description needn't explain results. It competently covers purpose, triggers, level semantics, and paging, though it says nothing about how the path/patterns/directory/framework parameters interact, which an agent might occasionally need.

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% and the 8 parameters are well documented inline, so the baseline is 3. The description's example ({'levels': ['error']}) and its 'follow nextCursor' note restate what the schema already specifies for levels/cursor, adding marginal value only.

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?

States a specific verb and resource ('Lists the problems test-inventory found while reading the test files') and explicitly demarcates scope versus siblings: 'They are about reading the code, not test failures.' An agent can tell this apart from test_summary/find_tests/get_tests without opening any schema.

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?

Gives explicit triggering conditions tied to sibling outputs: 'Use it when another tool reports scanErrors, or to check why a test is missing or notLoaded.' It also disambiguates the common confusion (reading problems vs test failures), leaving little to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavior: counting happens 'without running them', filters are conjunctive ('states, tags and grep count only the tests they match'), grouping is sorted by name and paged, and untagged tests fall into no tag group.

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?

Front-loaded with purpose and the primary use case, then semantics, then an example. Dense but nearly every clause carries information; only the example and the tag-edge-case sentence push it toward run-on length.

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?

With an output schema present, return values need not be explained. For a 9-parameter, zero-required aggregation tool the description covers counting semantics, filter conjunction, grouping, pagination and the alternative tool, leaving no significant gap for correct invocation.

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 coverage is 100%, so the baseline is 3, but the description goes beyond the schema: it explains what groupBy does (adds per-file/per-tag counts, sorted by name, paged), that cursor paging requires keeping other arguments the same, and the no-tag edge case. That is genuine added meaning over the field descriptions.

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?

States a specific verb and resource ('Counts a project's tests by state... and by tag and annotation, from the test files, without running them') and scopes the source of truth. It also names find_tests as the sibling that lists tests, so an agent can distinguish the two without opening either schema.

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?

Explicit routing: 'Use it first, for questions such as how many tests are skipped, or which files or tags have the most skipped tests; use find_tests to list the tests themselves.' Both the when-to-use and the when-to-use-something-else are stated.

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