update_draft

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

With no annotations provided, the description carries the full burden, and it delivers meaningful disclosure: partial-update semantics, the body being untouched, and the side effect that a cover_image not already hosted by Substack is downloaded and re-hosted first. It does not cover auth/rate-limit/error behavior, but the disclosed traits go well beyond a bare mutation description.

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 sentences, front-loaded with purpose, followed by the partial-update rule, the cover_image re-hosting behavior, and id sourcing. Every sentence earns its place; no redundancy with the schema.

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 12-parameter mutation tool with no annotations and no output schema, the description covers the essentials: scope of what changes, the safety-relevant partial-update behavior, a non-obvious side effect (re-hosting), and parameter provenance. The schema fills in all parameter details. The only gap is the absence of return-value/error information, which the description could have mentioned since there is no 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 description coverage is 100%, so the baseline is 3. The description adds genuine value beyond the per-parameter schema by stating the partial-update rule — 'only the fields you pass change' — which contextualizes all 11 optional parameters as omit-to-keep semantics. This is a meaningful addition, justifying a 4.

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 specific verb and resource: 'Change an existing draft's title, subtitle or any of its Post settings', followed by an explicit field list. This clearly differentiates update_draft from siblings like create_draft_post, set_post_body, publish_draft, and delete_draft.

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 description gives clear context on when to use the tool: it is a partial update ('only the fields you pass change'), and explicitly notes the body is left alone, which implies set_post_body is the alternative for body edits. It also tells the agent where to source the required id ('Take the id from list_posts or create_draft_post'). It stops short of explicitly naming when-not-to-use alternatives, so it earns a 4 rather than a 5.

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