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

The description reveals append-only content-addressed storage, immutability under content digest, that observations remain claims rather than derived states, and the public-write privacy restriction. These traits go well beyond the annotations (idempotentHint, destructiveHint, readOnlyHint) and align with them.

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 dense sentences, each earning its place: what to record, the structural/integrity constraints, and the storage/privacy semantics. The most decision-relevant information is front-loaded, and there is no filler or repetition of schema content.

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 write tool with a nested record object, the description covers the essential record structure, validation requirements, append-only behavior, and public-data restriction. It doesn't detail how to resolve `upstream` identifiers or the exact output, but the output schema and sibling tools like find_capability likely fill those gaps. This is a minor omission rather than a blocking one.

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?

The input schema only describes the optional ID parameters; the main `record` object is an open object with no internal schema. The description compensates by defining the required shape: at least one observed field, `upstream` identifying the capability, and `derivation.witness` holding input/output. It doesn't discuss the optional handles, but the schema already documents those.

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 opens with a specific verb and resource: 'Record what you observed when you ran a capability, as an attractor-cooperation record.' It further distinguishes the operation by specifying the required structure (observed field, upstream, derivation.witness), making it unambiguous against sibling read/validation tools like check_observation.

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 clearly states when to use the tool: after running a capability, and with the requirement that the record pass profile reference checks. It also gives an explicit boundary: public test inputs only, no personal data. It doesn't name alternatives or give a when-not-to-use list, so it falls just short of a 5.

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