checklist

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

With no annotations, the description carries the full burden and delivers richly: it discloses that calling again REPLACES the whole list, that copy comparisons fold whitespace but treat wording/case/punctuation as exact, that note items are never machine-checked, that every export verifies the checklist, and the exact return shape. No behavioral surprise is left undisclosed.

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 long but every sentence earns its place. The lead sentence front-loads the core purpose; the item-kind bullets are necessary because the schema cannot convey these semantics; and the export-interaction and replacement warnings are essential operational facts. No filler or repetition.

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?

Given no output schema and no annotations, the description is fully self-sufficient: it covers return values, item-kind semantics, replacement behavior, lifecycle timing, and failure-handling. An agent can invoke this tool correctly on the first attempt with zero information beyond the description.

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?

Although schema coverage is 100%, the description dramatically expands meaning beyond the bare field names: it defines each kind's semantics (output = absolute path that must exist; copy = verbatim with whitespace folding; note = never machine-checked), explains the read mode when only revision is passed, and documents the return object. This far exceeds the baseline-3 bar.

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 states a specific verb+resource: 'Register the brief's ACCEPTANCE CHECKLIST for a design — the machine-checkable claims that must hold before the work counts as done.' It is immediately distinguishable from siblings like export (which verifies the checklist), scorecard (which presumably grades), and edit/preview (which mutate/view the design).

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 gives explicit timing ('Do this right after intake, before the first edit'), specifies what to extract from the brief (output files, verbatim copy, self-check notes), and explains how unmet items interact with export ('treat an unmet item exactly like a failing test: finish the work, or re-register the checklist without the item'). This is actionable when-to-use guidance that also routes the agent's behavior downstream.

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