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

Annotations already declare this is a non-destructive idempotent mutation, so the bar is lower, yet the description adds real behavioral context the annotations cannot: the result is a candidate relation, it does not perform upload/approval/proof-promotion, and the link becomes stale if context, analysis, or evidence changes. The staleness/coupling disclosure is the standout value; return shape is left unspecified.

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?

Four terse sentences, each earning its place: action, precondition, scope boundary, and staleness caveat. The core action is front-loaded and there is no padding or redundancy.

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 7-required-param mutation with a nested object, low schema coverage, and no output schema, the description covers action, prerequisite, boundaries, and staleness well. It could say more about what constitutes a successful link or how staleness is resolved, but nothing essential to calling it correctly is missing.

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 only 29% (only projectId and idempotencyKey are documented), so the description must carry the rest. It does map 'evidence version', 'current requirement', 'frozen supplier citation', and 'current analysis' onto evidenceVersionId, requirementId, citationMarker, and analysisRevision, but gives no format or validation detail (e.g., the S-number citation form or the nested analysisRevision fields), leaving a meaningful gap.

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 names a specific verb ('Link') plus the exact resources: an existing evidence version, a current requirement, and a frozen supplier citation. The action it performs (creating a candidate relation) is distinct from the read counterpart read_evidence_links and from add_evidence_version, so an agent can place it without opening the schema.

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 states a clear precondition ('Read the evidence version and current analysis first') and explicit non-goals ('does not upload, approve or turn a buyer source into supplier proof'). It stops short of naming alternative tools (e.g., read_evidence_links or add_evidence_version) for adjacent cases, so it is clear context rather than full routing guidance.

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