Skip to main content
Glama
Sign In
awkoy

notion-mcp-server

by awkoy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Notion Read

notion_read
Read-onlyIdempotent

Run a named Notion read operation to retrieve pages, databases, blocks, comments, users, views, or files without modifying anything.

Instructions

Run one Notion read operation by name. Nothing is modified.

Call: { operation, payload } — payload carries that operation's fields. Common: search_pages { query }, get_page { page_id }, get_page_markdown { page_id }, query_database { database_id, where? }, get_block_children { block_id }.

Responses are slimmed; pass verbose:true in payload for the raw Notion object. Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL, as copied from Share → Copy link. A block link's #fragment is used for block_id fields and a database link's ?v= for view_id fields.

If the payload is malformed, the error response includes the schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (query_database filters).

Input Schema

NameRequiredDescriptionDefault
payloadYesOperation parameters. Pass either single-op fields directly, or { items: [...], atomic?, idempotency_key?, concurrency? } for batch.
operationYesThe read operation to run. This list is the complete menu of read operations enabled on this server; notion_describe(operation) returns any operation's full schema.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv3.3.0
    • changedInput schema / properties / operation / enum
      Previous value: -[
-  "query_database",
-  "list_data_sources",
-  "get_data_source",
-  "list_data_source_templates",
-  "get_view",
-  "list_views",
-  "query_view",
-  "list_comments",
-  "get_comment",
-  "list_users",
-  "get_user",
-  "get_bot_user",
-  "get_self",
-  "list_file_uploads",
-  "get_file_upload",
-  "get_file_url",
-  "get_image",
-  "search_pages",
-  "get_page",
-  "get_page_markdown",
-  "get_block",
-  "get_block_children"
-]New value: +[
+  "query_database",
+  "get_view",
+  "list_views",
+  "query_view",
+  "list_comments",
+  "get_comment",
+  "list_users",
+  "get_user",
+  "get_bot_user",
+  "get_self",
+  "list_file_uploads",
+  "get_file_upload",
+  "get_file_url",
+  "get_image",
+  "list_data_sources",
+  "get_data_source",
+  "list_data_source_templates",
+  "search_pages",
+  "get_page",
+  "get_page_markdown",
+  "get_block",
+  "get_block_children"
+]
  2. Addedv3.0.1

TDQS

A4.8/5.0
Behavior5/5

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

Although annotations already declare read-only, idempotent, non-destructive behavior, the description adds substantial operational context: responses are slimmed by default, verbose:true returns raw objects, ids accept Notion URLs, and malformed payloads return schema plus an example for one-round-trip retry. It also discloses URL fragment and ?v= handling, which is beyond the annotations and schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action, then organized into compact paragraphs for call shape, common operations, response behavior, id handling, and error/describe guidance. Every sentence carries operational value, and the dense operation list is appropriate for a multi-operation router.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex multi-operation read tool with no output schema, the description covers the essential call contract, common payload shapes, response slimming, verbose override, id/URL flexibility, malformed-payload recovery, and when to use notion_describe. Nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the top-level parameters, but the description adds meaningful semantics beyond the schema by explaining that payload carries operation-specific fields and by listing common operation-field mappings like search_pages { query } and query_database { database_id, where? }. It also explains that every id field accepts Notion URLs and that verbose:true modifies response detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Run one Notion read operation by name,' and immediately clarifies 'Nothing is modified.' This clearly distinguishes notion_read from notion_write and positions notion_describe as the schema-discovery helper rather than a competing read path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear usage context and explicitly tells the agent when to call the alternative notion_describe: only for complex shapes such as query_database filters. It does not explicitly say to use notion_write for mutations, but 'read operation' and 'Nothing is modified' make the boundary clear.

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

Deploy Server

Other Tools