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

Annotations already declare it read-only, non-destructive, and closed-world, but the description adds substantial return-behavior context: Markdown body up to 100,000 characters with bodyTruncated flag, comments oldest-first capped at 500 with commentsTruncated, authorship by project members, and access by any project role. This is rich behavioral detail beyond what annotations provide.

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?

Front-loads the core action ('Reads one note or discussion in full') and then packs only relevant details about the returned content into a single dense but waste-free sentence. Every clause (truncation flags, comment ordering, rev, authorship, access) 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?

With no output schema, the description carries the full burden of describing return values, and it does so thoroughly: title, Markdown body, truncation indicators, author, pinned/archived state, comments with limits, and the revision needed for editing. Nothing an agent needs to call and interpret the tool correctly is missing.

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% for the single pageId parameter, and the description's phrase 'one note or discussion' merely restates what the schema already documents. With the schema doing the heavy lifting, the baseline score of 3 is appropriate.

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?

States a specific verb ('Reads') and resource ('one note or discussion') and adds scope ('in full'), which distinguishes it from sibling list_pages and update_page. An agent can identify exactly what this tool returns 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?

Provides clear context for use: reading a single page in full, with the explicit note that the returned rev is meant to be sent back when editing. It does not name alternatives such as list_pages for discovery or set_page_pinned for mutations, so it falls short of explicit when/when-not guidance.

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