restore_collective_page

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

Annotations already indicate readOnlyHint=false, idempotentHint=false, and destructiveHint=false, covering the mutation/non-destructive safety profile. The description adds no additional behavioral context: no mention of side effects, permissions required, reversibility, or error behavior (e.g., what happens if the page is not in trash). Since annotations already exist, the description's contribution is minimal.

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 extremely concise: one sentence for the action, then a clean args list. It is front-loaded with the primary purpose, and there is no fluff or redundant phrasing. Every element serves a purpose.

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?

The description provides the basic input parameters and mentions the return value ('JSON object with the restored page details'), which is helpful given an output schema exists. However, it lacks context on when to use the tool (usage guidelines) and does not describe behavioral details like error conditions or prerequisites. For a low-complexity tool with two integer params, this is adequate but not complete.

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 0%, so the description must compensate. It lists the two parameters as 'The numeric collective ID' and 'The numeric page ID,' which adds only that they are numeric (already implied by integer type) but does not explain what a collective is or what a page represents in this context. No added meaning beyond the schema's basic type and name.

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 clearly states the action: 'Restore a page from the collective's trash.' This specifies the verb (restore), the resource (a page within a collective), and the source (trash), which distinguishes it from sibling tools like restore_collective (restore entire collective) and trash_collective_page (move to trash). It is not a tautology and provides concrete purpose.

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 no guidance on when to use this tool versus alternatives. It does not mention that it should be used when a page is in trash and needs to be brought back, nor does it contrast with restore_collective (which restores a whole collective) or delete_collective_page (which permanently deletes). The agent must infer usage from the name and sibling context.

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