delete_page

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's added value lies in detail beyond safety labels. It adds the crucial nuance that the default action is a trash move (recoverable in principle) while permanent delete is the truly destructive path, plus the auth requirement of space admin. It falls short only in not disclosing side effects on child pages or explicitly confirming trash is recoverable via restore_page.

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?

Two sentences with zero filler: the primary behavior is front-loaded, and the permission caveat follows immediately. Every clause earns its place.

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 essential decision (trash vs permanent) and the key prerequisite (admin) are covered, which is the core of what an agent needs to invoke the tool correctly. However, for a destructive tool with openWorldHint=true and no output schema, gaps remain: no mention that trashed pages are recoverable (restore_page sibling exists), no cascade effects on child pages or attachments, and no return-value note. Adequate but missing secondary context about the destructive footprint.

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 both parameters are already documented (page_id as UUID/slugId, permanently with default false). The description adds meaning by tying the space-admin requirement to the permanently=true path, a constraint not present in the schema. This is useful semantic context beyond what the structured fields provide.

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 names a specific verb ('Move to trash' / 'permanently delete') and a specific resource ('a page'), making the operation unambiguous. The dual-mode behavior is stated up front, which distinguishes this tool from siblings like restore_page (the inverse operation) and move_page (relocation rather than deletion).

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 implies when to use the tool (when a page needs to be removed) and gives one concrete constraint: permanent deletion requires space admin. However, it never names alternatives or exclusions — it does not point to restore_page for undoing a trash, nor delete_space for space-level deletion, even though those siblings exist. The guidance is adequate but relies on the agent to infer routing.

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