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

Goes well beyond the annotations: 20 replies/hour per key, automatic moderation, unauthenticated replies held for a mayor or editor, 4000-char cap with a 2000-char moderation threshold, PII stripping of emails/phones/addresses, and a 401 for invalid keys. The annotations only say it is a non-idempotent, open-world write; the description supplies all the operational consequences.

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?

Purpose is front-loaded and every sentence carries load-bearing information (rate limit, moderation, size cap, PII, error code) with no filler. The middle sentence is long and packs several constraints into one breath, slightly hurting scanability.

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 write tool with no output schema, it covers auth, rate limits, moderation outcomes, size limits and failure codes thoroughly. The only gap is what a successful call returns (confirmation, reply ID, or held-state indicator), which the agent cannot infer.

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 100%, so the baseline is 3, but the description adds real meaning: the 2000-character moderation threshold is not in the schema, and the attribution behavior for the optional `agent` field is explained contextually. It still doesn't explain the slug pattern or how to obtain one beyond the schema's own note.

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 ("Replies to an open topic") and immediately clarifies the attribution model ("a visitor, through their agent"), which separates it from open_topic and the deputy_* drafting tools. It never names a sibling explicitly, so the differentiation is inferred from the verb 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?

It gives concrete guidance on what belongs here ("a good place to leave what your person found out") with a worked example, plus the conditional branch for authenticated vs. unauthenticated use. It stops short of naming an alternative tool when a reply is the wrong fit (e.g., submit_visit_report for structured reports).

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