Server Quality Checklist

Tool Scores

• notion_query_databaseC
  2.7/5.0
  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 action without behavioral details. It doesn't disclose whether this is a read-only operation, potential rate limits, authentication needs, pagination behavior, or error handling, leaving critical operational context unspecified.

  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 waste—it directly states the tool's function without unnecessary words. It's appropriately sized and front-loaded, making it easy 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 tool's complexity (6 parameters with nested objects, no output schema, and no annotations), the description is incomplete. It fails to explain the tool's behavior, output format, or interaction with sibling tools, leaving gaps that could hinder an AI agent's ability to use it effectively in context.

  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 well-documented in the schema itself. The description adds no additional meaning beyond the schema, such as explaining the purpose of 'filter' or 'sorts' in practical terms, but the schema provides sufficient detail, meeting the baseline for high 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 'Query a database in Notion' states the basic action and resource but is vague about scope and functionality. It doesn't specify what querying entails (e.g., retrieving filtered/sorted records) or distinguish it from sibling tools like 'notion_retrieve_database' or 'notion_search', leaving ambiguity about when to use each.

  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. The description lacks context about prerequisites, typical use cases, or comparisons to siblings like 'notion_retrieve_database' (which might fetch metadata) or 'notion_search' (which searches across workspaces), offering no help in tool selection.

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

• notion_retrieve_blockC
  2.7/5.0
  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 the action ('retrieve') but does not describe traits like authentication requirements, rate limits, error handling, or what the return value looks like (e.g., structure, pagination). For a read operation with no annotation coverage, this leaves significant gaps in understanding how the tool behaves.

  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 no wasted words. It is appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration. Every part of the sentence earns its place by conveying the essential action.

  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 retrieving a block (with parameters like format options) and no output schema or annotations, the description is incomplete. It lacks details on return values, error cases, or behavioral context, which are crucial for effective tool use. The description does not compensate for the absence of structured data, leaving gaps in 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?

  The input schema has 100% description coverage, detailing both parameters ('block_id' and 'format') with enums and defaults. The description does not add any meaning beyond what the schema provides, such as explaining parameter interactions or use cases. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the heavy lifting without extra value from the 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 states the verb ('retrieve') and resource ('a block from Notion'), which clarifies the basic action. However, it does not differentiate this tool from sibling tools like 'notion_retrieve_page' or 'notion_retrieve_database', leaving ambiguity about what specific type of content is being retrieved. It is vague in distinguishing the scope from other retrieval tools.

  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 sibling tools like 'notion_retrieve_page' or 'notion_retrieve_database', nor does it explain prerequisites such as needing a valid block ID. Usage is implied only through the tool name and parameters, with no explicit context or exclusions provided.

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

• notion_update_databaseC
  2.7/5.0
  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. 'Update a database in Notion' implies a mutation operation but provides no information about permissions required, whether changes are reversible, rate limits, error conditions, or what happens to existing database properties not mentioned in the update. For a complex mutation tool with 5 parameters and nested objects, this is 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 extremely concise at just 5 words: 'Update a database in Notion.' It's front-loaded with the core action and resource, with zero wasted words. While it may be too brief for adequate completeness, as a standalone statement it's perfectly structured and efficient.

  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 (5 parameters with nested objects, no annotations, no output schema), the description is inadequate. A database update tool in Notion involves significant complexity with rich text objects, property schemas, and format options. The single-sentence description fails to provide necessary context about what can be updated, how updates affect existing data, or what the tool returns. For a mutation tool of this complexity, more 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 100%, so the input schema already documents all 5 parameters thoroughly with detailed descriptions of database_id, title, description, properties, and format. The description adds no 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.

  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' clearly states the verb ('Update') and resource ('database in Notion'), making the basic purpose understandable. However, it's quite generic and doesn't differentiate from sibling tools like notion_update_block or notion_update_page_properties, which also perform updates on different Notion resources. It lacks specificity about what aspects of a database can be updated.

  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 are multiple sibling update tools (notion_update_block, notion_update_page_properties) and related tools like notion_retrieve_database, but the description offers no context about when this specific database update tool is appropriate versus those others. 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.

• notion_create_databaseC
  2.9/5.0
  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 offers minimal information. It states 'Create' which implies a write/mutation operation, but doesn't mention required permissions, whether the operation is idempotent, rate limits, error conditions, or what happens on success (e.g., returns database ID). 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 a single, efficient sentence with zero wasted words. It's appropriately front-loaded with the core purpose. Every word earns its place, making it easy for an agent to parse quickly while scanning available tools.

  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 mutation tool (database creation) with no annotations, no output schema, and complex nested parameters, the description is insufficient. It doesn't explain what happens after creation (return value), error handling, authentication requirements, or provide context about the Notion database model. The agent would need to rely heavily on the input schema alone, which is inadequate for safe operation.

  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 comprehensively documents all 4 parameters (parent, title, properties, format) with detailed descriptions and constraints. The description adds no additional parameter information beyond what's in the schema, which is acceptable given the high schema coverage but doesn't provide any helpful context about how parameters interact or typical usage patterns.

  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') and resource ('database in Notion'), making the purpose immediately understandable. It distinguishes from siblings like 'notion_create_database_item' (which creates items within databases) and 'notion_update_database' (which modifies existing databases), though it doesn't explicitly mention these distinctions in the description text itself.

  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 parent page), compare with similar tools like 'notion_update_database' for modifications, or indicate when database creation is appropriate versus using existing databases. The agent must infer usage 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.

• notion_create_database_itemC
  2.9/5.0
  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 it creates a new item, implying a write operation, but doesn't cover permissions required, rate limits, error conditions, or what the response looks like (since no output schema exists). 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 is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, 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 no annotations and no output schema, the description is incomplete. It lacks behavioral details (e.g., auth needs, side effects), usage context, and output information, leaving the agent under-informed despite the clear purpose and 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 the schema fully documents all parameters. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't explain property mapping or format implications further), 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 ('Create a new item') and resource ('in a Notion database'), specifying it creates a page. It distinguishes from siblings like notion_create_database (creates databases) and notion_update_page_properties (modifies existing pages), though it doesn't explicitly name these alternatives.

  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 (e.g., needing a database ID), exclusions, or compare with similar tools like notion_create_database or notion_update_page_properties, leaving the agent to infer usage context.

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

• notion_delete_blockC
  2.9/5.0
  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. While 'Delete' clearly indicates a destructive operation, the description doesn't mention important behavioral aspects: whether deletion is permanent or reversible, what permissions are required, whether child blocks are also deleted, or what happens to the response. The format parameter description adds some behavioral context about output formats, but doesn't compensate for the core 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 concise at just 5 words, front-loading the core purpose without unnecessary elaboration. Every word earns its place, and there's no wasted text. The structure is straightforward and immediately communicates the essential action.

  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 operation with no annotations and no output schema, the description is insufficiently complete. It doesn't address critical contextual information: what happens after deletion (confirmation? error handling?), whether the operation is idempotent, what permissions are needed, or what the response contains. The format parameter adds some context but doesn't compensate for the broader gaps in understanding this mutation tool's 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?

  With 100% schema description coverage, the schema already documents both parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema. The baseline score of 3 reflects adequate parameter documentation through the schema alone, though the description doesn't enhance understanding of when or why to use specific parameter values.

  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 resource ('a block in Notion'), making the purpose immediately understandable. However, it doesn't differentiate this destructive operation from sibling tools like notion_update_block or notion_retrieve_block, which would help the agent understand the tool's specific role in the Notion API ecosystem.

  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 (which can modify blocks) and notion_retrieve_block (which reads blocks), there's no indication of when deletion is appropriate versus modification or retrieval. The format parameter description offers some usage guidance for that specific parameter, but not for the tool as a whole.

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

• notion_retrieve_block_childrenC
  2.9/5.0
  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. While 'retrieve' implies a read operation, the description doesn't mention important behavioral aspects like pagination behavior (implied by parameters but not explained), rate limits, authentication requirements, or what happens with invalid block IDs. The description is too minimal for a tool with 4 parameters and 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 at just 5 words, making it easy to parse quickly. It's front-loaded with the core purpose and contains no unnecessary verbiage. Every word serves a purpose in communicating the tool's basic function.

  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 inadequate. It doesn't explain what 'children of a block' means in the Notion context, what format the results come in, or provide any behavioral context. The agent would need to rely heavily on the schema alone, which is insufficient for understanding the tool's full behavior and appropriate 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 provides no parameter information beyond what's already in the schema, which has 100% coverage. The schema thoroughly documents all 4 parameters including block_id format, pagination controls, and format options with clear usage guidance. The description adds no additional semantic value, so the baseline score of 3 is appropriate.

  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 ('children of a block'), making the purpose immediately understandable. However, it doesn't differentiate this tool from similar siblings like 'notion_retrieve_block' or 'notion_retrieve_page', which could cause confusion about when to use each 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 retrieval tools in the sibling list (notion_retrieve_block, notion_retrieve_page, notion_retrieve_database, etc.), there's no indication of what distinguishes retrieving block children from retrieving other Notion entities or when this specific retrieval operation is appropriate.

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

• notion_retrieve_bot_userC
  2.9/5.0
  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 this is a retrieval operation, implying it's likely read-only, but doesn't confirm this or describe other behaviors like authentication requirements, rate limits, error conditions, or what the response contains. For a 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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly. Every word earns its place.

  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 Notion API tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the bot user data includes, how it differs from regular users, or any authentication context. For a tool that likely returns structured user data, more context about the response would be helpful, especially without an output schema.

  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 fully documents both parameters. The description adds no additional meaning about parameters beyond what's 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, 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 verb 'Retrieve' and the resource 'bot user associated with the current token in Notion', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'notion_retrieve_user' or 'notion_list_all_users', which could cause confusion about when to use this specific bot user retrieval versus general user retrieval tools.

  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 prerequisites (e.g., needing a valid token), comparison to sibling tools like 'notion_retrieve_user', or specific use cases for retrieving bot users versus regular users. This leaves 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.

• notion_retrieve_databaseC
  2.9/5.0
  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. While 'retrieve' implies a read operation, the description doesn't specify whether this requires authentication, rate limits, pagination behavior, or error conditions. It also doesn't describe the return format beyond what's implied by the 'format' parameter in the 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 a single, efficient sentence that states the core purpose without unnecessary words. It's front-loaded and wastes no space, 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 that there are no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like authentication needs, rate limits, or what the return data looks like (beyond format options). For a tool that retrieves structured data, more context about the response 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?

  Schema description coverage is 100%, so the schema fully documents both parameters. The description adds no additional meaning about parameters beyond what's already in the schema (e.g., it doesn't explain database_id format or format usage beyond the enum descriptions). This meets 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 verb ('retrieve') and resource ('a database in Notion'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'notion_retrieve_page' or 'notion_retrieve_block', 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. For example, it doesn't explain how this differs from 'notion_query_database' (which likely searches within databases) or 'notion_retrieve_page' (which retrieves pages rather than databases), leaving the agent to infer usage from tool names alone.

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

• notion_retrieve_pageC
  2.9/5.0
  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. 'Retrieve' implies a read operation, but the description doesn't mention authentication requirements, rate limits, error conditions, or what the response contains. For a 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 a single, clear sentence with zero wasted words. It's appropriately sized for a simple retrieval operation and front-loads the essential information.

  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 information the retrieved page contains, how authentication works, potential errors, or how this differs from other retrieval tools. The parameter guidance in the schema helps, but the tool-level description is too minimal.

  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. The description adds no additional parameter information beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

  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 explicitly differentiate this tool from sibling tools like 'notion_retrieve_block' or 'notion_retrieve_database', which also retrieve Notion resources but different 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 'format' parameter description mentions use cases for 'json' vs 'markdown', this is parameter-level guidance, not tool-level guidance about when to retrieve a page versus querying a database or searching.

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

• notion_update_blockC
  2.9/5.0
  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 the update 'replaces the entire value for a given field,' which is crucial behavioral information about the mutation being destructive/replacement-based rather than partial. However, it doesn't mention authentication requirements, rate limits, error conditions, or what happens to other block properties not included in the update. 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.

  Conciseness4/5

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

  The description is appropriately concise with two sentences that each add value. The first sentence states the core purpose, and the second clarifies the replacement behavior. There's no wasted verbiage or unnecessary repetition of information already in the schema.

  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 no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns (success confirmation? updated block object?), doesn't mention error handling, and provides minimal behavioral context. The format parameter description offers some output guidance, but without an output schema, the agent lacks crucial information about response structure and content.

  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 minimal value beyond what's in the schema - it mentions the update is 'based on its type' and 'replaces the entire value,' which provides some context about the block parameter but doesn't add specific syntax or format details. This meets 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 the content of a block') and resource ('a block in Notion'), distinguishing it from siblings like notion_delete_block or notion_retrieve_block. However, it doesn't explicitly differentiate from notion_update_page_properties or notion_update_database, which are also update operations on different Notion 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 notion_update_page_properties for page content updates, or how it relates to notion_append_block_children for adding content versus replacing it. The format parameter description includes some usage hints, but these are about the response format, not the tool selection itself.

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

• notion_update_page_propertiesC
  2.9/5.0
  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 this is an update operation but doesn't mention permission requirements, whether changes are reversible, rate limits, or what happens to existing properties not included in the update. 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 is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded with the essential information.

  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 no annotations and no output schema, the description is insufficient. It doesn't explain what the update operation returns, error conditions, or behavioral constraints. The 100% schema coverage helps with parameters, but overall context for safe and effective use is lacking.

  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 three parameters thoroughly. The description adds no additional meaning about parameters beyond what's in the schema, maintaining the baseline score 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 properties') and target ('page or an item in a Notion database'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like notion_update_block or notion_update_database, which also perform updates on different Notion 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 sibling tools like notion_update_block (for block content) or notion_update_database (for database schema), nor does it specify prerequisites or typical use cases beyond the basic action.

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

• notion_searchB
  3.1/5.0
  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 function without disclosing behavioral traits like pagination behavior (implied by 'start_cursor' and 'page_size' parameters but not explained), rate limits, authentication requirements, or error conditions. It's minimally adequate but lacks important operational 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 that immediately conveys the core function without unnecessary words. It's perfectly front-loaded and wastes no space.

  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 search tool with 6 parameters, 100% schema coverage, and no output schema, the description is minimally complete. It states what the tool does but lacks context about when to use it, behavioral constraints, or result interpretation. The schema handles parameter documentation, but the description doesn't compensate for other gaps.

  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 6 parameters. The description adds no additional parameter semantics beyond what's already in the schema (e.g., it doesn't clarify search scope, ranking, or result format details). Baseline 3 is appropriate when schema does all 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 action ('Search') and target resources ('pages or databases by title in Notion'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling tools like 'notion_query_database' or 'notion_retrieve_page', which is why it doesn't reach 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 like 'notion_query_database' (for querying database contents) or 'notion_retrieve_page' (for retrieving specific pages). There's no mention of prerequisites, limitations, 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.

• notion_append_block_childrenB
  3.3/5.0
  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 the capability requirement but doesn't disclose other behavioral traits like whether this is a write operation (implied by 'Append'), potential rate limits, error conditions, or what happens if the parent block doesn't exist. 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 efficiently structured in two sentences: the first states the core purpose, the second adds important optional functionality. Every sentence earns its place with no wasted words, making it appropriately sized and front-loaded.

  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 this is a mutation tool with no annotations and no output schema, the description should do more to explain behavioral context. While it covers the basic purpose and mentions a capability requirement, it lacks information about what the tool returns, error handling, or constraints. The schema provides parameter details, but the description doesn't compensate for the missing behavioral transparency.

  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 minimal value by mentioning the optional 'after' parameter, but doesn't provide additional semantic context beyond what's 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 ('Append new children blocks') and target resource ('to a specified parent block in Notion'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'notion_update_block' or 'notion_retrieve_block_children', which would require 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 Guidelines3/5

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

  The description provides some context by mentioning 'Requires insert content capabilities' and the optional 'after' parameter, which implies usage for adding content after existing blocks. However, it doesn't explicitly state when to use this vs alternatives like 'notion_update_block' for modifying existing content or 'notion_create_database_item' for different resource types.

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

• notion_create_commentA
  3.9/5.0
  Behavior3/5

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

  With no annotations provided, the description carries full burden. It discloses the required capability ('insert comment' capabilities) which is useful context about permissions. However, it doesn't mention other behavioral traits like whether this is a write operation (implied by 'Create'), rate limits, error conditions, or what the response looks like. The description adds some value but leaves significant 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 (two sentences) and front-loaded with the core purpose. Every sentence earns its place: the first states what the tool does and prerequisites, the second clarifies a critical parameter constraint. There's zero wasted text.

  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 complexity (4 parameters with nested objects, no output schema, no annotations), the description is somewhat incomplete. It covers the prerequisite capability and parameter exclusivity but doesn't address the response format, error handling, or provide examples. For a write operation with rich parameter structures, more guidance 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?

  Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds the important semantic constraint that 'parent' and 'discussion_id' are mutually exclusive ('but not both'), which is valuable context beyond the schema. However, it doesn't explain the 'rich_text' parameter's purpose or the 'format' parameter's implications.

  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'), target resource ('in Notion'), and distinguishes from siblings by focusing on comment creation rather than other Notion operations like creating databases, updating pages, or retrieving content. It's not a tautology of the name.

  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: it specifies the required capability ('insert comment' capabilities) and the exclusive choice between 'parent' and 'discussion_id'. However, it doesn't explicitly mention when NOT to use it versus alternatives like updating existing comments or using other sibling tools for different operations.

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

• notion_retrieve_commentsA
  3.9/5.0
  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 mentions the required capability ('read comment' capabilities) and implies read-only behavior through 'retrieve,' but doesn't disclose other important traits like rate limits, pagination behavior (though hinted via parameters), error conditions, or what 'unresolved' specifically means. It adds some context but leaves gaps 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 two sentences, front-loaded with the core purpose and followed by a prerequisite. Every word earns its place with zero waste, making it highly efficient and easy to parse for an AI agent.

  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 but has gaps. It covers the purpose and a prerequisite, but for a tool with 4 parameters and behavioral complexity (e.g., pagination, format options), it lacks details on return values, error handling, and full behavioral context. It's adequate but not fully comprehensive for the tool's complexity.

  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 doesn't add any meaning beyond what the schema provides—it doesn't explain parameter interactions, defaults, or usage nuances. Baseline 3 is appropriate when the schema does the heavy lifting, though no extra value is added.

  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' and resource 'comments' are precise and unambiguous.

  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 ('retrieve a list of unresolved comments') and mentions a prerequisite ('Requires the integration to have 'read comment' capabilities'), but it doesn't explicitly state when NOT to use it or name alternatives among sibling tools (e.g., notion_retrieve_block for page content instead of comments). The guidance is helpful but not comprehensive.

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

• notion_list_all_usersA
  4.4/5.0
  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 adds valuable behavioral context: it discloses the Enterprise plan requirement and Organization API key prerequisite, which are critical for successful invocation. However, it doesn't mention pagination behavior or rate limits, 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?

  Two sentences with zero waste: the first states the core purpose, the second provides critical prerequisite information. The description is appropriately sized and front-loaded with essential information.

  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 list operation with 100% schema coverage but no output schema or annotations, the description provides good context about purpose and prerequisites. However, it doesn't describe the return format or structure, which would be helpful given the lack of output schema.

  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 three parameters. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for high schema coverage.

  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_retrieve_bot_user' (specific type). It provides a complete verb+resource+scope statement.

  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 ('List all users in the Notion workspace') and includes a critical prerequisite note about requiring an Enterprise plan and Organization API key to avoid permission errors. This provides clear context and exclusions.

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

• notion_retrieve_userA
  4.4/5.0
  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 describes key behavioral traits: it's a read operation (implied by 'retrieve'), requires specific permissions (Enterprise plan and Organization API key), and warns about potential errors (permission errors). However, it doesn't mention rate limits, response format details, or error handling beyond permissions.

  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 with two sentences: the first states the purpose, and the second provides critical usage prerequisites. Every word earns its place, and the structure is front-loaded with the core functionality followed by important constraints.

  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 annotations and no output schema, the description is quite complete: it covers purpose, prerequisites, and distinguishes from siblings. However, it doesn't describe the return value format or potential error scenarios beyond permissions, leaving some gaps in contextual 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 already fully documents both parameters (user_id format and format enum with usage guidance). The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score of 3 for high schema coverage.

  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 the scope 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 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 ('Retrieve a specific user by user_id') and provides critical prerequisites ('requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors'), which helps the agent avoid errors. It also implicitly distinguishes it from notion_list_all_users for bulk retrieval.

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