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

Annotations already declare this is a non-read-only, non-destructive, open-world, non-idempotent write. Beyond that, the description adds substantial context: the agreement is public and permanently recorded, the city 'records but never enforces it,' lookups must reference existing non-withdrawn things, and links 'move nothing and change no terms.' It never states that repeat calls create separate agreements, which is the main non-idempotency fact an agent would want.

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?

Constraints and the open/accession_open distinction are front-loaded, and the quota and exemption sentences, while dense, are operationally relevant to whether a call will succeed. The closing 'Lost? Call front_door' is useful but tacked on, and the quota sentence packs three unrelated numbers into one breath.

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 mutating tool with no output schema and no return-value documentation, the description covers permanence, referential integrity, quotas, and exemptions — the things most likely to cause a failed or unexpected call. What is missing is failure behavior and what the call returns (e.g., an agreement id), which matters for an agent that may need to sign or open accession afterward.

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 coverage is 75%, and the description compensates for the undocumented parties array by requiring handles that 'already exist' and be 'unique valid resident handles' — a referential constraint the pattern alone cannot express. It also restates the closed-by-default behavior of accession_open and the non-mutating nature of thing_links, adding meaning beyond the field text.

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 opens with a specific verb and resource: 'Write a public plain-text agreement,' then immediately bounds it (1–32 unique existing resident handles, 1 byte–64 KB safe UTF-8). It distinguishes this from siblings like sign and open_agreement_accession by describing the authoring act and by noting that accession can be opened later via a separate action.

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 clear conditions for the accession_open parameter ('open means at least one named party has not signed; accession_open means later signers may join') and routes a confused agent to front_door. It does not explicitly name sign or open_agreement_accession as alternative tools, so the when-to-use-which-tool guidance is implied rather than spelled out.

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