The Notion MCP server exposes 24 tools whose definitions cost approximately 17,476 tokens in every single conversation, whether or not any of them is ever called. Against the 19 static rules in the catalogue it scores 86 out of 100 — grade B — raising 95 scored findings in 3 of the six categories.
Its strongest category is naming at 100/100; the weakest is schemas at 68/100. It is catalogued here under Productivity and Docs, alongside other servers agents reach for in the same kind of work.
At 17,476 tokens the surface takes about 9% of a 200,000-token context window, and it takes it on every turn — this is rent, not a one-off cost. That averages 728 tokens per tool definition, counted with the o200k_base encoding.
Against a category median of 2,360 tokens, this surface runs about 641% above the middle of the pack.
The findings below are grouped by severity, and each links to the rule that produced it.
`schemas/loose` accounts for 40 findings. Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes. On this surface it fires on `API-get-self`, `API-post-search` and `API-patch-block-children`, among 8 others.
37 findings come from `schemas/param-desc-missing`. Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes. On this surface it fires on `API-get-user`, `API-post-search` and `API-update-a-block`, among 9 others.
`schemas/complexity-budget` contributes 8 findings. Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often. On this surface it fires on `API-patch-page`, `API-post-page` and `API-create-a-comment`, among 4 others.
Notion's surface raises 4 further rules — `design/overlap-cluster`, `design/enum-in-prose`, `surface/token-budget` and `surface/tool-budget` — listed in full below.
Findings that measurably degrade tool selection.
Values enumerated in prose ('one of: a, b, c') are invisible to schema validation: the model can misspell them and the server only finds out at call time. If the value set is closed, encode it as an enum.
The direction to sort. Possible values include `ascending` and `descending`.
Values enumerated in prose ('one of: a, b, c') are invisible to schema validation: the model can misspell them and the server only finds out at call time. If the value set is closed, encode it as an enum.
The name of the timestamp to sort against. Possible values include `last_edited_time`.
Values enumerated in prose ('one of: a, b, c') are invisible to schema validation: the model can misspell them and the server only finds out at call time. If the value set is closed, encode it as an enum.
The name of the property to filter by. Currently the only property you can filter by is the object type. Possible values include `object`. Limitation: Currently the only filter allowed is `object` which will filter by type of object (either `page` or `data_source`)
Tools whose descriptions substantially overlap force the model to pick between near-synonyms — the classic cause of wrong-tool calls. Clusters are usually one tool wearing several names; consolidate with include-flags or a mode parameter.
API-get-user, API-get-users, API-get-self, API-get-block-children
Tools whose descriptions substantially overlap force the model to pick between near-synonyms — the classic cause of wrong-tool calls. Clusters are usually one tool wearing several names; consolidate with include-flags or a mode parameter.
API-retrieve-a-block, API-retrieve-a-page, API-retrieve-a-page-property, API-retrieve-a-comment, API-retrieve-a-data-source, API-retrieve-a-database, API-retrieve-page-markdown
Tools whose descriptions substantially overlap force the model to pick between near-synonyms — the classic cause of wrong-tool calls. Clusters are usually one tool wearing several names; consolidate with include-flags or a mode parameter.
API-update-a-block, API-update-a-data-source, API-update-page-markdown
Tools whose descriptions substantially overlap force the model to pick between near-synonyms — the classic cause of wrong-tool calls. Clusters are usually one tool wearing several names; consolidate with include-flags or a mode parameter.
API-get-user, API-get-self, API-post-search, API-get-block-children, API-patch-block-children, API-retrieve-a-block, API-update-a-block, API-delete-a-block, API-retrieve-a-page, API-patch-page, API-post-page, API-retrieve-a-page-property, API-retrieve-a-comment, API-create-a-comment, API-query-data-source, API-retrieve-a-data-source, API-update-a-data-source, API-create-a-data-source, API-list-data-source-templates, API-retrieve-a-database, API-move-page
Tools whose descriptions substantially overlap force the model to pick between near-synonyms — the classic cause of wrong-tool calls. Clusters are usually one tool wearing several names; consolidate with include-flags or a mode parameter.
API-retrieve-page-markdown, API-update-page-markdown
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Deeply nested inputs, very wide property lists, and stacked oneOf/anyOf force the model to solve a constraint puzzle before every call. Flatter, narrower inputs get filled correctly more often.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Loose schemas (bare objects, untyped arrays, open additionalProperties) turn schema validation off exactly where the model is most likely to hallucinate argument shapes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
Undescribed parameters get filled by guesswork. Every property the model must populate deserves a sentence saying what it means and what shape it takes.
The serialized tools/list payload is injected into every conversation that connects the server, before any work happens. Its token cost is a per-message tax.
Tool selection accuracy degrades as the surface grows: more near-neighbours to confuse, more tokens spent before the first user message. Fewer, intent-shaped tools outperform one-tool-per-endpoint surfaces.
3 of the six categories come through clean: naming, descriptions and annotations. In practice that means the tool names follow one convention end to end, every tool carries a description long enough to disambiguate it and read and write operations are machine-distinguishable before a client runs them.
The heaviest definition is `API-update-page-markdown` at 1,281 tokens, roughly 7% of the total; the lightest, `API-get-self`, costs 594. Every tool carries a description, ranging from 49 to 280 characters.
All 24 declare annotations, so a client can tell a read from a write before running one. Input schemas average 3 top-level parameters and nest 4 levels deep at their worst, with 1 tool taking no input at all.
All 24 tools as published, heaviest first. Token counts use the o200k_base encoding and are approximate.
| Tool | Tokens | Description | Params | Required | Depth | Annotations |
|---|---|---|---|---|---|---|
API-update-page-markdown | 1,281 | 280 chars | 6 | 2 | 4 | yes |
API-post-search | 1,096 | 58 chars | 5 | 0 | 2 | yes |
API-patch-page | 888 | 65 chars | 6 | 1 | 3 | yes |
API-post-page | 818 | 56 chars | 5 | 2 | 2 | yes |
API-query-data-source | 769 | 62 chars | 8 | 1 | 2 | yes |
API-update-a-block | 726 | 57 chars | 3 | 1 | 1 | yes |
API-create-a-comment | 724 | 57 chars | 2 | 2 | 4 | yes |
API-update-a-data-source | 720 | 63 chars | 4 | 1 | 2 | yes |
API-patch-block-children | 712 | 64 chars | 3 | 2 | 2 | yes |
API-retrieve-page-markdown | 705 | 231 chars | 2 | 1 | 1 | yes |
API-retrieve-a-page-property | 703 | 72 chars | 4 | 2 | 1 | yes |
API-get-block-children | 692 | 66 chars | 3 | 1 | 1 | yes |
API-create-a-data-source | 687 | 63 chars | 3 | 2 | 2 | yes |
API-retrieve-a-comment | 686 | 60 chars | 3 | 1 | 1 | yes |
API-retrieve-a-page | 679 | 58 chars | 2 | 1 | 1 | yes |
API-get-users | 662 | 49 chars | 2 | 0 | 1 | yes |
API-move-page | 640 | 54 chars | 2 | 2 | 1 | yes |
API-list-data-source-templates | 639 | 74 chars | 3 | 1 | 1 | yes |
API-retrieve-a-data-source | 617 | 65 chars | 1 | 1 | 1 | yes |
API-retrieve-a-database | 612 | 62 chars | 1 | 1 | 1 | yes |
API-retrieve-a-block | 611 | 59 chars | 1 | 1 | 1 | yes |
API-delete-a-block | 610 | 57 chars | 1 | 1 | 1 | yes |
API-get-user | 603 | 50 chars | 1 | 1 | 1 | yes |
API-get-self | 594 | 73 chars | 0 | 0 | 0 | yes |
Notion ranks 3 of 3 scanned Productivity and Docs servers, 10 points below the category median of 96.
The closest comparisons in this directory are Memory, Microsoft Learn and MongoDB, which sit nearest on score and face the same kind of surface-design pressure.
A fix plan turns these findings into an ordered set of changes with the token saving of each one.
This page is a static analysis of Notion's published tools/list surface on the date shown. It is not a security review, a performance benchmark, or a judgement of the product behind the surface. Read how the score is computed, or browse every audited server.