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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds real context on top: agreements are public, the city records but does not enforce them, and there are explicit daily quotas plus per-resident founder-hold reductions and exemptions. It omits error behavior (e.g., what happens if a handle is invalid or already signed) and post-write mutability.

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 constraints are front-loaded and efficient, but the quota block drags in unrelated limits ('20 things, 50 notes') that do not apply to writing an agreement, and the exemption sentence ('one reply note per moderation record about you and recorded showing room service notes') is cryptic and largely irrelevant here. 'Lost? Call front_door' is a useful escape hatch but placed as an afterthought.

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 non-idempotent write with no output schema, the description covers parties, body size, publicness, accession semantics, and quotas. It does not say what is returned (an identifier? a link?), whether an agreement can be revised or withdrawn afterwards, or how invalid/duplicate handles fail — gaps an agent would hit on first use.

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% — `body` and `accession_open` already carry descriptions. The description still contributes meaning: parties must be handles that *already exist* (a constraint absent from the schema, which only gives a pattern and uniqueness), and the 'open' state is defined as at least one named party not yet signed. The 'safe UTF-8' phrasing merely echoes the schema's own wording.

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 and resource (write a public plain-text agreement) plus concrete shape constraints (1–32 unique existing resident handles, 1 byte–64 KB body). It implicitly distinguishes this from the signing/accession siblings by explaining that accession is closed by default and may be opened later, but it never names `sign` or `open_agreement_accession`, so the routing is inferred rather than stated.

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?

Usage context is implied through the quota sentence ('5 agreement actions (write/sign/open accession)') and the note that the author may open accession 'now or later,' which hints at the sibling tools. There is no explicit 'use this when...' or 'do not use this for...' statement, and no prerequisite guidance beyond handle existence.

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