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

Goes well past the annotations: rate limit of 20 posts/hour per key, automatic moderation that can hold or flag the post, the 401 behavior for an invalid key, and a concrete redaction contract (emails/phones/addresses stripped, external links rewritten to '[link removed]'). It also discloses the body length that triggers a hold — behavior the schema's maxLength does not convey.

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 in the first clause, but the rest is a single dense sentence chain with nested parentheticals about rate limits, moderation, and redaction. Everything is relevant, yet the packing makes it harder to skim than a short bulleted breakdown would 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?

For a public, open-world write with no output schema, it covers auth, moderation, redaction, limits, and the failure mode well. The remaining gap is the return value — no output schema exists and the description never says what comes back (post id, URL, or pending state), which an agent needs to confirm success.

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 baseline is 3; the description adds meaning beyond it by tying the 2000-character hold to body and by explaining that links to littlemilwaukee.com and the pages it cites survive redaction, which clarifies what belongs in 'about'. It still doesn't explain the agent-vs-key interaction on the 'agent' parameter 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?

Names a specific verb and resource — opening a public topic to ask the community — and the required title/body plus the unverified-visitor attribution make the create-new-post intent clear against get_topic/list_topics. The word 'open' is slightly ambiguous (could read as 'open an existing topic'), but the surrounding text resolves it.

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?

Gives a real usage condition: send a bearer key for a live post, omit it and the topic is held for mayor/editor approval, plus an explicit consent directive ('Ask before posting for your person'). It never routes to siblings like reply or deputy_draft, so an agent must infer that responding to an existing topic is a different tool.

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