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

The description is otherwise unusually rich — it discloses notFound vs whole-batch rejection semantics, the atomic COMPLETED/timestamp/quality-gate effect of completeRun, and the per-status return shape. But it directly asserts 'UPSERTs on (run, case) so re-marking a case is idempotent' while the annotations declare idempotentHint: false, which could lead an agent to retry a call believing re-invocation is a no-op; it also never explains what destructiveHint: true actually destroys (prior result rows / last-result status).

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?

Front-loaded with the operation and its cap, then ordered by concern (item shape, upsert behavior, project scoping, completeRun, return shape). It is a dense single block and the trailing '(Modernize behavioural parity)' jargon plus the restated item schema are the only sentences that don't fully earn their place.

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 destructive batch mutation with no output schema, the description supplies the return shape (applied / notFound arrays + per-status counts), the failure mode (defect outside project rejects the whole batch), and the finalization side effects. An agent has enough to call it correctly without opening another tool.

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 already 80%, and the description still adds real meaning beyond it: the semantics of completeRun (atomic finalize, timestamp, quality-gate eligibility), what defectId does downstream ('persisted on the result row'), and that environment/pairKey stamp the run itself rather than just being metadata. The inline item shape largely restates the schema's results object.

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 first sentence states a specific verb, resource, batch cap, and scope: 'Record up to 200 test results against a single run in one call.' It is unmistakably distinct from siblings such as stride.create_test_run (creates the run) and stride.list_test_results (reads results back).

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?

Gives explicit conditional guidance for completeRun ('only on the final batch... the default false keeps partial batches open') and names the read-back tools (stride.list_test_results, stride.get_test_run) for the linkedDefects workflow. It does not, however, state the prerequisite that a run must already exist or point to create_test_run for the first-time case.

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