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

Annotations declare idempotentHint=true and destructiveHint=false but do not explain the execution model. The description adds real value: isolated disposable instances, a retained receipt, no change to publication status, and the caveat that it does not claim universal service fidelity. The operationKey recovery instruction is consistent with the idempotency annotation rather than contradicting it.

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?

Four short sentences, front-loaded with the core action and followed by scoping caveats and the recovery instruction. Every sentence carries content, though 'does not claim universal service fidelity' is slightly obscure phrasing that costs a bit of clarity.

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 nested-schema, non-read-only tool with no output schema, the description covers the important behavioral facts (isolation, receipt, publication untouched) but says nothing about what the receipt contains, what happens to instances on failure, or how expectations mismatches are reported. The cardinality limits sit in the schema, so their absence is acceptable, but the result contract is thin.

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 only 20% – only operationKey is documented in the schema, and the description repeats that same recovery guidance while adding nothing for projectId, environmentId, buildId, or the deeply nested suite object. The suite's cases/steps/expect/records structure carries the tool's entire semantics and is left for the agent to infer from the schema alone.

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 concrete verb+resource: run operation/expectation fixtures against an exact private service build in isolated disposable instances. The phrase 'does not change publication status' implicitly distinguishes it from firedrill_service_publish, and 'executes authored service code, not the customer agent' distinguishes it from agent-level assessment tools. It stops short of naming siblings explicitly.

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?

'This executes authored service code, not the customer agent' gives a useful boundary against the agent-facing tools, but there is no explicit guidance on when to use this versus firedrill_service_invoke, firedrill_service_acquire, or firedrill_service_control. Usage is implied by the phrase 'supplied operation/expectation fixtures' rather than stated as a decision rule.

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