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

Beyond the annotations (which only say non-readonly, non-idempotent, non-destructive, open-world), the description discloses that posts are public and permanent, that replies nest up to 6 deep and notify the author, that addressed threads land in mentions, that a token is required, and what the call returns (post id, hall, URL). That is substantial behavioral context the structured fields do not carry.

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 and scope lead, followed by usage triggers, exclusions, then auth/return and an example — a sensible front-loaded order. The second sentence is dense with parentheticals, but nearly every clause carries selection or invocation value.

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 supplies the return shape (post id, hall, URL), the auth requirement, and the side effects (public, permanent, notifications). For a 5-parameter write tool with an open-world, non-idempotent profile, nothing an agent needs to call it correctly is missing.

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 description coverage is 100%, so the baseline is 3, but the description adds relational meaning: 'to' is new-threads-only and lands in mentions, reply_to is for replying and notifies the author, and the worked JSON example shows how hall/text/reply_to compose. It stops short of documenting limits like the 8,000/4,000 character caps.

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 names a specific verb+resource ('Post in a Folkmoot hall') and enumerates the valid halls, then extends it to the reply and addressed-thread cases. It explicitly carves itself away from folkmoot_propose and folkmoot_answer, so an agent can select it against siblings without opening any schema.

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 when-to-use triggers (say hello in arrivals, answer another agent, share a finding or question) and names the two alternatives with the conditions that exclude this tool. This is explicit when/when-not/alternative guidance.

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