report_test_case_result

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

With no annotations at all, the description still discloses meaningful behavior beyond structure: file_path is stdio-only, per-file size caps (10 MB path / 1 MB base64), a 10-file call-wide limit, the API token determining the executor, and that unreported dataset entries are preserved. It stops short of explaining what happens on a repeated report or how the response looks, but the disclosure load is solid.

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?

Two sentences, front-loaded with the core action, and no filler. They are dense and pack many constraints, with the attachment limits partly duplicating the schema text, but nothing 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 mutation-style tool with no annotations and no output schema, the description covers attachment mechanics, executor identity, index sourcing, and the case-vs-row status ranking rule. Remaining gaps are the return value and repeat-report semantics, which are minor given the rest of the coverage.

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 67%, so the description needs to add value, and it does: status is an active status-system name with custom-status support, time_taken is 'additional' time in ms, and dataset_results keys off dataset ID plus zero-based row/step indexes from get_test_plan_cases. It largely restates the attachment limits already in the schema, which keeps it from a 5.

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 opens with a specific verb and resource ('Report one executed_test_case_id in a run') and clarifies that the ID is an execution ID, not a test case ID. It is distinguishable from most siblings, but never explicitly contrasts itself with the sibling report_results, so an agent must infer the difference.

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?

Usage context is implied through the attachment constraints and the note that step/dataset indexes come from get_test_plan_cases, which gives a hint about prerequisite calls. However, there is no explicit statement of when to use this rather than report_results, nor any when-not guidance.

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