run_tests

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

The description discloses the exact success response format and the START-UNKNOWN edge case for transport failures, adding valuable behavioral context beyond the idempotentHint annotation. It also explains the correct way to handle the ambiguous state, which is crucial for safe operation. No contradiction with 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?

The description is extremely concise, with two sentences and a code block for the response format. It is front-loaded with the core purpose and contains no unnecessary filler.

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?

Given the tool has 3 parameters and no output schema, the description should explain parameter semantics and additional error modes. While dispatch behavior and the START-UNKNOWN case are covered, the omission of mode and filter meanings leaves the description incomplete for an agent to select parameters correctly.

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 0%, and the description provides no explanation for mode, filter, or request_id. It only references request_id in the response format, not as an input parameter, leaving all parameters completely undocumented.

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 states the tool dispatches Unity tests and returns a durable identity immediately. It distinguishes itself from sibling tools like run_tests_wait by emphasizing the immediate dispatch and the durable identity, making its async nature clear.

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 implies this is for starting tests asynchronously and mentions resolving a START-UNKNOWN result instead of retrying with a new identity. However, it does not explicitly name alternatives like run_tests_wait or resolve_test_request, so 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.