manage_page

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

No annotations are provided, so the description carries the full burden. It identifies both operations as mutations but discloses nothing beyond that: it doesn't state whether creating a page also switches to it, whether duplicate names are allowed, what changes occur to the current view/selection, or what the tool returns. For a mutation tool with zero annotation coverage, this is a significant gap.

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?

One sentence, perfectly front-loaded with the two operations, zero filler. The second phrase ('or switch the active page') adds a distinct purpose without redundancy. Structurally efficient and easy to scan.

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 tool with two actions, conditional parameters, no annotations, and no output schema, the description is adequate but lean. It covers the two operations but doesn't address return behavior, side effects on the active page when creating, or the parameter-action pairing rules. The schema fills part of the gap (required action, enum values), but the description leaves behavioral outcomes unstated.

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 100%, so the baseline is 3. The description adds marginal value by scoping creation to 'the document' and mapping switch behavior to 'active page,' which loosely reinterprets the action enum. However, it doesn't clarify the conditional relationship between action, name, and pageId beyond what the schema already conveys.

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-resource pair ('create a new page' / 'switch the active page') and clearly differentiates this tool from all siblings. No other sibling manages pages — the nearest are object creators (create_frame, create_rectangle, create_text) which operate on different resources. An agent can select this tool unambiguously.

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 the two use cases (creating vs. switching) through the action verbs, but provides no explicit when-to-use guidance, prerequisites, or exclusions. It also doesn't name alternatives or clarify which action requires which parameters (name vs. pageId). The usage context is inferable but not spelled out.

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