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

Annotations only declare readOnly/idempotent/non-destructive, so the description carries the interpretive burden and does so thoroughly: it explains null semantics for non-completed tests and unmeasured tools, that install_rate is null (not 0) when install_rate_hidden_reason is no_installable_tool, that fallback guesses are included in counts but excluded from loss verdicts, that outcome counts vanish when run detail is unavailable, and that the feature and visibility.read are required.

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 first sentence is well front-loaded, but the remainder is a dense, run-on enumeration of output fields packed into a handful of overloaded sentences, several of which repeat 'Each test includes...' openings. Length is partly justified by the absence of an output schema, but the structure is hard to scan.

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 no output schema, no annotations beyond safety flags, and a complex payload, the description is unusually complete on return semantics: it enumerates the returned fields, null conditions, comparison_key behavior, and measurement caveats. It stops short of telling the agent how to source test_ids, the one thing needed to actually call the tool.

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 0% and there is a single parameter (test_ids), so the description must compensate. It constrains the parameter meaningfully — '1 to 8 distinct project-owned tests' — implying these are project-owned test UUIDs and matching minItems/maxItems, but it never defines where an agent obtains valid test IDs, leaving a real gap.

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 opening sentence gives a specific verb (Read), a specific resource (per-model cells), and a scope (1-8 distinct project-owned tests from test history), which is clear enough for an agent to identify the operation. However, it does not explicitly differentiate itself from closely related siblings such as devtune_get_agent_picks_test or devtune_get_agent_picks_history, so sibling disambiguation is left to inference.

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 provides some operative guidance — 'Compare equal keys only and break history lines when they change', 'report the pick rate alone and say why' — and states the required Agent Picks feature and visibility.read permission. It never says when to choose this tool over the adjacent agent-picks siblings, so usage context is only implied.

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