report_case_result

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

Well beyond the annotations, the description discloses the auto-derivation precedence order (failed then blocked then in_testing then passed), the group roll-up rules (all not_executed → not_started; some executed → in_progress; all executed → blocked if a blocked case exists else completed), the quirk that test_run_status has no failed state, and the override lifespan semantics. No annotation contradiction — idempotentHint=true is reinforced by the stated idempotent behavior.

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 description is long (~230 words), but every sentence carries load-bearing information — targeting rules, derivation order, roll-up logic, override interaction, return payload. It is front-loaded with the primary purpose and organized topically; it would only benefit from minor separation, but no sentence is wasted.

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 9-parameter, side-effecting tool with no output schema, the description covers every decision an agent needs: how to address the case, how to set each field, how auto-roll works for the containing group, when an override sticks, and exactly what the call returns (case status, group status, steps written, progress). Nothing required for correct invocation 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?

Although the schema already covers all 9 parameters (100% coverage), the description adds genuinely non-obvious meaning: the precedence ordering of executionCaseId vs executionId+caseId, the groupId disambiguation condition, the "auto" derivation algorithm, and the omit-to-leave-unchanged behavior. These cross-parameter semantics live only in the description.

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 states a specific verb and resource — "Record the result of running one case inside a Manual Test Execution: set per-step pass/fail and/or the case status" — and immediately distinguishes itself from siblings like update_execution and set_execution_source_status by scoping to a single case's results with atomic/idempotent semantics.

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?

It provides explicit targeting guidance: use executionCaseId (from get_execution_cases) as preferred, fall back to executionId + caseId, and pass groupId if the case is in several groups. It also tells the agent when to supply status explicitly, when to use "auto", and when to omit it, and explicitly references the set_execution_source_status sibling to explain how its override interacts with the automatic roll-up.

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