Skip to main content
Glama

mcp-notion__notion-search

Read-onlyIdempotent

Search Notion pages and databases, or look up a user by name or email. Does not search connected apps; use connector_search, when listed, for sources such as Slack, Google Drive, GitHub, mail, or calendar. When connector_search is listed, call it in parallel with search on the first search for an information need, unless the user names a source, the request is a user lookup, or the request is about Notion pages or databases themselves, such as finding a page to read or edit. Decisions, status updates, and discussions often live in connected sources. Preserve distinctive names and identifiers.

Use a non-empty query for content searches. Leave the query empty only when you also send filters or a non-relevance sort, as in the browse example below. Omit optional parameters unless needed. Do not add filters or sorting just to fill in defaults. Business or Enterprise is required for filters.edited_by_user_ids, filters.last_edited_date_range, filters.title_only=true, filters.content_status, more than one distinct … Through Royally: its server marks it read-only, so it runs straight away.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "mcp-notion__notion-search"
  }
}

Input Schema

NameRequiredDescriptionDefault
sortNoResult ordering for Notion workspace search. Omit for the default "relevance" ordering. "last_edited" and "created" require Business access.
queryYesShort, specific keywords for Notion content search. For user search, enter a name or email address. Provide a non-empty query unless intentionally browsing with filters or a non-relevance sort.
skillNoFor tracking only: the name of the agent skill you are following for this task, such as notion-meeting-prep. Omit if you are not following a skill.
filtersNoOptional exact filters for Notion workspace search. Omit unless required by the request. Keep filter fields nested here; do not send them at the top level. Some filters require Business access.
site_idNoSite to run this tool on: ded71e55-0da4-4a52-8f14-1224fa9979b9 (https://mcp.notion.com/mcp)
page_urlNoOptionally restrict keyword search to a page and its descendants. Accepts a Notion page URL or ID.
page_sizeNoMaximum number of results to return (default 10). Lower values reduce response size. Values outside the range (minimum 1, maximum 50) are clamped.
query_typeNoSpecify type of the query as either "internal" or "user". Always include this input if performing "user" search.
teamspace_idNoOptionally, provide the ID of a teamspace to restrict search results to. This will perform a search over content within the specified teamspace only. Accepts the teamspace ID (UUIDv4) with or without dashes.
data_source_urlNoOptionally restrict keyword search to a data source URL returned in a <data-source> tag.
instructions_versionNoNotion setup instructions version, such as 0.0.2. Omit if unknown.
max_highlight_lengthNoMaximum character length for result highlights (default 200). Set to 0 to omit highlights entirely. Values outside the range (minimum 0, maximum 500) are clamped.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, so the description's job is lighter, and it does add real value by disclosing plan-tier gating (Business/Enterprise required for edited_by_user_ids, last_edited_date_range, title_only, content_status, multi-teamspace) and the cost trade-off implied by omitting optional params. It loses a point because the tail is corrupted ('more than one distinct … Through Royally: its server marks it read-only'), an incomplete sentence plus a fragment that merely restates the readOnlyHint annotation.

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

Conciseness3/5

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

The first two thirds are dense and front-loaded, with the exclusion and the parallel-call rule placed before the parameter advice. However, the ending is truncated mid-clause ('more than one distinct …') and appends an unrelated sentence about another server's read-only marking, which is noise an agent must parse past.

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

Completeness4/5

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

For a 12-parameter, nested, plan-gated search tool, the description covers the key decision points: scope boundaries, sibling routing, query rules, and access tiers. With no output schema, it could say more about what results look like (highlights, page_size effects), and the garbled tail leaves the Business-plan enumeration incomplete.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all 12 parameters thoroughly, including enums, ranges, and plan requirements; baseline is 3. The description adds one cross-parameter operational rule (query emptiness tied to filters/sort) but otherwise restates constraints the schema carries, so it does not meaningfully exceed the baseline.

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?

Opens with a specific verb and two named resources: 'Search Notion pages and databases, or look up a user by name or email.' It then explicitly carves out what it is not ('Does not search connected apps') and names the sibling that covers that ground (connector_search), so an agent can route correctly without opening a schema.

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

Usage Guidelines5/5

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

Gives explicit when-to-use, when-not-to-use, and parallel-invocation guidance, including the three exceptions (user names a source, user lookup, request about Notion content itself). It also states a concrete query rule: non-empty for content searches, empty only when filters or a non-relevance sort accompany it, and warns against padding defaults.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources