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

Description warns that plain evidence never counts toward AC coverage and does not close goals, a non-obvious side-effect that annotations cannot convey. It also clarifies the note is a complement to an attached file, giving the agent a mental model of the tool's limited scope. Since annotations only provide readOnlyHint/idempotentHint, the description carries the burden and meets it.

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 key information is front-loaded: subordinate path, does not close AC, text-only. Repetition of the goal-attach-evidence alternative across several sentences is a bit verbose, but each sentence adds a distinct exclusion (bytes, filesystem paths, AC coverage) that reduces mis-invocation risk.

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 simple 3-parameter tool with no output schema, the description covers what the tool does, what it intentionally does not do, and which sibling covers every excluded case. The only omission is return behavior, but that is not essential for selecting and invoking this tool correctly.

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?

Input schema already fully documents all three parameters (100% coverage), so baseline is 3. Description restates the text payload constraint and adds exclusions (not for bytes/filesystem paths) that flesh out allowable values, but it introduces no new parameter-specific detail for criterionId or createdBy.

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?

States a specific verb and resource: adds text-only evidence/note to an acceptance criterion. Explicitly distinguishes itself from sibling goal-attach-evidence by framing itself as supplementary/subordinate and clarifying it does not close an AC. Concrete examples (URLs to CI run, commit, issue, manual scenario) make the purpose unmistakable.

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?

Explicitly directs the agent to goal-attach-evidence for any criterion coverage or any byte/file/path payload, and states this tool is only for text-only supplementary context. Gives clear when-not conditions (not for bytes, not for filesystem paths) and the alternative to use. This is the strongest possible usage guidance.

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