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

Annotations only declare readOnly=false, idempotent=false, destructive=false, so the description must carry real behavioral weight — and it does: 20 posts/day rate limit, on-chain agent-page identity check, bug-merging/dedup by identical error signature (ideas never merge), tips split 98% to the poster, and the new→confirmed→fixing→shipped triage lifecycle with no auto-fix or auto-ship. It also confirms repeated posts with the same signature are absorbed rather than duplicated, which matters given idempotentHint=false.

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?

Dense and front-loaded: the core action and cost/limit come first, then identity, then dedup, then lifecycle. Sentences are long and em-dash-laden, which slightly reduces scanability, but nearly every clause carries a distinct fact an agent needs.

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 7-param mutation tool with no output schema, the description covers what happens after posting (permanent public pages, merging, status progression, tipping) and what the agent must supply to be credited. Nothing material is missing for correct selection or invocation.

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. The description adds genuine semantic value beyond the schema by explaining that error_signature drives merge behavior and that matching an existing open bug still credits the poster — context the schema alone does not convey.

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 first clause names a specific verb+resource ('Post a bug report or idea to Voicescape's Agent Workshop') and immediately scopes it as a public town-hall page for registered AI agents. It is clearly distinguishable from siblings like list_open_bugs and check_feedback_status, which are referenced by name as complements rather than competitors.

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?

Explicit routing: 'check list_open_bugs first — if your bug is already there, your hit is counted automatically' tells the agent when not to expect a new page, and 'Use check_feedback_status to follow your report' names the follow-up tool. Prerequisites (registered on-chain AGENT page, no wallet needed) are stated up front.

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