get_case_execution_history

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

The description's existing annotations declare readonly and non-destructive, and the description goes far beyond them by revealing the exact scenarios: summary figures are nested rather than top-level, passRate divides by executedCount while list_executions's progress.passRate divides by total case count, source is a STRING whose .type is undefined and filter silently to nothing, and totalExecutions counts memberships including never-run entries. It also discloses that limit bounds the summary aggregates, not just the list, and that no inverse join exists from runId/executionCaseId back to the owning execution — all non-obvious behavior that an agent would otherwise be unaware of.

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 content is dense and earns its place, but the description is a single wall of text of roughly 400 words with no paragraph breaks, no bulleted structure, and several compressed explanations repeated (the source-is-a-string caveat is described twice, the passRate denominator difference appears both in the middle and near the end). The opening sentence is front-loaded and strong, but the mid-portion is very 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?

There is no output schema, so the description carries the full burden of explaining the return shape — and it does so thoroughly for both the row fields (id, status, runId, runName, executedBy, executedAt, notes, source with its standalone/release variants) and the summary fields — totalExecutions, executedCount, passed, failed, blocked, inTesting, notExecuted and passRate. It also documents edge cases (never-run memberships, inTesting shortfall, 365-day ceiling, both join paths and the lack of a reverse lookup) and identifies which sibling covers what, so nothing that an agent needs to invoke and interpret the tool correctly is missing.

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% for all three parameters, so the baseline is 3. The description contributes additional semantics beyond schema: days at its default of 30 can produce a near-empty result that falsely reads as 'never tested,' 365 is a hard ceiling with no way to query all history at once, and limit bounds the summary aggregates rather than just page size — none of which the schema states.

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 first sentence names a specific verb ('get'), a precise resource ('how one manual test case has fared over time'), and an explicit scope ('across every Manual Test Execution and release it appeared in, newest first'). It further differentiates itself from siblings by stating that only MANUAL results are covered, so an agent can distinguish it from get_test_history and get_execution_cases without opening their schemas.

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 explicitly routes to alternatives: 'use get_test_history for an automated test across launches, and get_execution_cases for the rows inside one execution.' It also warns against the tempting workaround of passing a releaseId to list_executions, since that tool has no releaseId filter and silently ignores unrecognized arguments, and instructs the caller to pass days explicitly because the 30-day default makes older cases read as never tested.

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