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

Annotations declare a non-read-only, non-destructive, non-idempotent write, and the description adds real context beyond that: "[sign-in required]" and the conditional branch where a close match causes a link-back instead of a queue. It still does not say what happens to the submission (queued for review? visible to others? duplicate handling?), so the mutation's consequences remain opaque.

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?

One sprawling run-on sentence stacks a dozen content mandates before ever naming the action, so the core purpose is not front-loaded. Much of the text reads as article style guidance rather than tool guidance, and the reader must parse to the middle to learn what the call actually does.

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, so return values need no explanation, but this is a four-parameter write with 0% schema coverage and a conditional branching workflow. The description spends its length on editorial content requirements and leaves the mechanical contract — field purposes, formats, and post-submission behavior — substantially unexplained.

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 description coverage is 0% across four parameters, so the description must carry the burden. It implies title, explainer, and sources ("trace every quote and fact to a named source"), but never explains the sources array shape, the 20-item cap, the length limits, or what summary is for — the single most under-documented field.

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 actual purpose — "Suggest an article title or topic" — appears mid-paragraph, buried under a long list of editorial requirements for the resulting article. The verb+resource are specific once found, and it distinguishes itself from check_existing_coverage and get_submission_guidelines, but an agent skimming the opening clause ("Read get_submission_guidelines first...") could easily mistake this for a content-authoring tool rather than a topic-submission 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?

Genuine sequencing guidance is present: read get_submission_guidelines first, check_existing_coverage is advisory and "does not block," and if a published article is a close match the flow switches to linking and asking what it misses rather than queuing. However, there is no guidance on when to prefer this over the close siblings propose_new_article or suggest_article_change, which is the main ambiguity an agent faces.

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