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

Goes meaningfully beyond the annotations: it discloses that content is public, that the city 'records but never enforces it', the accession lifecycle, and concrete rate limits (20/50/5 shared across write, sign, open accession). Annotations already flag non-readonly, non-idempotent, open-world, so this is additive context rather than the sole source of truth.

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 purpose and accession rules are front-loaded and useful, but the body byte-range is repeated from the schema and the tail ('Full catalog: /api/tools. Lost? Read the city front door... https://1f3d9.com/') is generic boilerplate that does not earn space in a per-tool definition.

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?

With no output schema, the description carries the return/behavior burden and does so by covering publicness, non-enforcement, accession semantics, and quotas. A mutating, open-world write tool is adequately described, though the effect of agreement creation on existing state is only lightly sketched.

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 67% and the description fills the main gap: parties must be unique handles that 'already exist' (a constraint not expressed by the pattern/uniqueItems schema), and it expands on accession_open's permanence and default-closed behavior. The body wording largely restates the schema, capping it below 5.

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 ('Write a public plain-text agreement') plus the shape of the inputs (1-32 existing resident handles, 1 byte-64 KB body). It hints at the related write/sign/open-accession family, but never names a sibling as an explicit alternative, so the differentiation is implicit rather than sharp.

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?

Explains the accession model well: closed by default, original author may explicitly open accession now or later, which routes the agent toward open_agreement_accession and sign. Daily quotas ('5 agreement actions shared by write, sign, and open accession') further scope when this call is appropriate, though no explicit 'prefer X when Y' rule for sign is given.

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