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

Since no annotations are provided, the description carries the full burden. It discloses critical behavioral traits: the mutation nature ('Append'), key limits (max 100 blocks, 2 nesting levels, 2000 chars), and that it modifies a parent block. However, it doesn't mention error conditions, rate limits, or authentication requirements, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, front-loaded sentence that states the core purpose, followed by a concise list of limits. Every word earns its place with no redundancy or fluff, making it highly efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is adequate but incomplete. It covers the core action and limits but lacks information on error handling, return values, or side effects. Given the complexity of the input schema, more guidance on block construction would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3. The description adds minimal value beyond the schema—it repeats the limits already documented in the children parameter's description. It doesn't provide additional context about parameter interactions or usage examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Append children blocks') and resource ('to a parent block'), making the purpose specific and unambiguous. It distinguishes this tool from siblings like notion_retrieve_block_children (which reads) and notion_update_block (which modifies existing blocks).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides no guidance on when to use this tool versus alternatives like notion_update_block or notion_create_page. It mentions limits but doesn't explain prerequisites, such as requiring write permissions or when appending is appropriate versus creating a new page. No explicit when/when-not statements are present.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by stating the permission requirement ('insert comment' capabilities) and the mutual exclusivity rule for parent/discussion_id. However, it doesn't mention potential side effects (e.g., notifications sent), rate limits, error conditions, or what the response looks like (since there's no output schema). For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is perfectly front-loaded and efficient: two sentences that cover purpose, prerequisites, and key usage constraint. Every word earns its place with zero redundancy. It's appropriately sized for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (mutation with 4 parameters, nested objects, no annotations, no output schema), the description is incomplete. While it covers purpose, prerequisites, and a key parameter constraint well, it lacks information about the response format, error handling, and other behavioral aspects. The 100% schema coverage helps, but for a creation tool, more context about what happens after invocation would be valuable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds value by clarifying the parent/discussion_id exclusivity rule, which isn't captured in the schema. However, it doesn't provide additional semantic context beyond what's already in the parameter descriptions (e.g., explaining when to choose parent vs discussion_id). Given the high schema coverage, baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a comment in Notion') and resource ('comment'), distinguishing it from sibling tools like notion_retrieve_comments (which reads comments) and other creation tools (which create pages, databases, etc.). It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description explicitly states when to use this tool ('Create a comment in Notion') and provides crucial exclusion guidance: 'You can either specify a page parent or a discussion_id, but not both.' It also mentions a prerequisite: 'This requires the integration to have 'insert comment' capabilities.' This gives clear context for when and how to invoke the tool versus alternatives.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic action. It doesn't mention authentication requirements, rate limits, whether this is a write operation (implied but not explicit), what happens on success/failure, or any side effects. For a creation tool with zero annotation coverage, this represents a significant gap in behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single, efficient sentence with zero wasted words. It's appropriately sized for a basic tool description and front-loads the essential information immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a database creation tool with complex nested parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what constitutes a successful creation, what gets returned, error conditions, or how this tool relates to other Notion operations. The agent would need to infer too much from the sparse description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, providing comprehensive documentation for all 4 parameters. The description adds no additional parameter information beyond the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no parameter info in the description, which applies here.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Create a database in Notion' clearly states the verb ('Create') and resource ('database in Notion'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'notion_create_database_item' which creates items within databases, leaving some ambiguity about scope differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides no guidance on when to use this tool versus alternatives like 'notion_create_page' or 'notion_create_database_item'. There's no mention of prerequisites, constraints, or typical use cases, leaving the agent with insufficient context for appropriate tool selection.

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

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

With no annotations, the description must fully disclose behavior. It only states the creation action without mentioning side effects, required permissions, rate limits, or consequences of invalid properties. The mutation intent is implied but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence with no redundancy. However, it could be slightly improved by front-loading the key action and resource while being more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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, nested object, no output schema), the description is incomplete. It does not mention the return value (the created page) or how to handle schema mismatches. The schema partially compensates but lacks behavioral context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage, so the baseline is 3. The description adds no extra meaning beyond the schema; e.g., the format parameter's usage guidance is already in the schema. No new semantics are introduced.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('create') and the resource ('new item (page) in a Notion database'). It distinguishes from sibling tools like notion_create_database (creates whole database) and notion_update_page_properties (updates existing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No context is provided on when to use this tool versus alternatives, such as notion_update_page_properties for modifying existing items or notion_query_database for reading. 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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates critical constraints ('LIMITS: 100 blocks, 2 nesting levels, 2000 chars') that aren't evident from the schema alone. However, it doesn't mention authentication requirements, error conditions, or rate limits that would be valuable for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is perfectly concise - a single sentence that states the core purpose followed by critical constraints. Every word earns its place, and the information is front-loaded with no unnecessary elaboration. The bold formatting for 'LIMITS' effectively highlights the most important behavioral constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with no annotations and no output schema, the description is adequate but has clear gaps. It covers the basic purpose and critical constraints, but doesn't address error handling, response format expectations, or integration patterns with sibling tools. The schema richness compensates somewhat, but more behavioral context would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds minimal value beyond what's in the schema - it mentions the parent relationship but doesn't provide additional context about parameter interactions or usage patterns. The baseline of 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a page'), the resource ('as child of page or database'), and distinguishes it from siblings by focusing on page creation rather than database operations or updates. It provides a complete verb+resource statement that is immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides no guidance on when to use this tool versus alternatives like 'notion_create_database_item' or 'notion_update_page_properties'. It doesn't mention prerequisites, dependencies, or contextual factors that would help an agent choose between this and sibling tools for content creation scenarios.

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

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

The description only says 'Delete a block in Notion' without any behavioral details. Since no annotations are provided, the description should disclose side effects (e.g., cascading deletion of children), required permissions, or irreversibility. It does not.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is a single concise sentence with no wasted words. However, it is under-specified; a slightly longer description with key usage context would be more helpful without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should provide more context about the tool's behavior, such as return value or effect on related blocks. The minimal description leaves the agent underinformed for a deletion operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for its two parameters, so the schema already explains block_id format and format options. The description adds no new parameter meaning beyond the schema, 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'Delete' and the resource 'block in Notion', making the action clear. However, it does not distinguish this tool from siblings like notion_update_block or notion_retrieve_block, which also operate on blocks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it relates to sibling tools like notion_append_block_children or notion_update_block.

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

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

With no annotations, the description carries the full burden. It discloses the permission requirement (Enterprise plan, Organization API key), but does not mention other behaviors like pagination flow, rate limits, or error handling. Acceptable for a simple list tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two concise sentences: first defines purpose, second provides critical dependency info. No redundant or unnecessary text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and the description covers purpose and a key requirement. Lacks mention of return format or response structure, but this is not essential given the tool's straightforward nature. Could be improved slightly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds no additional meaning beyond what the schema already provides for all three parameters. Baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all users in the Notion workspace,' which is a specific verb+resource combination. It distinguishes from sibling tools like 'notion_retrieve_user' (single user) and 'notion_search' (general search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description provides a crucial usage note about requiring an Enterprise plan and Organization API key to avoid permission errors. This helps the agent know when this tool is appropriate, though it doesn't explicitly mention alternatives.

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

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

No annotations provided, so description carries full burden. Only states 'Query a database' implying a read operation, but does not disclose pagination behavior, rate limits, or that it retrieves database items rather than metadata. Minimal behavioral disclosure beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Single sentence, very concise. Given that the schema covers most details, this brevity is acceptable. However, it borders on under-specification as the tool is complex.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 100% schema coverage and no output schema, the description does not explain the return structure (e.g., array of pages), pagination behavior, or the scope of query results. For a tool with 6 parameters and nested objects, the description is too sparse to be complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for all 6 parameters. Description adds value for the 'format' parameter by specifying when to use each format ('markdown' for reading, 'json' for writing). However, for other parameters (filter, sorts, start_cursor), the description adds nothing beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Query a database in Notion', which is a generic verb+resource. It does not specify that this tool queries items/pages within a database (as opposed to retrieving database metadata like notion_retrieve_database), nor does it differentiate from sibling tools that also interact with database items.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance on when to use this tool vs alternatives (e.g., notion_retrieve_database for schema, notion_create_database_item for adding items). Lacks context about prerequisites or common usage scenarios.

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

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

With no annotations, the description must carry the full burden of behavioral disclosure. It only states 'Retrieve', implying no side effects, but does not mention authentication needs, error cases (e.g., invalid block_id), rate limits, or whether the operation is safe. Essential behavioral context is missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Single sentence, no fluff, front-loaded with the core purpose. Every word earns its place. Cannot be more concise while remaining complete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's simplicity, the description lacks information about return values or behavior. There is no output schema, so the description should at least hint at what the response contains (e.g., block content, metadata). It does not, making it incomplete for an agent that needs to use the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds meaningful value beyond the schema. The 'format' parameter includes a clear decision tree for when to use 'markdown' vs 'json', which helps the agent choose appropriately. The 'block_id' description specifies the expected format. This is above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Retrieve' and the resource 'a block', which is specific enough to understand the tool's basic function. However, it does not differentiate from closely related siblings like 'notion_retrieve_block_children' or 'notion_retrieve_page', so the agent would need to infer distinctions from context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 such as 'notion_retrieve_block_children' or 'notion_retrieve_page'. There are no exclusions, prerequisites, or context hints, leaving the agent to guess based on tool names alone.

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

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

With no annotations, the description must fully communicate behavioral traits. It only states 'retrieve' (implying read-only) but does not disclose pagination behavior, rate limits, or whether it returns multiple pages. The schema shows pagination parameters, but the description does not mention them, leaving agents to infer behavior from schema alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is extremely concise at one sentence, with no redundant information. It front-loads the core action. While brevity is valued, it could benefit from a brief note on pagination or typical use cases without becoming wordy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 does not describe the return format structure (e.g., a list of block objects) or pagination behavior beyond what is hinted in the schema. For a tool used to retrieve nested content, more context is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, including detailed guidance for each parameter (e.g., format parameter explains when to use 'json' vs 'markdown'). The tool description adds no additional parameter semantics, so it does not exceed the baseline of 3 for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('retrieve') and the resource ('children of a block'), which distinguishes it from sibling tools like 'notion_retrieve_block' (single block) and 'notion_append_block_children' (modifying children). However, it does not elaborate on what 'children' means in Notion (child blocks), which could add slight ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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. For example, it does not mention that this tool is intended for retrieving hierarchical content, while 'notion_retrieve_block' is for a block's own properties. The description lacks context for preference.

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

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

No annotations provided, so description carries burden. It describes a read operation without side effects, but does not explicitly mention safety or other behavioral traits. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Single clear sentence with no redundancy, though could include more details without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, and description does not hint at the structure of the bot user object. For a simple retrieval, adequate but leaves some expectation gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both parameters. Description adds no additional meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states action (retrieve), resource (bot user), and context (associated with current token). Distinguishes from sibling tools like notion_retrieve_user and notion_list_all_users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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. Does not specify prerequisites or exclusions.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It states it retrieves unresolved comments and requires read capabilities, but omits details such as pagination behavior, error conditions (e.g., invalid block_id), or ordering of results. These gaps limit transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is two sentences long, front-loaded with the core action, and contains no redundant text. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, no output schema, and no annotations, the description is adequate but incomplete. It defines the core functionality and a key requirement, but does not explain return values or pagination behavior, leaving some context gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, and each parameter includes helpful details (e.g., block_id formatting, format guidance). The tool description itself does not add parameter information beyond what the schema provides, so it meets the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves unresolved comments from a Notion page or block. The verb 'retrieve' and resource 'comments' are specific. While it does not explicitly differentiate from sibling tools like notion_retrieve_block or notion_retrieve_page, the focus on comments provides inherent distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description mentions a prerequisite ('Requires the integration to have read comment capabilities') but does not provide guidance on when to use this tool versus alternatives. No explicit when-not or comparison to other tools is given, so usage context is implied rather than explicit.

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

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

No annotations provided. Description does not disclose any behavioral traits beyond the verb 'retrieve', such as whether it is read-only, requires specific permissions, or returns the full database structure. Minimal 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.

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

Single sentence, no unnecessary words. Perfectly concise for the simplicity of the tool. Front-loaded verb.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is minimal and does not provide complete context such as what exactly is retrieved (e.g., properties, items?), or how it differs from query_database. However, given the simplicity and schema coverage, it is adequate but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% description coverage, providing details for both parameters. The tool description itself does not add any additional meaning beyond the schema. Baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action ('Retrieve a database') and resource ('in Notion'). However, no differentiation provided from sibling tools like 'notion_query_database', which may have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 vs alternatives. The format parameter description provides usage context for output format, but not for tool selection. No mention of prerequisites or scenarios.

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

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

No annotations provided, so description carries full burden. It indicates a read operation but omits details like permissions, rate limits, or error handling. The format parameter guidance in the schema adds some behavioral context, but the description itself adds minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is extremely concise with a single sentence that immediately conveys the tool's core function. No extraneous words, every part is justified given that schema handles details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and sparse description: it does not explain what the returned page data contains or how to interpret it. Given sibling tools with similar retrieval operations, more context on page structure or typical use cases is needed for complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add any semantics beyond the schema; the schema already describes page_id format and format usage. Description provides no additional meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Retrieve a page from Notion', specifying the verb and resource. It distinguishes from sibling tools like notion_retrieve_block or notion_retrieve_database by the resource type, though it could elaborate on what a 'page' entails.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 such as notion_retrieve_block or notion_search. There's no mention of when not to use it or prerequisites.

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

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

No annotations are provided, so the description must disclose all behavioral traits. It mentions the Enterprise requirement but lacks details on error handling, rate limits, or return structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two sentences, front-loaded with purpose, followed by a critical usage note. No extraneous words; highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Lacks explanation of the return value (e.g., user properties) since no output schema is provided. The description is minimal but covers the essential purpose and a key prerequisite.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the input schema already clearly describes both parameters. The description adds no additional parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Retrieve a specific user by user_id in Notion.' Verb and resource are specific, and it distinguishes from sibling tools that list all users or retrieve the bot user.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description includes a crucial note about requiring an Enterprise plan and Organization API key, which guides usage. However, it does not provide explicit when-to-use or alternative comparisons.

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

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

The description is a single sentence with no details on return format, pagination behavior, error handling, or authentication requirements. Without annotations, the description fails to disclose important behavioral traits 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.

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

The description is one concise sentence placed at the beginning, immediately conveying the tool's purpose without extraneous detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the schema covers parameters, the overall context is minimal. The description lacks scope (e.g., across which content it searches) and behavior (e.g., pagination, result size limits). It is adequate for basic understanding but leaves gaps for new users.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema describes all parameters with clear definitions, and the 'format' parameter includes usage guidance (when to use markdown vs json). This adds concrete value beyond the schema, aiding correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches pages or databases by title in Notion. While it distinguishes the action from sibling tools like notion_retrieve_page or notion_query_database, it does not explicitly differentiate the search scope versus database querying.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 notion_query_database or notion_retrieve_page. There is no mention of prerequisites, limitations, or when not to use it.

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

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

Notes the replacement behavior ('replaces the entire value'), but with no annotations, it omits details on permissions, error conditions, or idempotency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Two concise sentences, no fluff, front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers basic purpose and replacement behavior but lacks details on response format, error handling, and required structure of the block object. No output schema exacerbates gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds context about 'based on its type' and 'replaces entire value', which meaningfully supplements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool updates block content, specifies it's type-dependent, and distinguishes from sibling tools like notion_retrieve_block and notion_delete_block.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

The description implies use when updating a block but provides no explicit guidance on when to use alternatives like notion_append_block_children or notion_update_page_properties.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. 'Update a database' implies a mutation operation, but the description doesn't mention permissions required, whether changes are reversible, rate limits, error conditions, or what happens to unspecified properties. For a complex mutation tool with 5 parameters, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

The description is extremely concise at just 5 words. It's front-loaded with the core action and resource. There's zero wasted language or redundancy. For a tool with comprehensive schema documentation, this brevity is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex mutation tool with 5 parameters, nested objects, no annotations, and no output schema, the description is inadequate. It doesn't explain what 'updating' entails, what fields can be modified, how partial updates work, or what the response contains. The rich schema documentation helps, but the description should provide higher-level context about the update operation's scope and behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds no additional parameter information beyond what's in the schema - it doesn't explain relationships between parameters, provide examples, or clarify usage patterns. Baseline 3 is appropriate when schema does all the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Update a database in Notion' states the basic action (update) and resource (database), but is vague about what specifically can be updated. It doesn't distinguish from sibling tools like notion_update_page_properties or notion_update_block, which also perform updates on different resources. The description lacks specificity about scope or fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

No guidance is provided on when to use this tool versus alternatives. There's no mention of prerequisites (e.g., needing database ID), comparison to sibling tools like notion_create_database or notion_retrieve_database, or any context about when this update operation is appropriate versus other update tools in the Notion suite.

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

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

No annotations are provided, so the description must fully disclose behavioral traits. It states 'update' implying mutation, but does not mention authentication requirements, rate limits, side effects, or whether the operation is reversible. This is insufficient for an update operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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

Description is a single sentence, concise and to the point. However, it omits some behavioral details that could be included without making it verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema, the description does not clarify what is returned after update (e.g., the updated page object). It partially covers input via parameter semantics, but overall completeness is moderate, especially considering the complexity of updating Notion properties.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline is 3. The description adds useful context: 'properties' are likened to database columns/fields. The 'format' parameter includes explicit guidance on when to use each enum value (markdown vs json), which adds significant semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb (update) and resource (properties of a page/database item). However, it does not differentiate from sibling tools like notion_update_block or notion_update_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.

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. There is no mention of prerequisites, context, or exclusions. The description simply states the action without any usage advice.

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