unmanned_merge_pages

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains that the merge is 'soft', that the old id redirects, labels and live facts move with original authors, and that the undo is a split. This gives the agent a clear picture of side effects and reversibility, which is more than most descriptions offer.

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 compact—two sentences—and the primary purpose is front-loaded in the first sentence. The second sentence adds necessary behavioral detail without fluff. It loses one point because the phrase 'tier 1' and the listing of behaviors could be structured more clearly, but overall it is efficient.

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 merge operation with no output schema and no annotations, the description is moderately complete. It covers the key outcomes (redirect, label/fact movement, undo behavior) and the eligibility condition. However, it omits parameter definitions and any prerequisites, and does not describe what the response contains, leaving the agent partially in the dark for a nontrivial mutation.

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 0%, so the description must explain all three parameters. It implies 'entity_id' is the duplicate and 'into' is the real page, but it never explicitly defines them or explains the 'reason' field. Without param-level detail, an agent cannot reliably construct a correct call, making this a significant gap.

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 action (merge) on a specific resource (pages) and clearly distinguishes a duplicate page from the real one. It adds a 'tier 1' qualifier and explicitly warns against merging similar things, which separates it from other page operations. This is unambiguous and not a tautology.

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 a clear condition for when to use the tool: 'Merge only true duplicates — same THING, not similar things.' This provides guidance on when NOT to use it, which is valuable. However, it does not explicitly name alternative tools (like split_page) or state when to prefer them, leaving some inference to the agent.

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