Add Evidence

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

With no annotations provided, the description carries the full burden and it deliberately discloses 'Mutating.' to signal side effects. It further clarifies a non-obvious behavioral nuance: evidence does not affect a control's implementation status. It stops short of covering dupicate-attachment behavior, permissions, or reversibility beyond pointing to remove_evidence, but the mutation disclosure plus semantic caveat is solid for a simple attach operation.

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 terse sentences with zero waste: the action is front-loaded, 'Mutating.' is a compact side-effect flag, and the semantic caveat plus sibling routing each earn their place. The paragraph break after the first sentence aids scannability.

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 straightforward mutation tool with an output schema present, the description plus schema cover the essentials: what it does, that it mutates, how it relates to status, and how to undo it. The only notable gap is the required server_version parameter having no description in either schema or description, and no statement about duplicate-attachment behavior, but these are minor against an otherwise complete definition.

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 83% (all parameters except server_version are documented), so the schema carries most of the parameter weight. The description adds marginal value by reinforcing the 'metadata-only' nature of the item and the type list already in the schema. It does not elaborate on server_version or label requirements, but the baseline 3 is appropriate given high schema coverage.

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 uses a specific verb ('attach'), names the resource ('auxiliary evidence item... to a control'), and enumerates the item types (doc, link, artifact reference). It also differentiates from siblings by clarifying that evidence is not an assertion and naming remove_evidence as the inverse, so an agent can distinguish it from add_assumption or submit_assertions.

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 gives clear usage context: evidence is contextual metadata and does not count toward implementation status, with 'only assertions prove controls' serving as an implicit when-not signal. It explicitly points to remove_evidence for detaching. It does not name the exact alternative tool for proving controls (e.g., submit_assertions), but the guidance is strong enough to route correctly.

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