record_attestation

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

Since no annotations are provided, the description has full responsibility for behavioral transparency. It does not mention whether this operation is destructive (e.g., overwrites existing attestation), what happens if an attestation already exists for the class, or any prerequisites like authorization or prior registration of the system. The phrase 'the register shows the latest attestation per class' suggests it updates state but does not clarify if it overwrites or appends. More transparency is needed for a mutation tool.

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 a single paragraph, but it is relatively dense with information: the exact legal reference, the list of classes, the two statement values, the basis requirement, and the register behavior. It is reasonably concise, but the list of classes (a, b, ba, bb, c, d, e, f, g, h) adds length, and the sentence about the register's display could be a separate sentence for clarity. Overall, it is efficient without being overly terse.

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?

This is a moderately complex tool with 6 parameters and no output schema. The description covers the key domain concepts (prohibited practices, attestation types) but omits critical operational details: how 'actor' and 'system' are used, whether 'ts' is a timestamp, and what the return value or side effects are. Given the legal and compliance context, more completeness would be needed to safely call this tool, especially around idempotency and authorization.

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%, so the description must fully compensate for the parameters. It only explains 'practice' (via the class list) and 'basis' (needed for not_applicable), but it does not explain 'actor', 'system', 'ts', or 'statement'. The description's mention of 'statement' as 'not_used' or 'not_applicable' indirectly defines it, but 'basis' is only assumed. The other parameters are completely unexplained, leaving ambiguity for an agent.

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 action ('Attest for one Art. 5(1) prohibited-practice class') and specifies the resource (the class) with a list of valid values (a through h). It also conveys the two possible statements ('not_used' or 'not_applicable') and the need for a basis when not_applicable. It is distinct from siblings like record_oversight, which likely handles different oversight actions, so it provides enough clarity for basic selection.

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 includes a specific legal reference (Art. 5(1)) and the required statement values, which imply when to use it: when recording an attestation about prohibited practices. It also briefly notes that the register shows the latest attestation per class and classes with none, which hints at context. However, it does not explicitly state when to use this tool versus other attestation-related tools like attest_retention or attest_documentation_retention, or when not to use it, but the domain specificity gives good guidance.

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