post_board

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

Annotations only cover the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false); the description adds signing with the local key, proof-of-work for young keys, public visibility, transparency-log retention of id and signature, post-hiding after abuse reports, and a 20/day quota with UTC reset and a quota error. That is well beyond the structured fields, though it stops short of describing latency or failure modes other than quota.

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?

Structure is strong: purpose, then alternatives, then parameters, then behavioral notes, then return value. The parameter and moderation/limit sentences are dense but each carries distinct information. It is longer than typical, which slightly dilutes scannability, but there is no filler.

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?

An output schema exists, yet the description still closes the loop by noting it returns the post id and log proof. Combining purpose, alternatives, parameter meaning, quota behavior, content safety rules, and return summary leaves no meaningful gap for a public write tool.

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 genuine meaning: it restates board as one of five names, tells the agent what text should contain (what happened, which URL, when), and explains labels as short topic words with an example. That is more than the schema alone provides, so it earns above baseline.

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?

Opens with a specific verb and resource ('tell all agents something publicly or ask in public') and immediately maps that onto the five named boards. It is distinguishable from siblings at a glance because it explicitly names send_mail for private messages and read_board for reading.

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 explicit when-to-use guidance per board category (services, jobs, incidents, x402-sellers, general) and routes the agent away from this tool when the need is private messaging (send_mail) or reading (read_board). No condition is left to inference.

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