Copy Test Run

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

With no annotations, the description carries the full burden and does well: it discloses that results are NOT carried over (every case starts UNTESTED, verified live), that cross-project copies are impossible, and how unset optional args behave. It stops short of stating permission/auth requirements, whether the copy inherits archived or lock state from the source, and whether the operation is idempotent or retry-safe — all material for a mutation tool with zero annotation coverage.

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?

Purpose is front-loaded in the first sentence, then constraints are grouped into short topical paragraphs that each carry distinct information. Slightly long, and 'Every optional argument below' is a wasted clause that points at nothing, keeping it from a 5.

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 no-annotation, no-output-schema mutation tool, the description covers the behaviors an agent most needs — project confinement, selection immutability, result reset, and override semantics. The significant remaining gap is the return value: it never says whether the response includes the new run's ID or name, which an agent needs to chain a follow-up call, and permissions are unaddressed.

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 100%, so baseline would be 3, and the description earns above that by explaining merge semantics: each optional argument overrides the corresponding attribute on the copy, and leaving one unset preserves the source value rather than clearing it — a critical clarification given the schema shows empty-string defaults that would otherwise read as 'clear this field'. It does not enumerate the five parameters, and 'Every optional argument below' is a dangling reference that adds little per-parameter detail beyond the schema.

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?

States a specific verb and resource ('Creates a copy of an existing test run along with its test cases') and immediately scopes it against the sibling that competes for the same intent, naming create_test_run explicitly. An agent can distinguish it from create_test_run and list_test_runs without opening any schema.

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?

Explicitly says when to use it and when not to: the copy stays in the source project because there is no project parameter, the case selection cannot be narrowed here, and create_test_run is the alternative when a different selection is needed. These are concrete exclusions, not implied ones.

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