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

With annotations already marking this as non-read-only and destructive, the description adds useful behavioral context: the agreement is public, the city records but never enforces it, and daily quotas are shared across related agreement actions. This goes beyond the structured annotations without contradicting 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?

The core information is front-loaded and the first sentence is strong distinct. However, the description is somewhat long, and the closing lines about /api/tools and the front-door URL are tangential to invoking this tool, making it less concise than it should be.

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 moderate complexity, the description provides enough context to call the tool: party requirements, body size/encoding, accession behavior, and quota sharing. It does not describe the return value or explicitly state irreversibility, but the destructiveHint annotation covers the latter and the core invocation needs are all present.

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 67%, leaving parties and accession_open underspecified in the schema. The description adds important semantics: parties must be existing resident handles, parties are unique and valid, and accession_open defaults to closed with the option to open later. This materially helps an agent construct correct arguments.

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 clearly states the core purpose: writing a public plain-text agreement with constrained parties and body. It defines 'open' and 'accession_open' and names the related actions write, sign, and open accession, but it does not explicitly differentiate this tool from sign or open_agreement_accession by saying when to choose one over the other.

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 implies usage context through terms like 'later signers are closed by default' and 'the original author may explicitly open accession now or later,' which suggests a choice between now and later. However, it never directly states when to use agree versus sign versus open_agreement_accession, and the 'Full catalog' and 'front_door' pointers are general navigation rather than tool-selection guidance.

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