Update draft post

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

With no annotations, the description carries the full transparency burden. It discloses critical behaviors: the http(s) link restriction, reset of approved drafts to "draft" status, null-to-clear semantics, and the text/parts precedence rule. It does not mention permissions or response shape, but the disclosed side effects are substantive and give the agent a reliable mental model.

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?

The description is compact but information-dense. It leads with the action, then packs essential rules into a few sentences. Each sentence adds a distinct piece of guidance. Slightly longer than the minimal, but every clause earns its place.

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 10-parameter mutation tool with no annotations and no output schema, the description covers purpose, key behavioral rules, null handling, state transitions, and the sibling alternative. It omits minor details like mutual exclusivity constraints and response format, but the former is in the schema and the latter is less critical given the absence of an output schema.

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 baseline is 3. The description adds meaningful context beyond the schema: the "Same link rule as create_draft" clarifies URL handling, "Pass null to clear an optional field" generalizes null semantics, and "text wins and becomes parts[0]" explains a precedence not fully evident from the schema. This elevates the parameter understanding.

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 opens with a clear verb and resource: "Edit a draft's content" followed by a specific list of editable fields. It explicitly distinguishes itself from the sibling tool update_published_draft by stating "To change a live post, use edit_published_draft," making scope unambiguous.

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?

Provides explicit guidance: references the same link rule as create_draft, warns about the approved-draft reset behavior, and names the alternative tool for live posts. This directly answers when to use this tool vs. alternatives.

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