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

Adds substantial context beyond annotations: the live store is untouched, and repeated calls merge into one pending change set with replace semantics for single values and whole-list replacement for arrays. That is the crucial behavior for an agent. It does not, however, explain why destructiveHint=true (e.g. what a later publish overwrites) or discuss permissions, though the repeat-call semantics implicitly reconcile with the declared idempotentHint=false without contradicting it.

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 core guarantee ('live store does not change') before the mechanics; every sentence carries information about draft semantics. It is dense with parentheticals but no sentence is filler.

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 draft-staging mutation with no output schema, it covers the safety model and merge semantics well. Gaps remain: no mention of what is returned (draft identifier or version), and the `kind` parameter and its interaction with `id='settings'` are unexplained.

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?

The description adds real meaning to `changes` ('a partial object in the write-guide field names'), pointing the agent to get_write_guide and clarifying that only changed fields are sent. With only 60% schema coverage, this compensates for the bare `changes: object` schema, but the `kind` parameter is undocumented in both the schema and the description.

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 and resource ('Save changes to a live item (or app settings) as UNPUBLISHED changes') and makes the key distinction explicit: the live store keeps its current version until publish. That separates it cleanly from sibling draft-mutators such as create_draft, edit_draft, and preview_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?

Gives clear workflow context: staging is provisional, publishing happens via publish_draft or the merchant's Publish click, and the draft 'can be discarded' (discard_draft). It never states an explicit exclusion, e.g. 'use create_draft when the item does not exist yet', so the boundary against create_draft is left to inference.

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