commit_page_draft

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

Annotations only declare readOnlyHint=false; the description adds substantial behavioral context: incremental one-section-per-request writes, a 120s per-request timeout, dry_run preview semantics, and full resumability via retained page_id + committed_count. This is exactly the kind of mutation/recovery detail annotations cannot convey.

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 action, then the dry_run modes, then a capped RESUMABLE block for the failure path. Three compact segments, no filler, and the escalation-worthy detail is surfaced with emphasis.

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 mutation tool with no output schema and only two parameters, the description covers the write behavior, timeout risk, dry-run preview, and failure recovery. Nothing an agent needs to invoke it correctly or recover from a mid-commit failure 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 the baseline is 3, but the description goes further: dry_run=true validates the assembled page and previews stats while false creates then appends sections, adding meaning beyond the schema's terse wording. draft_id origin is only noted in the schema, so no extra credit there.

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 (persist/commit), resource (local page draft), and distinguishing mechanism (incremental, one section per request). The dry_run paragraph clarifies both modes, and the resumable note tells the agent exactly what the tool does on failure. It is clearly separable from start_page_draft and add_draft_section.

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?

Explains the dry_run default and what each mode does, which implicitly guides usage, but never explicitly states when to call this versus start_page_draft/add_draft_section or that it must follow draft construction. Usage is inferable from the workflow but not spelled out.

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