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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real context: it consumes one article from the month's allowance, lands in the review queue as a draft, takes a minute or two, and requires confirmation. That is meaningful disclosure beyond the structured fields, though it omits failure modes or quota-exhaustion behavior.

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?

Front-loads the action ("Write an article now on a topic") and wastes little space. The inline parameter parenthetical and the terse "Needs confirm" clause are slightly clunky and partially duplicate the schema's confirm description, but overall it is compact.

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 mutation tool with no output schema, the description covers the key operational facts: quota consumption, resulting draft state, timing, and confirmation flow. The org parameter is left to the schema (which points to seovyn_whoami), so nothing critical 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 description coverage is only 40%. The description adds meaning for competitorUrls ("1-4 competitor pages it should beat") and hints at optionality of pageType, but org, pageType's enum values, and topic are unexplained in the description. It partially but not fully compensates for the documentation gap.

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?

Specific verb (Write) and resource (article) plus scope (against 1-4 competitor pages it should beat). It is easily distinguished from seovyn_edit_article and seovyn_rewrite_section because it creates a new draft rather than modifying existing content, though it doesn't name those siblings explicitly.

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?

Usage is implied by "Write an article now" and by naming the inputs, and it notes the confirm protocol, but there is no explicit when-to-use vs when-not or routing to alternatives like seovyn_plan or seovyn_edit_article. Adequate but leaves the agent to infer selection.

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