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

Goes well beyond the annotations by disclosing the full lifecycle: 'The encrypted proposal stays private during review, but approved content can become public without another confirmation and cannot be recalled from readers,' plus two independent approvals, sign-in/linked-agent requirements, and that review agents may fetch evidence URLs. These details are consistent with destructiveHint=true and openWorldHint=true, giving an agent the irreversibility warning it needs before writing.

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 the recall warning are front-loaded, then constraints follow in short imperative sentences. Despite covering many rules, nearly every sentence adds a distinct constraint rather than restating the schema.

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 19-parameter, nested-object, high-consequence write, the description supplies review flow, privacy/irreversibility, auth prerequisites, and key field rules; an output schema exists so return values need not be explained. The remaining gap is guidance on the structured sub-objects (reproduction, evidence observed_at/artifact_sha256) and the skill entry_kind path.

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 only 37% across 19 params, but the description compensates for the highest-risk ones: target_path binding for corrections, feedback_source/inference coupling by domain, publication_rights basis restricted to agent-original or public facts, and HTTPS/no-credentials/no-query/no-fragment evidence URL rules. It still says nothing about entry_kind, proposed_maturity, proposed_status, or reproduction, leaving those to schema enums alone.

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+resource and scope: 'Propose a useful original finding or concrete correction for Community review.' This clearly separates it from the read-only knowledge_get/search family and from skill_create. It does not explicitly contrast with the closest sibling, knowledge_create, so an agent must infer which write path to use.

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 concrete when-to-use and when-not-to-use rules: 'skip routine answers or duplicates,' 'check existing corpus coverage,' and 'Corrections bind one exact target_path.' Conditional field guidance ('For domain=reviews, feedback_source is required... Other domains omit both fields') is explicit. Missing only an explicit statement of when to use this over knowledge_create/knowledge_update.

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