# Notion: tool descriptions scored

- tools/list taken: 2026-09-30 (UTC)
- From: [npm @notionhq/notion-mcp-server@1.0.0](https://www.npmjs.com/package/@notionhq/notion-mcp-server)
- Homepage: https://github.com/makenotion/notion-mcp-server
- Scoring rules: v2
- Tools: 24
- Average: 33.0 / 100 (Rain)
- Near-identical pairs: 57

This page shows how Notion's tool descriptions scored, the issues found and the names of its tools and parameters. The descriptions are the server's own: read them where the copy came from.

## Across the server

- Minor: 57 pairs with nearly the same description in all; the top 12 are shown.
- Minor: The server has no instructions. Say there, once, what the server is for and when to use it: Claude Code and Gemini CLI read the instructions before the tool descriptions.

## Tools

- `API-query-data-source`: 20 / 100
  - Major: The description only restates the name (9 words).
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: filter, sorts, start_cursor, page_size, archived, in_trash.
  - Minor: String arguments with no constraint or example: start_cursor.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: The meaning of the boolean argument archived is unclear.
  - Minor: The meaning of the boolean argument in_trash is unclear.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: data_source_id. Name the tool or the place that returns it, or models look it up first.
- `API-create-a-comment`: 24 / 100
  - Major: The description is too short (7 words).
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: parent, rich_text, rich_text[].text.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: parent. Name the tool or the place that returns it, or models look it up first.
- `API-update-a-data-source`: 24 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: title, description, properties.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: data_source_id. Name the tool or the place that returns it, or models look it up first.
- `API-create-a-data-source`: 25 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: parent, properties, title.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: parent. Name the tool or the place that returns it, or models look it up first.
- `API-get-user`: 25 / 100
  - Major: The description is too short (6 words).
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: user_id.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: user_id. Name the tool or the place that returns it, or models look it up first.
- `API-list-data-source-templates`: 25 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: start_cursor, page_size.
  - Minor: String arguments with no constraint or example: start_cursor.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: data_source_id. Name the tool or the place that returns it, or models look it up first.
- `API-patch-page`: 25 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: properties, archived, icon, cover.
  - Minor: The meaning of the boolean argument archived is unclear.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: page_id. Name the tool or the place that returns it, or models look it up first.
- `API-move-page`: 29 / 100
  - Major: The description only restates the name (8 words).
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Arguments without a description: parent.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: page_id, parent. Name the tool or the place that returns it, or models look it up first.
- `API-update-a-block`: 30 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Arguments without a description: type.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: block_id. Name the tool or the place that returns it, or models look it up first.
- `API-post-page`: 34 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Arguments without a description: parent, properties.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: parent. Name the tool or the place that returns it, or models look it up first.
- `API-post-search`: 34 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Arguments without a description: sort, filter.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
- `API-delete-a-block`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: block_id. Name the tool or the place that returns it, or models look it up first.
- `API-get-block-children`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: block_id. Name the tool or the place that returns it, or models look it up first.
- `API-get-users`: 35 / 100
  - Major: The description is too short (6 words).
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
- `API-patch-block-children`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: block_id. Name the tool or the place that returns it, or models look it up first.
- `API-retrieve-a-block`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: block_id. Name the tool or the place that returns it, or models look it up first.
- `API-retrieve-a-comment`: 35 / 100
  - Major: The description is too short (7 words).
  - Major: Says nothing about when to use it, or when not to.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: block_id. Name the tool or the place that returns it, or models look it up first.
- `API-retrieve-a-data-source`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: data_source_id. Name the tool or the place that returns it, or models look it up first.
- `API-retrieve-a-database`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: database_id. Name the tool or the place that returns it, or models look it up first.
- `API-retrieve-a-page-property`: 35 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: String arguments with no constraint or example: start_cursor.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: page_id, property_id. Name the tool or the place that returns it, or models look it up first.
- `API-retrieve-a-page`: 40 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: page_id. Name the tool or the place that returns it, or models look it up first.
- `API-get-self`: 42 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
- `API-retrieve-page-markdown`: 50 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: page_id. Name the tool or the place that returns it, or models look it up first.
- `API-update-page-markdown`: 50 / 100
  - Major: Says nothing about when to use it, or when not to.
  - Major: Arguments without a description: replace_content, update_content, insert_content, replace_content_range.
  - Minor: The description mentions none of its 3 or more arguments.
  - Minor: Says nothing about what it returns.
  - Minor: Required identifiers whose description does not say where the value comes from: page_id. Name the tool or the place that returns it, or models look it up first.

Is your server listed here and you would rather it were not? Email support@forecall.dev, and we will take it off within 7 days.

[All scored servers](https://forecall.dev/en/servers)