protect-page

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

Annotations are present (readOnlyHint=false, destructiveHint=true), and the description adds substantial context beyond them: the exact return payload, partial-update behavior, the inherited-protection exclusion, and three distinct failure modes (missing protect permission, unsupported action/level, invalid or past expiry). This is rich behavioral disclosure that no annotation field captures.

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?

At roughly five sentences, the description is dense but every sentence carries unique information: return value, partial-update rule, lifting procedure, inherited-protection exclusion, and failure conditions. The action and resource are front-loaded in the first clause, and the subtle semantics are ordered before the error conditions. No filler or repetition of schema content.

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 high-complexity tool (6 params, nested protections object, partial-update semantics, multiple failure modes) with no output schema, yet the description covers everything an agent needs: what is returned, how the core parameter behaves, edge cases (inherited protection, non-existent pages via the schema's create action), and when it fails. Nothing material is missing for correct invocation.

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 the baseline is 3. The description exceeds it by explaining the critical semantics of the protections object that the schema does not: actions named are set until expiry, omitted actions retain current protection, and 'all' lifts protection. This is essential meaning beyond the schema, though other parameters (wiki, expiry, cascade, comment) are already well documented there.

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: 'Changes the protection of a wiki page.' It also states what it returns (title, protections with expiries, cascade state), which pins down the tool's scope precisely. This distinguishes it from content-editing siblings like update-page and lifecycle tools like create-page/delete-page without ambiguity.

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 clear operational context: partial-update semantics ('Actions left out keep their current protection'), how to lift protection by naming every action 'all', and the caveat that inherited cascade protection is 'neither changed nor listed' — which implicitly sets expectations for when the tool cannot do what a caller might want. However, it never explicitly names alternatives or when-not-to-use conditions relative to sibling tools, so it stops short of a 5.

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