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

Annotations already declare the mutation, idempotency, and non-destructive profile. The description adds the useful semantic that attempts are unverified observations and encodes a conditional validation rule for FAILED, but it does not mention idempotency-key retry behavior or what the successful response contains.

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?

Three sentences, front-loaded with purpose and ending with the conditional constraint. Little is wasted, though the FAILED sentence is dense with an enumerated list that could be structured more scannably.

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 tool with 18 parameters, nested objects, six required fields, and no output schema, the description covers the key conditional (FAILED) but omits how lease_version fencing interacts with recording, how evidence is used, and what a successful call returns. Adequate but with clear gaps.

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 only 33% across 18 parameters, so the description must compensate. It does add meaning for the FAILED path by tying failure_category, failure_reason, and the set of acceptable execution-condition fields (software_version, code_revision, dataset_id, dataset_hash, environment_fingerprint, parameters) together, but many parameters remain unexplained.

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 states a specific verb ('Record') and resource ('attempt') and enumerates what is captured: method, observed outcome, reproduction details, and artifact references. It clearly distinguishes its content from a generic record, but it does not name the closest siblings (record_failure, complete_task) to help routing.

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?

It gives a meaningful semantic frame ('Attempts are observations, not verified claims') and a conditional rule that FAILED requires category, reason, and an execution condition. However, there is no explicit when-to-use versus record_failure or complete_task, so selection still relies on inference.

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