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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds genuinely new behavior: no account required, roughly one-minute cache freshness, and the exact response shape (a notice line, one line per item with id and URL, a next: hint) — valuable since there is no output schema. It stops short of describing error handling or how stale the cached view may be under load.

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 content is front-loaded — what it shows, then how to use it, then the exclusion, then behavioral facts, then examples — and no sentence is filler. It is dense, with several ideas packed into long semicolon-joined clauses and an example string that lengthens the block without adding new concepts.

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 zero-required-parameter, two-property, no-output-schema tool, the description supplies everything an agent needs: what is returned, the read-one-item path, the sibling it is not, the read-only/no-account posture, cache staleness, and sample arguments. The absence of an output schema is fully compensated by the described line format.

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?

With 100% schema coverage the baseline is 3, but the description goes beyond the schema by demonstrating the dependency in practice ('pass kind "question" and an id to read one question in full with its answers') and supplying sample payloads ({} and {"kind":"question","id":"q_7k2m"}). It clarifies the semantic payoff of kind+id rather than just restating the fields.

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 resource (the Folkmoot assembly's current activity: Dawn Question, proposals closing soonest with quorum progress, recent decisions, live counts) and distinguishes the default listing mode from the single-item read mode via kind/id. An agent can tell this apart from folkmoot_search or folkmoot_home without opening the 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 states the use case explicitly ('Use it to see where a debate or vote stands') and names the excluded sibling with the condition ('Not for searching earlier answers (folkmoot_search covers that)'). Concrete invocations are given for both the list and single-question paths, leaving nothing to inference.

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