Create draft

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

Goes beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false) by explaining side-effect scope: a draft is inert, nothing is sent, and the call is safe to run without confirmation. It also discloses the return payload (post_id and editor link) and an input restriction (local image files cannot be used). What it doesn't cover is whether the draft is visible to anyone in the publication dashboard or whether repeated calls create duplicates — although idempotentHint=false already hints at the latter.

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-loaded with the two facts that matter most (what it makes, and that nothing is sent yet), then the Markdown capability list. The Markdown enumeration is long but each item constrains what the caller can legitimately submit, so it earns its space; a tighter version could group the inline-formatting items.

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 4-parameter creation tool with no output schema, the description covers purpose, side effects, the follow-up tools, the return values, and the content-format constraints. There is nothing an agent needs in order to call this correctly that 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 coverage is 100%, so title, subtitle, audience and body_markdown are already documented, making 3 the baseline. The description adds real meaning for body_markdown by enumerating the supported Markdown subset (headings, lists, quotes, code blocks, images by public URL, inline formatting) and, importantly, the exclusion of local image files — a constraint an agent would otherwise get wrong.

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 and resource ("New draft from Markdown") and immediately bounds its scope ("Nothing is sent until you publish or schedule it"). It names the sibling actions (schedule_post, publish_post) that do the sending, so an agent can distinguish this creation step from the publication steps without reading any schema.

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?

Explicitly states the when: build content now, nothing is delivered. Explicitly names alternatives: schedule_post or publish_post for sending. It even gives a decision rule ("A draft reaches no one, so it runs without asking"), which is exactly the guidance an agent needs before invoking.

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