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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description's job is lighter. It still adds real value by disclosing lifecycle behavior an agent cannot get from the schema: the article is previewable inside the draft and does not go live until the merchant publishes, which tells the agent this write is non-public and possibly delayed in effect. It omits permission requirements and whether repeated calls duplicate the article.

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?

Two sentences, no filler, and the core action is front-loaded ahead of the lifecycle note. Every sentence contributes: the first establishes what is created and where, the second establishes when it becomes visible.

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 three-parameter create tool with nested input, no output schema, and annotations covering the safety profile, the description supplies the essential mental model (draft-scoped, publish-gated). The remaining gaps — what is returned and whether the draft must already exist — are modest rather than blocking.

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 67%, and the uncovered field (article.title) is self-evident, so the schema carries most of the meaning. The description adds nothing about parameters — no mention of the draft ref format, the optional store selector, or why blogId must be resolved up front — leaving it at the baseline for a well-documented schema.

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 description names a specific verb and resource ('Create a new blog article') and scopes it to a Fudge draft, which separates it from siblings such as create_draft_page or create_draft_product by resource type. It never explicitly contrasts itself with those siblings, but the resource noun is distinctive enough for an agent to choose correctly.

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 only implied: the 'draft' framing suggests it belongs in the draft-authoring workflow, and the preview/publish sentence hints at the lifecycle. There is no explicit when-not guidance, no statement of prerequisites (e.g., an existing draft ref), and no named alternative for editing existing content such as edit_draft_content.

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