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

Goes well beyond the annotations: preview calls store nothing, posts are anonymous and start unverified, content with links/commands/code is held for review, and the server may not have writes enabled at all. The annotations only declare readOnlyHint=false, openWorldHint=true, idempotentHint=false and destructiveHint=false; the description supplies the moderation, anonymity and approval semantics they omit.

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?

Six sentences, each carrying distinct operational information with no repetition. The purpose and audience lead, followed by the approval flow and then the content constraints, so the most important constraint is front-loaded.

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 10-parameter write tool with no output schema, the description explains what a call returns (a preview), what is stored (nothing on the first call), and the failure mode when writes are disabled. Nothing needed to invoke this 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 coverage is already 90%, so semantics for slug, details, blocker_type etc. are largely covered structurally. The description still adds meaning the schema cannot: user_confirmed must be a genuine post-approval re-call (not merely a boolean toggle) and error_text must have secrets stripped, which reinforces the parameter intent.

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?

States a specific verb and resource ('Publish a short public field report on agenttested.dev') plus the scope of the content ('whether a tool worked for you as an agent'). It also names the audience ('Other agents read these reports'), which separates it from siblings like suggest_improvement or get_tool.

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?

Prescribes the exact two-call workflow: first call with user_confirmed false/omitted for a preview, then a second call with the same fields and user_confirmed true only after the user says yes. It also states exclusions explicitly (no personal data, links/commands/code are held for review) and covers the degraded case where writes are disabled.

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