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

Annotations already establish the safe, read-only, closed-world profile. The description adds genuinely useful non-annotation context: flakiness is only computed for roughly the last 7 days, only flaky tests are returned, and the payload includes a scanned-test count with how many had flakiness computed. No auth or rate-limit detail, but the disclosure goes meaningfully beyond the annotations.

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 tight sentences with no filler; the what-it-returns content is front-loaded and the 7-day limitation is attached directly to the flakiness concept rather than buried at the end.

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?

No output schema exists, so the description carries the return-value burden and does so well, naming flake rate, build, environment, and the scanned count. It stops short of describing ordering or empty-result behavior, but for a zero-required-parameter read tool this is nearly complete.

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 the baseline is 3. The description still adds value by explaining a constraint the schema hints at only partially: the 7-day flakiness computation window versus the 59-day serviceable range, which tells the agent results will be sparse or absent for older fromDate values.

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 (Lists) and a precise resource (tests marked flaky, i.e. passing/failing intermittently) scoped to a date range, and enumerates the returned fields (flake rate, build, environment). An agent can distinguish this from report/exception siblings like getTestTrends or postTestExceptions without opening the 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?

The date-range scope and the 'returns only flaky tests' framing imply when to reach for this tool, and the 7-day flakiness window is a useful caveat. However, no alternative tool is named and there is no explicit when-not guidance, so usage is only implied rather than directed.

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