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

Annotations only declare it is a non-read-only, non-destructive, closed-world mutation. The description goes well beyond that: ids stay stable so layouts/backgrounds/copy keyed to them are unaffected, variant aliases embedding the old name are rebuilt, and two distinct rejection rules are spelled out. This is exactly the kind of consequence-of-calling information annotations cannot carry.

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?

Three sentences, front-loaded with the action and followed immediately by the safety guarantee — the highest-value fact in the strongest position. The parenthetical examples of blog names add a touch of bulk but each sentence carries distinct information.

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?

With no output schema, no annotations beyond safety flags, and three undocumented parameters, the description supplies the mutation semantics, side effects, and failure modes an agent needs. The only real gap is the unexplained projectId and any hint about what the tool returns after a successful rename.

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 carry parameter meaning. It implies the semantics of newName (the new label, validated against duplicates) and pageName (the target page), but never states what projectId is or why the page is addressed by name rather than id. Partial compensation only.

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?

"Change what a page is called" names a specific verb and resource, and the body immediately disambiguates it from neighbouring mutation tools (set_page_settings, reorder_pages, duplicate_page) by scoping it to the page's name alone. An agent knows exactly what this does without opening the schema.

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 conditions under which the call will be refused (duplicate name ignoring case/spacing/punctuation, blog-style names on non-blog pages), which is effectively a when-not-use signal. It stops short of naming a sibling to use instead for those cases (e.g. add_page for a new page), so it falls one step below fully explicit routing.

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