MCP Notion Server (@suncreation)

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.6
Disambiguation4/5
Most tools have distinct purposes targeting specific Notion resources (blocks, databases, pages, users, comments), but some potential overlap exists between notion_create_page and notion_create_database_item (both create pages, though in different contexts) and between notion_retrieve_block and notion_retrieve_page (both retrieve content, but blocks vs. pages). The descriptions help clarify these distinctions.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern with 'notion_' prefix (e.g., notion_create_page, notion_retrieve_database, notion_update_block). The verbs (append, create, delete, list, query, retrieve, search, update) are used predictably across resources, making the set highly readable and systematic.
Tool Count4/5
19 tools is slightly high but reasonable for a Notion server covering blocks, databases, pages, users, and comments. It includes essential CRUD operations and utilities like search and listing, though it might be borderline heavy compared to simpler APIs. Each tool appears to serve a specific function without obvious redundancy.
Completeness5/5
The tool set provides comprehensive coverage of the Notion domain, including full CRUD for blocks, databases, pages, and comments, plus utilities like search, user management, and querying. There are no apparent gaps; agents can perform complete workflows from creation to deletion and retrieval across all major resource types.
Average 3.3/5 across 19 of 19 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It doesn't disclose whether this is a read-only operation (implied but not stated), what permissions are needed, how pagination works, rate limits, or what the response contains. For a query tool with 6 parameters, this is insufficient behavioral context.
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 a single, efficient sentence with zero wasted words. It's appropriately sized for a tool with good schema documentation, though this conciseness comes at the expense of helpful context that would benefit an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a query tool with 6 parameters, nested objects, no output schema, and no annotations, the description is incomplete. It doesn't explain what the tool returns, how results are structured, pagination behavior, or error conditions. The agent must rely entirely on the input schema without guidance on output expectations.
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 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema. The baseline score of 3 reflects adequate coverage through schema alone, though the description contributes nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Query a database in Notion' clearly states the action (query) and resource (database), but it's vague about scope and doesn't differentiate from sibling tools like 'notion_retrieve_database' or 'notion_search'. It lacks specificity about what kind of query operation this performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'notion_retrieve_database' (which fetches metadata) or 'notion_search' (which searches across all content). The description offers no context about appropriate use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update a database' implies a mutation operation, but the description doesn't mention permissions required, whether changes are reversible, rate limits, error conditions, or what happens to unspecified properties. For a complex mutation tool with 5 parameters, this leaves significant behavioral gaps.
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 extremely concise at just 5 words. It's front-loaded with the core action and resource. There's zero wasted language or redundancy. For a tool with comprehensive schema documentation, this brevity is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with 5 parameters, nested objects, no annotations, and no output schema, the description is inadequate. It doesn't explain what 'updating' entails, what fields can be modified, how partial updates work, or what the response contains. The rich schema documentation helps, but the description should provide higher-level context about the update operation's scope and behavior.
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 5 parameters thoroughly. The description adds no additional parameter information beyond what's in the schema - it doesn't explain relationships between parameters, provide examples, or clarify usage patterns. Baseline 3 is appropriate when schema does all the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a database in Notion' states the basic action (update) and resource (database), but is vague about what specifically can be updated. It doesn't distinguish from sibling tools like notion_update_page_properties or notion_update_block, which also perform updates on different resources. The description lacks specificity about scope or fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing database ID), comparison to sibling tools like notion_create_database or notion_retrieve_database, or any context about when this update operation is appropriate versus other update tools in the Notion suite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention authentication requirements, rate limits, whether this is a write operation (implied but not explicit), what happens on success/failure, or any side effects. For a creation tool with zero annotation coverage, this represents a significant gap in behavioral context.
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 a single, efficient sentence with zero wasted words. It's appropriately sized for a basic tool description and front-loads the essential information immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a database creation tool with complex nested parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what constitutes a successful creation, what gets returned, error conditions, or how this tool relates to other Notion operations. The agent would need to infer too much from the sparse description.
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?
The schema description coverage is 100%, providing comprehensive documentation for all 4 parameters. The description adds no additional parameter information beyond the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter info in the description, which applies here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a database in Notion' clearly states the verb ('Create') and resource ('database in Notion'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'notion_create_database_item' which creates items within databases, leaving some ambiguity about scope differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'notion_create_page' or 'notion_create_database_item'. There's no mention of prerequisites, constraints, or typical use cases, leaving the agent with insufficient context for appropriate tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write operation, it doesn't address important behavioral aspects like authentication requirements, error conditions, rate limits, or what happens when properties don't match the database schema. The description mentions the 'format' parameter's effect on response format, but this is covered in the schema description.
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 a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a tool with good schema documentation and is perfectly front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens on success (what gets returned), error conditions, or important behavioral constraints. The absence of output schema means the description should compensate by describing return values, but it doesn't.
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?
With 100% schema description coverage, the baseline is 3. The description adds no additional parameter semantics beyond what's already documented in the schema. It doesn't clarify the relationship between 'database_id' and 'properties', nor provide examples of property structures that would be helpful for a creation operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new item') and resource ('in a Notion database'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling 'notion_create_page' or 'notion_create_database', which could cause confusion about when to use each specific creation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'notion_create_page' or 'notion_create_database'. There's no mention of prerequisites, context, or comparison with sibling tools, leaving the agent to guess about appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Delete a block' implies a destructive mutation, but it doesn't mention permissions required, whether deletion is permanent/reversible, rate limits, or what happens to child blocks. For a destructive operation with zero annotation coverage, this is a significant gap in transparency.
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 a single, direct sentence with zero wasted words. It's perfectly front-loaded with the core action and resource, making it immediately scannable and efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after deletion (success response, error conditions), doesn't mention permissions or side effects, and provides no usage context relative to sibling tools. The agent would struggle to use this tool correctly and safely.
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 fully documents both parameters (block_id format and format enum with usage guidance). The description adds no additional parameter information beyond what's in the schema, meeting the baseline expectation but not providing extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and target resource ('a block in Notion'), making the purpose immediately understandable. However, it doesn't differentiate this destructive operation from similar sibling tools like 'notion_update_block' or 'notion_retrieve_block', which would require explicit comparison to earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With sibling tools like 'notion_update_block' (for modification) and 'notion_retrieve_block' (for reading), there's no indication of when deletion is appropriate versus updating or simply retrieving information. This leaves the agent without contextual decision-making help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention whether this is a read-only operation (implied by 'retrieve' but not explicit), authentication requirements, rate limits, error conditions, or what the return structure looks like (especially problematic without an output 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 perfectly concise - a single, clear sentence that states exactly what the tool does with zero wasted words. It's front-loaded with the core purpose and contains no unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what a 'block' is in Notion's context, what data is returned, or how this differs from retrieving pages or databases. The agent must rely entirely on the parameter schema and guess about return values and behavioral characteristics.
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?
The description adds no parameter information beyond what's already in the input schema (which has 100% coverage). The schema thoroughly documents both parameters, including format requirements for block_id and detailed usage guidance for the format enum. The description doesn't compensate but doesn't need to given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Retrieve') and resource ('a block from Notion'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from sibling tools like 'notion_retrieve_page' or 'notion_retrieve_database', which also retrieve Notion resources but target different entity types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While the input schema's 'format' parameter description mentions when to use 'json' vs 'markdown', this doesn't address tool selection among siblings like 'notion_retrieve_page' (for pages) or 'notion_retrieve_block_children' (for child blocks).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states 'retrieve' implying a read operation, but doesn't clarify pagination behavior (implied by parameters), rate limits, authentication needs, or what happens with invalid block IDs. The description is minimal and leaves critical behavioral aspects undocumented.
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 a single, clear sentence that states the core purpose without unnecessary words. It's front-loaded with the essential action and target, making it immediately understandable. Every word earns its place with zero redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what 'children' means in the Notion context (nested blocks), doesn't mention the paginated nature of results, and provides no context about return format or error conditions. The description leaves too many gaps for effective tool use.
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%, providing complete parameter documentation. The description adds no parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('retrieve') and target ('children of a block'), making the purpose immediately understandable. It distinguishes from siblings like 'notion_retrieve_block' (which retrieves the block itself) and 'notion_append_block_children' (which modifies children). However, it doesn't explicitly mention that this is for reading nested content within a block, which would make it fully specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention scenarios like exploring page structure, accessing nested content, or comparing with 'notion_retrieve_page' for top-level content. Without any usage context, the agent must infer from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Retrieve' implies a read-only operation, but the description doesn't clarify authentication requirements, rate limits, error conditions, or what the response contains (e.g., page content, metadata). The format parameter description hints at behavioral differences between JSON and markdown outputs, but this is insufficient for a tool with no annotation coverage.
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 a single, clear sentence with zero wasted words. It's front-loaded with the core purpose ('Retrieve a page from Notion'), making it immediately understandable without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what a 'page' entails in Notion's context, what data is returned, or how this differs from other retrieval tools. For a tool with no structured behavioral hints, the description should provide more context about the operation's scope and results.
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 fully documents both parameters (page_id format, format enum with defaults and usage guidance). The description adds no additional parameter semantics beyond what's already in the schema, meeting the baseline score of 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('retrieve') and resource ('a page from Notion'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'notion_retrieve_block' or 'notion_retrieve_database', which also retrieve specific Notion resources, leaving some ambiguity about when to use this specific retrieval tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With multiple sibling retrieval tools (e.g., notion_retrieve_block, notion_retrieve_database, notion_retrieve_user), there's no indication of what makes a 'page' distinct or when this tool is preferred over others for retrieval operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions searching by title but doesn't cover key aspects like whether this is a read-only operation, potential rate limits, authentication needs, or what the output looks like (e.g., pagination details). This leaves significant gaps for a tool with 6 parameters.
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 extremely concise and front-loaded in a single sentence: 'Search pages or databases by title in Notion'. It wastes no words and directly states the core functionality without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, nested objects, no output schema, and no annotations), the description is insufficient. It doesn't explain behavioral traits, output format, or usage context, making it incomplete for effective agent use despite the concise structure.
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?
The description adds minimal parameter semantics beyond the schema, which has 100% coverage. It implies the 'query' parameter is for titles but doesn't elaborate on other parameters like 'filter', 'sort', or 'format'. With high schema coverage, the baseline is 3, as the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search pages or databases by title in Notion'. It specifies the action (search) and the target resources (pages or databases), though it doesn't explicitly differentiate from sibling tools like 'notion_query_database' or 'notion_retrieve_page', which is why it doesn't reach a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or specify contexts where this search tool is preferred over others like 'notion_query_database' or 'notion_retrieve_page', leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool updates properties, implying a mutation, but fails to mention critical aspects like required permissions, whether changes are reversible, rate limits, or what the response looks like (since there's no output schema). This leaves significant gaps in understanding the tool's behavior and risks.
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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to grasp quickly. Every part of the sentence contributes to understanding, with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a mutation tool with 3 parameters, no annotations, and no output schema, the description is insufficient. It doesn't cover behavioral risks, response format, or usage context, leaving the agent with incomplete information to safely and effectively invoke the tool. More detail is needed to compensate for the lack of structured data.
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 fully documents all parameters. The description adds no additional meaning beyond what's in the schema, such as examples of property formats or constraints. It merely restates the purpose without enhancing parameter understanding, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('properties of a page or an item in a Notion database'), making the purpose evident. However, it doesn't explicitly differentiate from siblings like 'notion_update_block' or 'notion_update_database', which also perform updates on different resources, leaving some ambiguity about when to choose this specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as 'notion_update_block' for block-level changes or 'notion_update_database' for database-level updates. It lacks context on prerequisites, like needing a page ID, and doesn't mention any exclusions or specific scenarios where this tool is preferred over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'retrieve' which implies a read-only operation, but doesn't clarify if this requires specific permissions, rate limits, or what the response looks like (e.g., structure, size limits). For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves beyond the basic action.
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 a single, clear sentence with zero wasted words. It's appropriately sized for a simple retrieval operation and front-loads the essential information ('retrieve a database').
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is minimally adequate but incomplete. It states what the tool does but lacks behavioral context, usage guidance, and output information. Without annotations or output schema, the agent must infer behavior from the description alone, which is insufficient for confident tool selection and invocation.
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 fully documents both parameters. The tool description adds no additional parameter information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'retrieve' and the resource 'a database in Notion', making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'notion_retrieve_page' or 'notion_query_database', which also retrieve Notion content but target different resources or operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it doesn't mention when to choose 'notion_retrieve_database' over 'notion_query_database' (which might retrieve filtered database items) or 'notion_retrieve_page' (for page content). The input schema's 'format' parameter description offers some usage hints, but the tool description itself lacks explicit when-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states this is a retrieval operation, implying it's read-only, but doesn't clarify authentication requirements (token-based), rate limits, error conditions, or response format details. For a tool with no annotation coverage, this leaves significant behavioral gaps.
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 a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple retrieval tool and front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete. It doesn't explain what the bot user data includes (e.g., ID, name, capabilities), how errors are handled, or authentication dependencies. For a tool that likely returns structured user data, more context is needed to use it effectively.
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 fully documents both parameters. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't explain why 'random_string' is required or provide context for the 'format' parameter). Baseline 3 is appropriate when the schema handles parameter documentation.
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 clearly states the specific action ('Retrieve') and resource ('the bot user associated with the current token in Notion'), distinguishing it from sibling tools like notion_retrieve_user (which retrieves any user) and notion_list_all_users (which lists all users). It precisely defines what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., token authentication), use cases (e.g., identifying the bot for permissions), or exclusions (e.g., not for retrieving human users). Without this context, the agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states it 'replaces the entire value for a given field,' which implies mutation. It doesn't disclose behavioral traits like required permissions, whether changes are reversible, rate limits, or what happens to unspecified fields. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. However, it could be slightly more structured by separating behavioral details, but it avoids unnecessary repetition and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a mutation tool with no annotations and no output schema, the description is minimally adequate but incomplete. It covers the basic action and parameter intent but lacks details on behavioral context, error handling, or return values, leaving gaps for an AI agent to infer safely.
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 parameters thoroughly. The description adds no additional meaning beyond implying block content must match type, which is partially covered in the schema. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update the content of a block') and resource ('a block in Notion'), specifying it's based on block type and replaces entire field values. It distinguishes from siblings like notion_append_block_children (adds children) and notion_delete_block (removes), but doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the description of replacing entire field values based on block type, suggesting it's for modifying existing blocks rather than creating new ones. However, it lacks explicit guidance on when to use this vs. alternatives like notion_update_page_properties or notion_retrieve_block, and doesn't mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses critical behavioral traits: the mutation nature ('Append'), key limits (max 100 blocks, 2 nesting levels, 2000 chars), and that it modifies a parent block. However, it doesn't mention error conditions, rate limits, or authentication requirements, leaving some gaps.
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 a single, front-loaded sentence that states the core purpose, followed by a concise list of limits. Every word earns its place with no redundancy or fluff, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is adequate but incomplete. It covers the core action and limits but lacks information on error handling, return values, or side effects. Given the complexity of the input schema, more guidance on block construction would be helpful.
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?
With 100% schema description coverage, the baseline is 3. The description adds minimal value beyond the schema—it repeats the limits already documented in the children parameter's description. It doesn't provide additional context about parameter interactions or usage examples.
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 clearly states the verb ('Append children blocks') and resource ('to a parent block'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like notion_retrieve_block_children (which reads) and notion_update_block (which modifies existing blocks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like notion_update_block or notion_create_page. It mentions limits but doesn't explain prerequisites, such as requiring write permissions or when appending is appropriate versus creating a new page. No explicit when/when-not statements are present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates critical constraints ('LIMITS: 100 blocks, 2 nesting levels, 2000 chars') that aren't evident from the schema alone. However, it doesn't mention authentication requirements, error conditions, or rate limits that would be valuable for a mutation tool.
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 perfectly concise - a single sentence that states the core purpose followed by critical constraints. Every word earns its place, and the information is front-loaded with no unnecessary elaboration. The bold formatting for 'LIMITS' effectively highlights the most important behavioral constraint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex mutation tool with no annotations and no output schema, the description is adequate but has clear gaps. It covers the basic purpose and critical constraints, but doesn't address error handling, response format expectations, or integration patterns with sibling tools. The schema richness compensates somewhat, but more behavioral context would be helpful.
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?
With 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions the parent relationship but doesn't provide additional context about parameter interactions or usage patterns. The baseline of 3 is appropriate when the schema does the heavy lifting.
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 clearly states the specific action ('Create a page'), the resource ('as child of page or database'), and distinguishes it from siblings by focusing on page creation rather than database operations or updates. It provides a complete verb+resource statement that is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'notion_create_database_item' or 'notion_update_page_properties'. It doesn't mention prerequisites, dependencies, or contextual factors that would help an agent choose between this and sibling tools for content creation scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating the permission requirement ('insert comment' capabilities) and the mutual exclusivity rule for parent/discussion_id. However, it doesn't mention potential side effects (e.g., notifications sent), rate limits, error conditions, or what the response looks like (since there's no output schema). For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
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 perfectly front-loaded and efficient: two sentences that cover purpose, prerequisites, and key usage constraint. Every word earns its place with zero redundancy. It's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with 4 parameters, nested objects, no annotations, no output schema), the description is incomplete. While it covers purpose, prerequisites, and a key parameter constraint well, it lacks information about the response format, error handling, and other behavioral aspects. The 100% schema coverage helps, but for a creation tool, more context about what happens after invocation would be valuable.
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?
The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds value by clarifying the parent/discussion_id exclusivity rule, which isn't captured in the schema. However, it doesn't provide additional semantic context beyond what's already in the parameter descriptions (e.g., explaining when to choose parent vs discussion_id). Given the high schema coverage, baseline 3 is appropriate.
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 clearly states the specific action ('Create a comment in Notion') and resource ('comment'), distinguishing it from sibling tools like notion_retrieve_comments (which reads comments) and other creation tools (which create pages, databases, etc.). It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.
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?
The description explicitly states when to use this tool ('Create a comment in Notion') and provides crucial exclusion guidance: 'You can either specify a page parent or a discussion_id, but not both.' It also mentions a prerequisite: 'This requires the integration to have 'insert comment' capabilities.' This gives clear context for when and how to invoke the tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates the read-only nature ('retrieve') and the permission requirement ('read comment capabilities'), which are crucial for a tool accessing external data. However, it doesn't mention potential rate limits, pagination behavior (implied by start_cursor but not explained), error conditions, or what 'unresolved' means operationally.
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 two sentences that are front-loaded with the core purpose and followed by a critical prerequisite. Every word earns its place—no redundancy, no fluff. It's appropriately sized for a tool with clear parameters and no complex behavioral nuances needing extensive explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is moderately complete. It covers the purpose, scope, and a key prerequisite, but lacks details on return format (only implied by the 'format' parameter), pagination mechanics, error handling, or the definition of 'unresolved'. For a tool with 4 parameters and external API dependencies, more behavioral context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/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 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. However, with 4 parameters (one required), the baseline is 3, and the description's clarity about the tool's purpose indirectly helps contextualize why these parameters matter, earning a slightly higher score.
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 clearly states the specific action ('Retrieve a list of unresolved comments') and target resource ('from a Notion page or block'), distinguishing it from sibling tools like notion_create_comment (which creates comments) and notion_retrieve_block (which retrieves block content rather than comments). The verb 'retrieve' is precise and the scope 'unresolved comments' is well-defined.
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?
The description provides clear context for when to use this tool ('Requires the integration to have "read comment" capabilities'), establishing a prerequisite. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools (e.g., notion_create_comment for creating comments or notion_retrieve_block for retrieving block content).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a read operation (implied by 'List'), requires specific permissions (Enterprise plan and Organization API key), and warns about potential errors. It doesn't mention rate limits or pagination behavior, but covers essential access constraints.
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?
Two sentences with zero waste: the first states the purpose, the second provides critical usage guidance. The description is appropriately sized and front-loaded with the core functionality.
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 read operation with no output schema, the description provides good context about plan requirements and API key constraints. It could be more complete by mentioning pagination behavior (implied by parameters but not explicitly stated) or typical response structure, but covers the most critical contextual information.
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%, providing complete parameter documentation. The description adds no parameter-specific information beyond what's in the schema, so it meets the baseline of 3. It doesn't compensate for any gaps because there are none in the schema.
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 clearly states the specific action ('List all users') and resource ('in the Notion workspace'), distinguishing it from sibling tools like 'notion_retrieve_user' (singular) and 'notion_search' (general search). It provides a complete, unambiguous purpose statement.
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?
The description explicitly states when to use this tool (to list all users) and includes a critical prerequisite about plan requirements and API key type. However, it doesn't explicitly contrast when to use this versus alternatives like 'notion_retrieve_user' for single users or 'notion_search' for filtered results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively adds critical context beyond what the input schema provides: it specifies that this function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors. This is valuable information about authentication requirements and potential limitations. However, it does not describe the return format or error handling in detail.
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 appropriately sized and front-loaded: the first sentence states the core purpose, and the second sentence provides crucial additional context. Every sentence earns its place by adding essential information without redundancy or unnecessary elaboration.
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?
Given the complexity (a read operation with specific requirements) and the absence of annotations and output schema, the description is mostly complete. It covers the purpose, prerequisites, and key behavioral constraints. However, it does not describe the return values or potential error scenarios, which would be helpful for an agent to understand what to expect from the tool invocation.
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 both parameters (user_id and format) comprehensively. The description does not add any additional meaning or clarification about the parameters beyond what is in the schema. According to the rules, when schema coverage is high (>80%), the baseline score is 3 even with no parameter info in the description.
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 clearly states the specific action ('Retrieve a specific user') and resource ('by user_id in Notion'), distinguishing it from sibling tools like notion_list_all_users (which lists all users) and notion_retrieve_bot_user (which retrieves a bot user). The verb 'retrieve' is precise and differentiates from creation or update operations.
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?
The description provides explicit context for when to use this tool (to retrieve a specific user by ID) and includes important prerequisites (Notion Enterprise plan and Organization API key). However, it does not explicitly state when NOT to use it or name specific alternatives among the sibling tools, such as notion_list_all_users for listing users instead of retrieving a specific one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-notion-server MCP server](https://glama.ai/mcp/servers/SunCreation/mcp-notion-server/badges/card.svg)](https://glama.ai/mcp/servers/SunCreation/mcp-notion-server)

Score Badge

Copy to your README.md:

[![mcp-notion-server MCP server](https://glama.ai/mcp/servers/SunCreation/mcp-notion-server/badges/score.svg)](https://glama.ai/mcp/servers/SunCreation/mcp-notion-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SunCreation/mcp-notion-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server