Retrieve a Notion page's title, URL, properties, and markdown content. Provide a page alias, URL, ID, or exact title to fetch the full page details for reading or further processing.
A Notion page, as {title, url, properties, markdown}. The body is markdown;
block types outside the supported subset appear as
<!-- unsupported: TYPE -->.
ref: an alias, a notion.so URL, an id, or an exact page title.
| Name | Required | Description | Default |
|---|---|---|---|
| ref | Yes |
Changes observed during successful MCP inspections.
v0.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description caries the full disclosure burden. It meaningfully discloses the return envelope and a conversion behavior: unsupported block types appear as '<!-- unsupported: TYPE -->' comments. It doesn't cover not-found errors or permissions, but the getter nature is apparent and the output behavior is usefully detailed.
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?
The description is compact, front-loaded with the response shape, and each clause earns its place: return fields, markdown/unsupported-block behavior, and ref formats. There is no filler or repetition of schema 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?
For a one-parameter retrieval tool with no output schema, the description covers the return object, the markdown conversion caveat, and valid ref forms. It is slightly incomplete in not pointing to sibling tools for discovery workflows or describing not-found behavior, but those are secondary given the simple operation.
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?
The input schema only says 'ref' is a required string with no description, and schema coverage is 0%, so the description is the only parameter documentation. It adds substantial meaning by enumerating accepted ref formats: alias, notion.so URL, id, or exact page title. It doesn't define 'alias' further, but it is a clear gain over the schema.
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 identifies the resource (a Notion page) and the shape of what the caller recieves ({title, url, properties, markdown}), so an agent can tell this returns page content rather than a schema or database list. It doesn't use an explicit verb such as 'retrieve' or 'fetch' and doesn't contrast with siblings like search or query_database, so it stops short of the top tier.
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?
Usage is implied by the tool name and by the 'ref' field, which lists accepted inputs (alias, notio.so URL, id, or exact title). However, the description never says when to choose this over query_database, search, or list_databases, and provides no exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.