promote_dev_draft

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

No annotations are present, so the description carries the full transparency burden. It discloses the mutation ('replaces the shared draft blocks'), ownership ('belongs to the token's user'), failure mode, and post-result warning semantics ('blockWarnings... violates the workspace block manifest'). This is unusually rich behavioral disclosure for a one-parameter tool.

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 front-loads the primary action and packs prerequisites, failure, warning, and confirmation into five purposeful sentences. There is little redundancy; each sentence adds operational or safety-relevant information.

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 one-parameter mutation with no output schema and no annotations, the description covers the core call path, failure behavior, and result interpretation. It could additionally specify required parameters or return payload details, but these are largely covered by the schema and the blockWarnings note.

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 only parameter, pageId, is already fully described in the input schema ('Page id'), so schema coverage is 100%; the description adds no further type, format, or constraint details about the parameter. The baseline of 3 applies because the description mostly references 'the page' without expanding pageId semantics.

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 uses a specific verb ('Promote') and a concrete resource ('your per-user dev draft overlay onto the page's shared draft'), and clarifies what the operation does ('replaces the shared draft blocks'). This distinguishes it from siblings like update_page_blocks or publish_page because it targets the draft-promotion workflow rather than editing or publishing.

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?

It gives a temporal precondition ('Do this after the block code for the composed types is deployed to the site'), a failure condition ('Fails when you have no dev draft for the page'), and an explicit user-confirmation gate ('Only call after the user confirms'). It does not name alternative sibling tools or state when not to call, but the context is sufficient for the primary decision.

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