Notion MCP Server

Overview Schema Related Servers Score Discussions

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes targeting specific Notion resources like blocks, pages, databases, comments, and users, with clear action verbs. However, 'API-retrieve-a-block' and 'API-get-block-children' could be slightly confusing as both involve blocks, though one fetches a single block and the other its children.
Naming Consistency4/5
Tool names follow a consistent 'API-verb-a-noun' pattern with minor deviations like 'API-get-users' (plural) and 'API-post-database-query' (includes 'query'). The pattern is mostly uniform, making tools predictable and readable, though not perfectly standardized.
Tool Count4/5
With 19 tools, the count is slightly high but reasonable for Notion's broad API scope covering blocks, pages, databases, comments, and users. It provides comprehensive coverage without being overwhelming, though it borders on the heavy side.
Completeness5/5
The tool set offers complete CRUD and lifecycle coverage for Notion's core resources: create, retrieve, update, and delete operations for blocks, pages, databases, and comments, plus user management and search. No obvious gaps exist for typical agent workflows in this domain.
Average 2.8/5 across 19 of 19 tools scored. Lowest: 2.2/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 the full burden of behavioral disclosure but provides almost none. 'Update a database' implies a mutation operation, but the description doesn't mention permission requirements, whether changes are reversible, rate limits, or what happens when only partial parameters are provided. The description fails to disclose critical behavioral traits needed for an agent to use this tool safely and effectively.
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 extremely concise at just three words, which could be appropriate if it were more informative. However, this brevity comes at the cost of being under-specified rather than efficiently informative. The structure is simple but lacks the front-loaded essential information that would help an agent understand the tool's purpose and usage context.
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 mutation tool with 4 parameters (including complex nested objects), no annotations, and no output schema, the description is severely inadequate. It doesn't explain what 'updating a database' entails, what fields can be modified, what the expected outcome is, or how this differs from other update operations in the sibling tool set. The description fails to provide the contextual information needed for an agent to use this tool 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?
The schema description coverage is 100%, so the schema already documents all four parameters thoroughly. The description adds no parameter information beyond what's in the schema - it doesn't explain the relationship between parameters, provide examples of valid values, or clarify edge cases. With complete schema documentation, the baseline score of 3 is appropriate as the description doesn't add value but doesn't detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose2/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Notion | Update a database' is essentially a tautology that restates the tool name 'API-update-a-database' with minimal added value. It specifies the verb 'Update' and resource 'database' but lacks specificity about what aspects can be updated or how it differs from sibling tools like 'API-patch-block-children' or 'API-update-a-block'. The description doesn't provide meaningful differentiation from related operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides zero guidance on when to use this tool versus alternatives. There are multiple sibling tools that modify Notion content (API-patch-block-children, API-patch-page, API-update-a-block), but the description offers no context about when this specific database update tool is appropriate versus those other modification tools. No prerequisites, constraints, or comparison information is included.
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 full burden. It mentions 'Create a database' which implies a write operation, but lacks details on permissions, side effects (e.g., if it modifies existing data), rate limits, or response format. This is inadequate for a mutation tool with no structured safety hints.
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 with 'Notion | Create a database', which is front-loaded and wastes no words. However, this brevity contributes to underspecification rather than clarity, but strictly on conciseness, it scores high.
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 (3 parameters with nested objects, no output schema, and no annotations), the description is incomplete. It doesn't address behavioral traits, parameter meanings, or usage context, making it insufficient for an agent to reliably invoke this mutation tool in Notion's ecosystem.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 33%, with only the 'properties' parameter documented in the schema. The description adds no parameter information beyond the tool name, failing to compensate for the coverage gap. It doesn't explain what 'parent', 'properties', or 'title' mean in context, leaving key inputs ambiguous.
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 'Notion | Create a database' states the action (create) and resource (database) but is vague about scope and lacks specificity. It doesn't differentiate from sibling tools like 'API-retrieve-a-database' or 'API-update-a-database', nor does it clarify what type of database is being created (e.g., in Notion's context).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/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. With siblings like 'API-retrieve-a-database', 'API-update-a-database', and 'API-post-database-query', the description offers no context on use cases, prerequisites, or exclusions, leaving the agent to guess.
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, the description carries full burden but provides minimal behavioral insight. It doesn't disclose if this is a read-only operation, requires authentication, has rate limits, or what the response format includes (e.g., pagination details). The term 'Query' suggests non-destructive reads, but this isn't explicitly confirmed, missing key context for safe usage.
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 extremely concise with 'Notion | Query a database', which is front-loaded and wastes no words. However, it may be overly terse, risking under-specification for a complex tool with 8 parameters, though it efficiently states the core action and platform.
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 (8 parameters, nested objects, no output schema, and no annotations), the description is incomplete. It doesn't explain return values, error conditions, or behavioral traits, leaving significant gaps for an AI agent to infer usage. Without annotations or output schema, more detail is needed to ensure proper 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 75%, providing good documentation for most parameters like database_id, filter, and page_size. The description adds no additional parameter semantics beyond the schema, but with high coverage, the baseline is 3. It doesn't compensate for gaps in parameters like archived or in_trash, which lack descriptions in both schema and tool description.
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 'Notion | Query a database' states the platform and resource but is vague about the action—'Query' could mean search, filter, or retrieve, and it doesn't specify if this is for listing, filtering, or paginating database entries. It distinguishes from siblings like API-create-a-database or API-retrieve-a-database by implying read operations, but lacks clarity on exact functionality compared to API-post-search.
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 explicit guidance on when to use this tool versus alternatives is provided. The description doesn't mention when to choose this over API-post-search for broader searches or API-retrieve-a-database for metadata. Usage is implied through the name and parameters but not stated, leaving gaps for agent decision-making.
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 only states 'Retrieve a page', which implies a read-only operation but does not detail aspects like authentication needs, rate limits, error handling, or what the retrieval includes (e.g., full content vs. metadata). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with 'Notion | Retrieve a page', which is front-loaded and wastes no words. However, it is overly brief, bordering on under-specification, as it could benefit from slightly more detail without losing efficiency, but it remains structurally sound.
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 retrieval tool with no annotations and no output schema, the description is incomplete. It fails to explain what is returned (e.g., page data, properties), any limitations, or behavioral traits, leaving significant gaps for the agent to understand the tool's full context and usage.
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 semantics beyond the input schema, which has 100% coverage with detailed descriptions for both parameters. Since schema_description_coverage is high, the baseline score is 3, as the description does not compensate but also does not detract from the schema's documentation.
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 'Notion | Retrieve a page' states the verb 'Retrieve' and resource 'page', which clarifies the basic action. However, it lacks specificity about what 'retrieve' entails (e.g., fetching metadata, content, or properties) and does not distinguish it from sibling tools like 'API-retrieve-a-block' or 'API-retrieve-a-database', making it vague in comparison.
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 does not mention scenarios for usage, prerequisites, or exclusions, nor does it reference sibling tools such as 'API-post-search' for broader queries or 'API-retrieve-a-block' for specific content, leaving the agent without contextual 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?
No annotations are provided, so the description carries full burden. 'Create comment' implies a write operation, but it doesn't disclose behavioral traits like authentication needs, rate limits, error conditions, or what happens on success. For a mutation tool 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 extremely concise with just three words, front-loaded with the service name and action. There's zero waste or redundancy, making it efficient for quick scanning, though this brevity contributes to gaps in other dimensions.
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 a mutation tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain the tool's behavior, return values, or error handling. For a create operation in Notion, 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 50% (one of two parameters has a description). The description adds no parameter information beyond the schema. With low coverage, the description doesn't compensate by explaining 'parent' or 'rich_text' semantics. Baseline 3 is appropriate as the schema provides some documentation, but the description adds no value.
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 'Notion | Create comment' states the action (create) and resource (comment) but is vague about scope and lacks specificity. It doesn't distinguish this from sibling tools like 'API-retrieve-a-comment' or explain what a 'comment' means in Notion context. The purpose is clear at a basic level but lacks detail.
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 on when to use this tool versus alternatives is provided. The description doesn't mention prerequisites, when to choose this over other comment-related tools, or contextual constraints. With siblings like 'API-retrieve-a-comment', the lack of differentiation leaves usage unclear.
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 'Delete a block' which implies a destructive mutation, but it doesn't specify if deletion is permanent, requires permissions, has side effects (e.g., on children blocks), or includes confirmation steps. This leaves significant gaps 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 'Notion | Delete a block' is extremely concise and front-loaded, with no wasted words. It efficiently conveys the core action and resource in a minimal format.
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 this is a destructive mutation tool with no annotations and no output schema, the description is incomplete. It lacks critical details like behavioral traits (e.g., irreversibility, permissions), usage context, and expected outcomes, making it inadequate for safe and effective 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%, with the parameter 'block_id' documented as 'Identifier for a Notion block'. The description adds no additional meaning beyond this, such as format examples or constraints. Baseline 3 is appropriate since the schema handles parameter documentation adequately.
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 'Notion | Delete a block' states the action (delete) and resource (a block), but it's vague about scope (e.g., whether it's permanent or reversible) and doesn't distinguish from siblings like 'API-update-a-block' or 'API-retrieve-a-block'. It provides a basic purpose but lacks specificity.
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 given on when to use this tool versus alternatives (e.g., 'API-update-a-block' for modifications or 'API-retrieve-a-block' for viewing). The description implies deletion but offers no context on prerequisites, exclusions, or typical use cases.
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, the description carries full burden but only states 'Retrieve', implying a read-only operation without details on permissions, rate limits, pagination behavior, or error handling. It lacks behavioral context 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 extremely concise with just two words plus a separator, front-loaded and zero waste. Every element ('Notion', 'Retrieve block children') is essential, making it efficiently structured.
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 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what 'block children' returns, how pagination works, or behavioral traits, leaving significant gaps for agent understanding.
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 parameters. The description adds no meaning beyond the schema, providing no extra context on parameter usage or relationships. Baseline 3 is appropriate as the schema does the work.
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 'Notion | Retrieve block children' states the action ('Retrieve') and resource ('block children'), but is vague about what 'block children' means and doesn't differentiate from siblings like 'API-retrieve-a-block' or 'API-retrieve-a-page'. It lacks specificity about scope or content.
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. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone among many sibling tools.
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 'lists all users' without disclosing behavioral traits like pagination behavior (implied by parameters but not explained), authentication requirements, rate limits, or what 'all users' encompasses. It mentions Notion context but adds minimal operational insight.
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 with just three words, front-loaded with the platform (Notion) and action. There's zero wasted text, making it efficient for quick scanning.
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 2 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain the return format, pagination behavior, or scope of 'users,' leaving gaps that could hinder correct agent invocation 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?
Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds no additional meaning about parameters beyond implying a list operation. Baseline 3 is appropriate as the schema handles parameter documentation adequately.
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 'Notion | List all users' states the resource (users) and verb (list) but lacks specificity about scope or differentiation from sibling tools. It doesn't clarify if this lists workspace members, database users, or all accessible users, and doesn't distinguish itself from 'API-get-user' (singular) or 'API-get-self'.
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 'API-get-user' (singular user) or 'API-get-self' (current user). There's no mention of prerequisites, context, or exclusions for usage.
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. 'Search by title' implies a read-only operation, but doesn't specify pagination behavior (though the schema covers this), rate limits, authentication requirements, or what happens with no results. It mentions Notion platform but doesn't clarify API constraints or error conditions. The description adds minimal behavioral context beyond what's implied by 'search'.
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 extremely concise at just 4 words ('Notion | Search by title'), which is appropriately brief. It's front-loaded with the essential action. However, it could be more structured by explicitly mentioning the resource scope (pages and databases) to improve clarity without sacrificing conciseness.
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 5 parameters with 100% schema coverage but no annotations and no output schema, the description is minimally adequate. It identifies the platform and action but lacks details about the search scope, result format, or behavioral constraints. For a search tool with multiple parameters and no output schema, the description should ideally mention what kind of results to expect (e.g., 'returns matching pages and databases') to be more complete.
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 all 5 parameters with detailed descriptions. The description 'Search by title' only hints at the 'query' parameter's purpose (searching titles) but doesn't add any meaningful semantic context beyond what the schema provides. No parameter details are explained in the description itself, 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Notion | Search by title' states the platform (Notion) and the action (search), but it's vague about scope and resource. It mentions 'by title' which suggests searching page/database titles, but doesn't specify that it searches both pages and databases or that it's a general search tool. It doesn't clearly distinguish from sibling tools like 'API-post-database-query' which might also involve searching.
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. There's no mention of when this search tool is appropriate versus other search or query tools in the sibling list (like 'API-post-database-query'), nor any context about prerequisites or limitations. 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 for behavioral disclosure. 'Retrieve' implies a read operation, but the description doesn't specify authentication requirements, rate limits, error conditions, or what data is returned. For a tool with zero annotation coverage, this leaves significant behavioral gaps unaddressed.
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 three words. It's front-loaded with the platform name, followed by the action and resource. There's zero wasted language, though this conciseness comes at the cost of completeness.
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 purpose (retrieving user data), the absence of annotations, 0% schema coverage, and no output schema, the description is inadequate. It doesn't explain what user data is returned, how to obtain user IDs, authentication requirements, or how this differs from sibling tools. For a retrieval operation in a platform like Notion, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the single parameter 'user_id' is completely undocumented in the schema. The description provides no information about this parameter - what format it should be in, where to find user IDs, or what constitutes a valid user_id. The description fails to compensate for the schema's lack of documentation.
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 resource ('a user'), and specifies the platform ('Notion'). However, it doesn't distinguish this tool from its sibling 'API-get-users', which appears to retrieve multiple users. The description is specific but lacks sibling 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. With siblings like 'API-get-users' (plural) and 'API-get-self' (likely for current user), there's no indication of when this single-user retrieval is appropriate versus those other options. No prerequisites or exclusions are mentioned.
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 offers minimal behavioral insight. It states 'Append' which implies a write/mutation operation, but doesn't disclose permissions needed, rate limits, idempotency, or what happens on failure. For a mutation tool with zero annotation coverage, this is inadequate.
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 with just three words, front-loading the key information ('Notion | Append block children'). There's no wasted verbiage, making it efficient for quick scanning.
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 mutation tool with 3 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or important behavioral aspects like whether appending is additive or has side effects. The context demands more completeness.
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 detailed documentation for all parameters (block_id, children, after). The description adds no additional parameter semantics beyond what's in the schema, so it meets the baseline of 3 where 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 action ('Append') and resource ('block children') with platform context ('Notion'), making the purpose understandable. It doesn't explicitly distinguish from siblings like 'API-update-a-block' or 'API-get-block-children', but the verb 'Append' suggests a specific type of modification rather than full replacement or retrieval.
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 like 'API-update-a-block' (which might replace content) or 'API-get-block-children' (which retrieves). The description implies appending children to blocks, but lacks explicit context about use cases or prerequisites.
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 page properties' implies a write/mutation operation, but it doesn't disclose important traits: whether this requires specific permissions, if changes are reversible, what happens to unspecified properties, rate limits, or error conditions. The description adds no behavioral context beyond the basic action implied by 'Update'.
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 4 words ('Notion | Update page properties'). It's front-loaded with the essential action and context, with zero wasted words. Every element (platform, action, resource) earns its place, making it easy for an agent to parse quickly.
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 mutation tool with 6 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what constitutes successful completion, what gets returned (if anything), error scenarios, or the scope of 'page properties' updates. The high schema coverage helps, but for a write operation with complex nested parameters, more contextual guidance is needed.
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 high at 83%, providing good documentation for most parameters. The description adds no parameter-specific information beyond what's in the schema - it doesn't explain what 'page properties' encompasses or provide examples of property updates. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't add meaningful semantic value beyond the 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 ('Update') and resource ('page properties') with the Notion context. It distinguishes from siblings like API-create-a-database or API-post-page by focusing on updating existing pages rather than creating new ones. However, it doesn't explicitly differentiate from API-update-a-block or API-update-a-database which also perform updates on different resources.
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 when to choose this over API-update-a-block (for block-level updates) or API-retrieve-a-page (for read-only access), nor does it specify prerequisites like needing a valid page_id. The agent must infer usage from the name and schema 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 the full burden of behavioral disclosure but only states the basic action ('Create a page'). It doesn't mention authentication requirements, rate limits, error handling, or what happens upon creation (e.g., returns a page object). For a mutation tool 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 extremely concise ('Notion | Create a page') and front-loaded with essential information. Every word earns its place, with no wasted text or redundancy, making it efficient for quick understanding.
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 mutation tool with 5 parameters, nested objects, no annotations, and no output schema, the description is incomplete. It lacks behavioral context (e.g., side effects, return values), parameter guidance, and differentiation from siblings, leaving significant gaps for an AI agent to invoke it correctly in a complex environment.
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 in the schema, which has 60% coverage. With 5 parameters (2 required) and nested objects, the schema does moderate lifting, but the description doesn't compensate for the 40% coverage gap or clarify usage semantics (e.g., how 'parent' relates to Notion's hierarchy). Baseline 3 is appropriate given schema coverage >50% but no added value from 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 action ('Create a page') and the target resource ('Notion'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'API-create-a-database' or 'API-patch-page' beyond the basic resource type, missing explicit sibling distinction.
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 like 'API-patch-page' (for updates) or 'API-create-a-database'. The description lacks context about prerequisites, appropriate scenarios, or exclusions, leaving usage decisions to inference 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic action ('Retrieve') without mentioning any behavioral traits such as permissions needed, rate limits, error handling, or what the return format looks like. This is inadequate 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 extremely concise with just three words ('Notion | Retrieve a block'), front-loaded with the key information. There is no wasted text, making it efficient and easy 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?
Given the lack of annotations and output schema, the description is incomplete. It doesn't provide enough context for an AI agent to understand how to use this tool effectively, such as what the retrieved block data includes or any usage constraints. This is a significant gap for a retrieval tool.
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 semantics beyond what the input schema provides. Since schema description coverage is 100% (the 'block_id' parameter is fully described in the schema), the baseline score is 3. The description doesn't compensate with additional context about the parameter.
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 resource ('a block') with the context ('Notion'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from similar siblings like 'API-retrieve-a-database' or 'API-retrieve-a-page', which follow the same pattern for different resources.
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 when this retrieval is appropriate compared to other retrieval tools (e.g., for blocks vs. pages) or when other tools might be better suited (e.g., 'API-get-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?
No annotations are provided, so the description carries the full burden. It states 'Retrieve comments' but lacks behavioral details such as authentication requirements, rate limits, pagination behavior (implied by parameters but not described), error handling, or what the response contains. This is inadequate for a tool with parameters and no 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 extremely concise ('Notion | Retrieve comments'), with no wasted words. It's front-loaded with the essential action and resource, making it easy to scan. Every part earns its place by specifying the platform and tool purpose.
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 has 3 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain the retrieval process, response format, or usage context, leaving significant gaps for an AI agent to understand how to invoke it effectively beyond basic parameter input.
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 parameters like 'block_id', 'page_size', and 'start_cursor'. The description adds no additional meaning beyond the schema, such as explaining comment retrieval context or parameter interactions. Baseline 3 is appropriate as the schema handles 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 ('Retrieve') and resource ('comments'), specifying it's for Notion. It distinguishes from siblings like 'API-retrieve-a-block' or 'API-retrieve-a-page' by focusing on comments, but doesn't explicitly differentiate from other comment-related tools like 'API-create-a-comment' beyond the verb.
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., needing a block ID), exclusions, or compare it to similar tools like 'API-retrieve-a-block' for general block data or 'API-create-a-comment' for adding comments.
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 the basic action without disclosing behavioral traits. It doesn't mention whether this is a read-only operation, authentication requirements, rate limits, error handling, or what the retrieval includes (e.g., metadata, properties). For a tool with zero annotation coverage, this is inadequate.
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 with just three words, front-loading the essential information ('Notion | Retrieve a database') with zero wasted words. Every element earns its place by specifying platform, action, and resource.
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 for a retrieval tool. It doesn't explain what is returned (e.g., database structure, properties), potential errors, or usage constraints, leaving significant gaps for an AI agent to understand how 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?
The description adds no parameter information beyond what's in the schema, which has 100% coverage with a clear description for 'database_id'. Since schema_description_coverage is high, the baseline score of 3 is appropriate as the schema does the heavy lifting without additional value from 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 action ('Retrieve') and resource ('a database') with platform context ('Notion'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'API-retrieve-a-block' or 'API-retrieve-a-page' beyond the resource type, missing explicit sibling distinction.
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 'API-post-database-query' for querying database contents or 'API-retrieve-a-page' for retrieving pages. The description offers no context about use cases, prerequisites, 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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Retrieve' which implies a read-only operation, but doesn't clarify if it's safe, idempotent, or has side effects. It also doesn't mention pagination behavior (implied by page_size and start_cursor parameters) or rate limits. For a tool with 4 parameters and no 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 extremely concise—a single phrase with zero waste. It's front-loaded with the key action and resource, making it easy to parse. Every word ('Notion', 'Retrieve', 'a page property item') earns its place by specifying the context and purpose without 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 (4 parameters, no output schema, no annotations), the description is incomplete. It doesn't explain what a 'page property item' entails, the return format, or error conditions. While the schema covers parameters, the lack of behavioral context and output details leaves gaps for the agent to understand how to use this tool effectively in practice.
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 (page_id, page_size, property_id, start_cursor) with clear descriptions. The description adds no additional parameter semantics beyond what's in the schema, such as format examples or constraints. Baseline 3 is appropriate when the schema does the heavy lifting, but the description doesn't compensate with extra insights.
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 ('a page property item'), and specifies the platform ('Notion'). It distinguishes this as a retrieval operation rather than creation or update, which helps differentiate from siblings like API-create-a-database or API-patch-page. However, it doesn't explicitly contrast with similar retrieval tools like API-retrieve-a-page or API-retrieve-a-database, which would have made it 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. It doesn't mention prerequisites (e.g., needing a valid page_id and property_id), nor does it compare to siblings like API-retrieve-a-page (which might retrieve entire pages) or API-post-search (which might search for properties). Without any usage context, the agent must infer based on 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. 'Update a block' implies a mutation operation, but the description fails to mention that it can archive/unarchive blocks, handle specific block types (e.g., text, to_do), or discuss potential side effects like permissions or rate limits, which are critical for safe use.
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 'Notion | Update a block' is extremely concise and front-loaded, with no wasted words. It efficiently communicates the core purpose in a minimal format, making it easy for an agent to parse quickly.
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 updating blocks (with nested objects and archiving functionality), no annotations, and no output schema, the description is incomplete. It should provide more context on behavioral aspects, return values, or error handling to adequately guide the agent, especially for a mutation tool with potential side effects.
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 input schema has 100% description coverage, so the schema fully documents parameters like block_id, archived, and type. The description adds no additional meaning beyond the schema, such as explaining parameter interactions or use cases, but this is acceptable given the high schema coverage, resulting in a baseline score of 3.
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 'Notion | Update a block' clearly states the action (update) and resource (a block in Notion), distinguishing it from siblings like API-create-a-database or API-delete-a-block. However, it lacks specificity about what aspects of a block can be updated, which could differentiate it more precisely from similar tools like API-patch-block-children.
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 does not mention prerequisites, such as needing a block_id, or compare it to siblings like API-patch-block-children or API-retrieve-a-block, leaving the agent without context for 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?
No annotations are provided, so the description carries full burden. It states 'Retrieve', implying a read operation, but doesn't disclose behavioral traits such as authentication requirements, rate limits, error conditions, or what the return data includes. This is inadequate for a tool with zero 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, efficient sentence that front-loads the key action ('Retrieve') and resource. There is no wasted text, making it highly concise and well-structured for quick understanding.
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 the retrieved bot user data includes, potential use cases, or how it differs from other user-related tools. For a tool in a rich API context with many siblings, more contextual detail is needed.
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?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description adds no parameter information, which is acceptable here since there are no parameters to explain. A baseline of 4 is appropriate as it doesn't need to compensate for any gaps.
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 'your token's bot user', which is specific and meaningful. However, it doesn't explicitly differentiate from sibling tools like 'API-get-user' or 'API-get-users', which likely retrieve other user types, 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. With siblings like 'API-get-user' and 'API-get-users', it's unclear if this is for self-retrieval only, authentication checks, or other contexts. No exclusions or prerequisites are mentioned.
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:

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

Score Badge

Copy to your README.md:

[![notion-mcp-server MCP server](https://glama.ai/mcp/servers/gendosu/notion-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/gendosu/notion-mcp-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/gendosu/notion-mcp-server'

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