replace_content

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

With no annotations provided, the description carries the full behavioral burden, and it delivers extensively. It discloses atomicity, block-ID preservation, unmatched block replacement, dropped page types, bookmark/embed preview loss, and warning codes. It also describes the dry-run behavior and response shape, so the agent knows exactly what to expect.

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 long but every sentence earns its place, covering core behavior, preservation caveats, alternatives, parameter effects, docs references, and return values. The most important facts are front-loaded, with the atomic replacement behavior stated first and supporting details organized in a logical progression.

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?

This is a complex tool with five parameters, no annotations, and no output schema, yet the description is nearly self-contained. It covers the return value with success/truncated/warnings/block_map details, documents the dry-run response, names warning codes, and points to docs for further detail. The only minor gap is that not every warning code is enumerated, but the description references docs and gives representative examples, which is sufficient.

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, but the description adds meaningful semantic value beyond the schema. It explains the effect of collapse_soft_wraps on single line breaks, mentions that replace_content renders in-paragraph line breaks as separate paragraphs regardless of the option, and clarifies that bookmarks/embeds are written as bare URLs. These details help the agent choose parameter values correctly.

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: 'Replaces all page content with the provided markdown atomically (one Notion API call).' This makes the tool's core action unmistakable and distinguishes it from sibling tools like append_content, which adds rather than replaces content. It also clarifies that this is an all-page replacement, not a targeted edit.

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 explicit when-to-use and when-not-to-use guidance, including 'use duplicate_page first or edit those types via the Notion UI' when the source contains child_page subpages or other unsupported constructs. It also provides concrete parameter-level guidance, such as recommending collapse_soft_wraps for hard-wrapped prose files and warning not to use it when re-uploading content read from Notion. This routes the agent to alternatives and away from misuse.

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