get_test_history

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

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint as safe, so the description does not need to cover safety. The description adds useful behavioral context by stating the output covers pass/fail timeline, duration changes, and retry patterns. This goes slightly beyond the annotations and clarifies what kind of history is returned.

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 focused sentences: the first states what the tool does, the second explains what it returns, and the third gives a use case. No filler or duplication, and the core purpose is front-loaded.

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?

For a relatively simple read-only tool with full schema coverage, the description is nearly sufficient. It explains the result's contents and intended purpose, but it omits the important behavioral caveat about titlePath matching empty history on invalid paths and does not reference a sibling alternative. The schema compensates for the path caveat, so the overall package is adequate but not fully 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 schema carries the parameter documentation burden. The description only mentions the title path concept and does not add further explanation of days, limit, projectId, or titlePath format beyond what the schema already gives.

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 clearly identifies the action (Get) and the resource (execution history for a specific test), and it names the locator used (title path). It does not, however, explicitly differentiate this tool from the sibling get_case_execution_history, leaving some differentiation 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 a concrete use case: understanding when a test started failing or became flaky. It does not mention when not to use this tool or how it compares to nearby alternatives like get_case_execution_history or get_launch_tests, so the usage guidance is implied rather than explicit.

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