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

Adds genuinely non-obvious behavior beyond the annotations: every change is revisioned and restorable, the article stays unpublished unless published: true, and there is a per-call cost of $0.01 with no charge on failure. The cost and default-publish semantics are exactly the kind of context annotations cannot convey.

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?

Four short sentences, front-loaded with the create/update rule, then body format, then side effects, then cost. Nothing is padding and each sentence carries a distinct fact.

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?

Good on side effects and cost for a mutation tool with no output schema, but with 14 mostly undescribed parameters and a nested options object, an agent still has no guidance on what most fields do or which are meaningful on update vs create.

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 14% across 14 params, so the description must compensate and largely doesn't. It clarifies markdown vs content HTML and the publish flag, but slug, cover, order, options (toc/feedback), featured, collection, seo_title/description, and description are given no meaning in the description despite having no schema descriptions.

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+resource and even splits the two modes: create (no id) vs update (id). It does not distinguish itself from adjacent siblings such as help_center_publish or help_center_apply_template, which overlap with its published/create behavior.

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?

The id/no-id rule effectively tells the agent which mode to use, and it points at the design guide for markdown. But it never says when to use help_center_publish or apply_template instead, even though the 'unpublished until published: true' sentence overlaps directly with those siblings.

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