Update a dochost page

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

Beyond annotations (readOnlyHint=false, destructiveHint=true), the description reveals what stays the same (URL, view/like counts, expiry), what changes (body, format, title), and idempotence (resending identical content is a no-op). This gives the agent a precise mental model of side effects and is consistent with the annotations.

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?

Three sentences, each earning its place: operation and scope first, then behavioral details, then routing guidance. No filler or redundant restatement of the title or 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 4-parameter mutation tool with an output schema, the description covers selection, mutation scope, preserved fields, and idempotence. The only notable gap is minimal explicit parameter-level guidance for slug and format, but the schema and enum mostly cover invocation. Overall it is complete enough for an agent to use correctly.

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 property descriptions are absent (0% coverage), but the description partially compensates by indicating that body, format, and title are the mutable fields and that the URL stays stable, which implies slug identifies the page. It does not explicitly define slug or explain format values, though the schema's enum and min/max constraints fill some of that gap. This is adequate but not fully compensating.

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 states a specific verb ('replace') and resource ('one of your pages') with clear scope: 'in place.' It explicitly distinguishes update_page from publish by explaining that publishing again creates a second link, so the tool's purpose is unambiguous and easily separated from its siblings.

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?

Usage guidance is explicit: 'Prefer this over publishing again whenever the user is revising something you already published for them.' It also explains the downside of the alternative ('a second publish creates a second link and strands the one they already shared'), so an agent knows exactly when to choose update_page over publish.

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