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

With no annotations, the description carries the transparency burden. It discloses that text is sent as native API markdown, supporting inline formatting, equations, and @mentions, and explains the behavior of discussion_id (turns the comment into a reply). It doesn't mention permissions or errors, but given the output schema exists, return values are covered.

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 concise and well-structured, with the purpose front-loaded in the first sentence. The parameter list is clear and each line earns its place, including the practical pointer to notion_get_comments. No unnecessary words.

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 simplicity, the description is complete: purpose, all parameter semantics, and a helpful cross-reference to a sibling tool. The presence of an output schema covers return values. No critical information is missing for an agent to select and invoke this tool correctly.

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 0%, so the description fully compensates by explaining each parameter explicitly: page_id (the page to comment on), text (with markdown details), and discussion_id (reply semantics). This adds significant meaning beyond the schema's bare names and types.

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's action: 'Add a comment to a Notion page or reply to a discussion thread.' It specifies the verb (add) and resource (page or discussion thread), and distinguishes it from sibling tools like notion_update_comment and notion_delete_comment by focusing on creation.

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 clear context for when to use the tool: to add a new comment or reply to an existing discussion thread. It also points to a sibling tool (notion_get_comments) for obtaining discussion IDs, which is useful. It doesn't explicitly exclude alternatives, but the context is clear enough for a simple create operation.

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 fully discloses key behavioral traits: the append/replace mode semantics (what happens to existing files), the fact that files never traverse MCP parameters (implying side-channel transfer and no size limits), and the exact source schemes. This goes far beyond typical descriptions and informs the agent of important operational details.

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 front-loaded with the main purpose, followed by a cleanly formatted parameter list and a practical workflow example. Every sentence contributes valuable information—no fluff. The structure makes it easy to scan and understand.

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 (5 params, 3 required) and lack of annotations, the description is remarkably complete: it covers all parameters, provides usage workflows, and even explains cross-MCP file transfer mechanics. It also references sibling tools for context. No critical information is missing.

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 0%, but the description compensates excellently by defining every parameter: page_id with how to obtain it, source with all supported schemes, files_property as exact column name, mode with concrete append/replace behavior, and filename as override. This provides complete semantics beyond the bare 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 opens with a specific verb+resource+target: 'Upload a file and attach it to an EXISTING database row's files & media column.' The emphasis on 'EXISTING' distinguishes it from sibling tools like notion_upload_file_to_database and notion_batch_add_file_to_row. It clearly states what the tool does.

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 'Cross-MCP file transfer' section provides a concrete step-by-step workflow for using this tool with a Gmail attachment, including prerequisites (download_attachment) and an alternative route via Drive. This gives explicit context for when to use this tool and how it fits into a larger process, effectively covering usage guidance.

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. It discloses that markdown is parsed into blocks and appended to the end of the page, and lists supported markdown elements. It doesn't discuss error cases or permissions, but the core behavioral traits are transparent and complete for a simple append 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?

The description is well-structured: a one-sentence purpose, a brief explanation of parsing behavior, a list of supported markdown features, and clear parameter definitions. Every sentence provides useful information with no redundancy or filler.

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 covers both required parameters, explains the input format, and describes the append operation. It doesn't address edge cases like empty content or invalid page_id, but the tool is relatively simple and the output schema is present, so the description is sufficiently complete for an agent to use it correctly in most scenarios.

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 provides only names and types with no property descriptions (0% coverage). The description fully compensates by explicitly defining page_id as 'the page to append to' and content as 'markdown text to append,' and it elaborates on the content format. This adds substantial meaning 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?

The description clearly states the tool appends markdown content to an existing Notion page, with a specific verb (append), resource (existing page), and scope (end of page). This distinguishes it from siblings like notion_replace_page_content or notion_update_page_content, which replace or update content rather than append.

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 clear context for when to use this tool: when you want to add content to the end of an existing page. It doesn't explicitly mention alternatives or exclusions, but the append semantics and 'existing page' phrasing imply the appropriate use case and distinguish from creation or replacement.

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?

Despite no annotations, the description discloses that the operation is a soft-delete and the page remains in trash for 30 days. This is valuable behavioral context beyond the basic 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?

The description is compact: one sentence for the operation, one for restoration, and one for the parameter. It is front-loaded with the core purpose and contains no redundant 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 with one required parameter, and the description covers purpose, soft-delete behavior, restore path, and parameter semantics. The presence of an output schema means return values don't need explanation. Slight gap: no mention of permissions or side effects, but not essential.

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 has 0% description coverage for page_id, but the description adds 'the page to archive,' providing clear meaning for the sole parameter. This compensates for the schema gap.

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 archives (soft-deletes) a Notion page, distinguishing it from delete_block or update_page. It also mentions restoration, further clarifying the specific operation.

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 references notion_restore_page as the path for undoing the archival, giving context on when to use this tool vs. that alternative. However, it does not explicitly state when not to use it (e.g., for permanent deletion).

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 fully discloses key behaviors: bounded concurrency with default 3, serialization for same-row items, 429/5xx backoff, per-item failures reported but not aborting the batch, and the read-modify-write nature of the append path. This is rich, non-obvious context that goes far beyond what annotations or schema provide.

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 long but genuinely information-dense: each paragraph covers a distinct aspect (usage example, defaults, concurrency, error handling, staging workflow) and the first sentence states the purpose. No filler or repetition.

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 (batch concurrency, per-item errors, default inheritance), the description covers all critical operational aspects, including a recommended workflow involving sibling tools. An output schema exists, so return-value details are not required, but the description still covers per-item status reporting.

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 0%, so the description must compensate. It does so by giving a full JSON example for items_json, explaining default_mode and default_files_property as batch-level fill-ins, and showing mode values like 'append' and 'replace'. This makes the parameters meaningful beyond their bare schema definitions.

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 opens with 'Attach files to many existing Notion rows in one call,' which is a specific verb+resource+scope. It clearly contrasts with the singular notion_add_file_to_row sibling and the batch nature is explicit.

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?

Provides a concrete usage pattern ('stage N files via google-accounts-mcp download_attachment, call this tool once, then call notion_purge_file') and explains why batch is preferable to serial ('a batch of ~8 used to exceed the client's 4-minute timeout when serial'). This gives clear when-to-use context and implies the singular tool for one-off operations.

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. It does disclose that the database appears as an inline database on the page and that a title property is required, which adds behavioral context. However, it does not state permissions needed, reversibility, or what happens on failure. For a mutation tool, this is a moderate level of 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 well-structured with a clear opening sentence, parameter breakdown, and a compact example. The example is lengthy but necessary for explaining the schema_json format. Every part serves a purpose, though the overall length is above minimal.

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 covers the essential aspects of the create operation, including the target page, title, and schema structure. It does not mention return values, but an output schema is present, so that gap is acceptable. Missing prerequisites like page existence or permissions are not stated, but the description is fairly complete given its complexity.

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 provides no descriptions for its parameters, so the description must compensate. It does so thoroughly by explaining each parameter (parent_page_id, title, schema_json) and providing a detailed example for schema_json, including property types and structure. This adds significant meaning 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?

The description clearly states 'Create a new Notion database under a page,' which is a specific verb and resource. It distinguishes this from sibling tools like notion_update_database (updating existing) and notion_query_database (querying) by focusing on creation. The scope of where the database is created is also specified.

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 context of use is clear: this tool creates a database and places it under a specified page. While it doesn't explicitly mention alternatives or exclusions, the description provides enough context for an agent to know when to select this tool over siblings (e.g., not for updating or querying). The 'under a page' detail adds important usage context.

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 explains that the tool behaves differently depending on which ID is provided (parent_page_id vs database_id), and it details that content supports markdown elements like headings, lists, quotes, code blocks, and inline formatting. While it does not mention permissions or rate limits, the main creation behavior is well-covered for a non-destructive write 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?

The description is efficiently structured with a lead sentence, two usage lines, and a clean parameter list. It is longer than minimal, but given 6 parameters and two modes, every line earns its place. The purpose is front-loaded, and the list format improves readability.

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 has 6 parameters, no schema descriptions, and an output schema (so return values are presumably covered elsewhere). The description covers all parameters and the key mode distinction, making it complete enough for an agent to invoke correctly. It does not explain error scenarios, but that is not required for completeness here.

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 has 0% description coverage, so the description must fully compensate. It explains every parameter: title, content, parent_page_id, database_id, properties_json, and icon. It also clarifies the format of properties_json as 'keys are property names, values are Notion API property value objects' and gives an example for icon. This is excellent compensation for the bare 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 opens with a specific verb+resource: 'Create a new Notion page with optional markdown content.' It clearly differentiates from sibling tools like notion_create_database and notion_update_page by focusing on page creation, and it further specifies two distinct modes (standalone page under another page vs database row). This makes the tool's purpose unambiguous.

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 clear context for when to use the tool: 'For a standalone page under another page, provide parent_page_id. For a database row, provide database_id and properties_json.' It effectively explains the two main use cases, though it does not explicitly name alternatives or state when not to use this tool. Still, the mode distinction gives actionable guidelines.

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 carries the full burden. It adds useful behavioral context by documenting parameters, including the default view_type and the cross-reference to notion_query_database's filter_json, but it does not disclose side effects, permissions, or failure modes. It only implies mutation through the verb 'create'.

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 front-loads the purpose in a single sentence, then uses a clear list format for parameter documentation. Every line provides necessary information with no filler, making it both concise and well-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 5-parameter complexity and the existence of an output schema, the description covers all parameters effectively and provides a helpful cross-reference for filter_json. It does not mention prerequisites like the database existing, but this is relatively minor for a create 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?

Schema description coverage is 0%, and the description fully compensates by documenting every parameter: database_id, name, view_type with allowed values, filter_json with a reference to another tool's format, and sorts_json as an optional JSON array. This adds significant meaning beyond the raw 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 states 'Create a view on a Notion database' with a specific verb and resource. It clearly distinguishes from sibling tools like notion_list_views, notion_update_view, and notion_delete_view by the action 'create'.

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 context is clear that this tool is used to create a view on a database, but there is no explicit guidance on when to use it versus alternatives. No exclusions or alternative tool mentions are provided, so the usage 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 are provided, so the description carries the full burden. It explicitly discloses that the deletion removes the block and all children, and that deletion is permanent and cannot be restored. This fully informs the agent of destructive side effects.

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 only two sentences plus a parameter line, with the main action and critical caveats front-loaded. Every sentence adds value with no redundancy.

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 simple deletion tool with one parameter and an output schema, the description covers the essential behavioral context: what is deleted, cascading effect, and irreversibility. No further explanation of return values is necessary given the output schema.

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 only provides a title ('Block Id') with no description. The description adds 'ID of the block to delete,' clarifying that this is the target block. For a single-parameter tool with 0% schema coverage, this is adequate compensation.

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 ('Delete'), the resource ('a block from a Notion page'), and adds key scope ('all its children') and irreversibility. This distinguishes it from sibling tools like update_block or archive_page.

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 first sentence provides clear context: use this tool to delete a block from a Notion page. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous and distinct from related block/page operations.

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 reveals the ownership constraint and the 404 error for non-owned comments, which is useful behavioral context. However, it does not explicitly mention permanence or reversibility of the deletion, though this is a typical implication of a delete 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?

The description is extremely concise, with two clearly separated sentences: one for the purpose/behavior and one for parameter sourcing. No redundant information or filler text exists, making it easy to parse and act on.

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 with one parameter, an output schema (though not shown), and no annotations. The description covers the core purpose, a key behavioral constraint, and parameter sourcing. It could mention what the response looks like or explicitly note that deletion is permanent, but given the simplicity and presence of an output schema, the description is sufficiently 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?

The schema has no description for the single parameter, and coverage is 0%. The description compensates by telling the agent where to source the comment_id (from notion_get_comments or notion_add_comment). This adds practical meaning beyond the raw schema type, but it does not elaborate on the expected format or validation of the ID.

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 deletes a comment, with the specific constraint that it must have been created by this integration. This distinguishes it from sibling comment tools like notion_add_comment and notion_update_comment. The mention of Notion returning 404 for others further clarifies the exact scope.

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 when to use the tool (only for comments created by this integration) and when not to (for comments created by anyone else, as they will 404). It also guides the agent on where to obtain a valid comment_id (from notion_get_comments or notion_add_comment). Explicit alternatives are not listed, but no other delete-comment tool exists among the siblings.

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. It discloses a key behavioral trait: deletion only affects the view configuration, not the database or its rows. This helps set expectations about the tool's impact, though it does not mention permanence or permissions.

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, focused sentence that front-loads the action and includes a valuable clarification about what is not affected. No unnecessary words or repetition.

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 simplicity of the tool (one param, no annotations) and the presence of an output schema, the description is largely complete. It explains both the action and the non-destructive scope, leaving little ambiguity for an agent invoking the tool.

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 0% description coverage for its single parameter, and the description does not explicitly explain 'view_id'. While the parameter name and context imply it is the ID of the view to delete, the description does not add meaningful detail (e.g., how to obtain it or whether it must be a view ID rather than a database ID).

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 'Delete a view from its database', which identifies the specific action (delete) and resource (view). It distinguishes from sibling tools like notion_create_view and notion_update_view by indicating the destructive action, and from notion_delete_block by clarifying the scope is limited to a view configuration.

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 implicit context by noting 'The database and its rows are untouched', implying this tool is for removing only a saved view without affecting data. However, it does not explicitly state when to use this tool versus alternatives or mention any exclusions, so the guidance 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It states the core behavior (retrieves schema, returns property names/types) and adds context about how to find database_id. However, it does not disclose potential error conditions, rate limits, or any prerequisites beyond knowing the database_id. For a simple read-only operation this is adequate but not deeply transparent.

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 concise and well-structured. The first sentence states the purpose and return value, while the second provides crucial parameter guidance. No unnecessary words or redundant information are present.

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 (one parameter, no nested objects), and an output schema is present. The description explains what the tool does, what it returns, and how to get the input parameter. It also ties the tool into a broader workflow with related tools. This is sufficient for an agent to select and invoke it correctly.

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 provides only the parameter name 'database_id' with no description. The tool description compensates fully by explaining what database_id is and exactly how to obtain it: 'calling notion_list_files_on_page on the page that holds the inline database (child_database blocks will show), or pasted from the database URL.' This adds significant meaning 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?

The description uses the specific verb 'Retrieve' and clearly identifies the resource ('Notion database's schema'). It states what is returned ('each property name and type') and distinguishes this from siblings by focusing on schema retrieval rather than querying or modifying data. The additional note about finding exact column names for upload tools clarifies its intended niche.

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 an explicit use case: 'use this to find the exact files & media column name to pass to notion_upload_file_to_database / notion_add_file_to_row.' It also explains how to obtain the database_id via a sibling tool or URL. However, it does not explicitly mention when not to use this tool or compare it to alternatives like notion_query_database, so it lacks full exclusionary guidance.

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 so effectively by explaining storage locations (FILES_DIR, shared mount), the 24h TTL for shared, Drive upload behavior, and MCP response size limits for base64. It also notes that bytes never traverse MCP parameters in the shared flow, which is valuable operational context. It omits specifics like authentication or error semantics, but given the richness of what is disclosed, this is above average.

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 longer than average but well-structured with a bulleted list and a clearly separated cross-MCP workflow. Each sentence adds necessary information, and the most important purpose is front-loaded. It could be slightly tighter by moving the cross-MCP example into a 'Use cases' subsection, but it remains efficient and scannable.

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 having no annotations and minimal schema, the description covers all essential operational aspects: destinations, filename handling, storage paths, TTL, size constraints, and an end-to-end email attachment flow. It also gives a pointer to the sibling tool needed to locate block IDs. With an output schema present, return-value details are not needed from the description, and nothing critical is missing.

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 0%, so the description must fully document parameters. It explains destination as an enum with per-value behavior, filename as an override, and that local filenames may include subdirectories that are auto-created. block_id is implied by the opening sentence and the pointer to notion_list_files_on_page. This fully compensates for the sparse 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 opens with a specific verb+resource+scope: 'Download a file from a Notion file/image/pdf/video/audio block.' This clearly distinguishes the tool from siblings like notion_extract_file_text or notion_render_file_page, and the destination options are enumerated. It also cross-references notion_list_files_on_page for finding block IDs, reinforcing its unique role.

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 detailed guidance on when to use each destination option (local, shared, drive, base64), including TTL and size constraints. It also includes a step-by-step cross-MCP transfer example to Gmail. However, it does not explicitly contrast this tool with sibling tools that might also retrieve file content (e.g., notion_extract_file_text or notion_render_file_page), so exclusionary guidance is implicit 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?

With no annotations provided, the description carries full responsibility for behavioral disclosure. It excels by detailing response truncation (200 KB ceiling, page-boundary truncation, trailing marker), silent dropping of out-of-range pages, OCR auto behavior with a 20-char threshold, error conditions ('ocr_error'), and the distinction between native and OCR extraction. These details go far beyond what the schema or annotations reveal.

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 long but densely informative, with every section providing necessary operational detail. It is front-loaded with the core purpose and then structured into paragraphs and enumerations for source schemes, return format, page specs, mode, and OCR, making it navigable despite its length.

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 presence of an output schema, the description goes beyond it by explicitly listing the returned JSON fields and explaining truncation behavior. It covers all four parameters, source access, mode semantics, OCR fallback conditions, and error signaling, leaving no material gap for an agent to invoke the tool correctly.

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?

Since schema description coverage is 0%, each parameter is thoroughly explained in prose: source includes scheme-specific examples, pages uses a pdftotext-style grammar with concrete examples, mode enumerates 'text', 'layout', and 'tables' with explanations, and ocr documents 'auto', 'off', 'force', and 'llm' with detailed behavior. This fully compensates for the absent schema descriptions.

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's function: "Extract text from a PDF anywhere notion-mcp can reach" and distinguishes it by noting it does so "without moving the bytes over MCP." It also specifies supported source schemes and references companion tool notion_list_files_on_page, making the resource and scope unambiguous.

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 clear contextual guidance: it explains the acceptable source schemes, how to obtain block IDs (via notion_list_files_on_page), and when to use different modes and OCR settings. However, it does not explicitly contrast with alternative sibling tools (e.g., notion_download_file) or state when not to use this tool, so it falls short of full alternative-based guidance.

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 carries the transparency burden. It discloses that the tool returns comment text, author, and timestamps, and implies a read-only operation. However, it doesn't mention pagination, error behavior, or permissions. For a simple read tool this is adequate but not rich.

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 concise and front-loaded. The first sentence states the main action, followed by a useful detail about returned fields, a usage guideline, and a parameter explanation. Every sentence contributes value without redundancy.

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 simple tool with one parameter and an output schema, the description is complete. It explains what the tool does, what it returns, when to use it, and what the parameter means. Given the low complexity, no additional details are 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 one parameter (page_id) with no description, and schema coverage is 0%. The description compensates by explicitly explaining 'page_id: the page to get comments from.' This adds clear meaning beyond the bare parameter name, which is valuable for 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's function: 'Get all comments on a Notion page.' It specifies a precise verb (Get), resource (comments on a Notion page), and scope (all comments). The addition 'Use this to read discussion threads' reinforces the purpose and differentiates it from sibling tools that add, update, or delete comments.

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 gives a clear context for use: 'Use this to read discussion threads on a page.' While it doesn't explicitly name alternatives or exclusions, the read-focused language makes it obvious that this is for reading rather than modifying comments. The context is sufficient for selecting this tool over its mutating siblings.

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 burden of behavioral disclosure. It reveals that the tool returns a single property with full pagination, handles large properties gracefully, and gives precedence to property_id over property_name. This goes beyond a simple 'get' but could mention error handling or auth implications.

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 well-structured and front-loaded: a clear one-sentence purpose, followed by a targeted use case, then a neatly formatted parameter list. Every sentence earns its place, with no unnecessary fluff.

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 covers purpose, usage, and parameters well. However, it says 'Provide either property_name or property_id' but does not specify what happens if neither is given, especially since both are optional in the schema. This minor ambiguity prevents a perfect score.

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 0%, so the description must compensate. It thoroughly documents all three parameters: page_id (page to read), property_name (looked up from metadata), and property_id (from notion_describe_database schema, with precedence). This adds significant meaning beyond the bare 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 opens with 'Retrieve a single property from a Notion page with full pagination,' clearly stating the verb, resource, and scope. It distinguishes itself from sibling tools like notion_read_page by specifying 'single property' and addressing truncation, making its purpose unmistakable.

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 tool says it is 'Useful for large properties (relations, rollups, long rich_text) that get truncated in the normal page response,' providing clear context on when to use it. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.

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 burden of disclosing behavior. It states the tool 'Get details' (implying non-mutating) and lists the return fields. It also specifies the user_id format as a 'Notion user UUID.' However, it does not mention error conditions (e.g., 404 if not found) or any authentication requirements, but for a simple read tool this is reasonably transparent.

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 three concise sentences: purpose, return values, and usage guidance. It is front-loaded with the primary action. No filler or redundant information; every sentence earns its place.

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 simple get-by-id tool with one parameter and an output schema, the description is complete. It states what the tool returns, how to find the ID (via list_users), and the parameter format. No additional behavior or caveats are needed for this straightforward read 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?

Schema description coverage is 0%, but the description compensates by defining user_id as 'Notion user UUID,' which adds meaning beyond the bare schema (type string, title 'User Id'). It also includes the context that the ID is for a specific user. This is sufficient for a single parameter tool.

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 a specific verb+resource+scope: 'Get details for a specific Notion user by ID.' It also lists the returned fields (name, email, avatar URL, type), distinguishing it from sibling tools like notion_list_users which list users rather than fetching one. The phrase 'by ID' further clarifies the exact operation.

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 guides usage: 'Use notion_list_users to find user IDs first.' This provides a clear alternative and prerequisite, telling the agent when to use this tool vs. listing users. It also implies this tool is for a known user ID, which is good contextual guidance.

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 exist, so the description carries full responsibility. It discloses async polling behavior, plan-dependent size limits, the absence of sha256 reporting, and the server-side transfer path without sending bytes through this server. This is exemplary transparency for a tool with no annotations.

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 compact—four sentences—with the core purpose front-loaded. Every sentence adds essential context: constraints, async behavior, size limits, and integrity caveat. It is dense but not bloated, and each statement earns its place.

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 (async import, size limits, integrity concerns) and the presence of an output schema, the description covers all necessary operational aspects. It explains the critical behaviors without needing to describe return values, which are already handled by the output schema.

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 0% schema description coverage, the description compensates well by explaining url requirements, filename semantics (determines block type), wait_seconds as polling timeout, and referencing notion_upload_file for parent_page_id and position. However, the caption parameter is not mentioned, leaving a gap for a minor field.

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 opens with a specific action: 'Import a file into Notion directly from a public HTTPS URL' and clearly distinguishes this tool from notion_upload_file by noting the bytes go Notion-side, never through the server. It also references notion_upload_file for parameter behavior, making the scope and differentiation explicit.

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?

It provides clear usage context: url must be publicly accessible, filename must have an acceptable extension, and the import is asynchronous with wait_seconds timeout. It recommends notion_download_file for integrity checks, offering an alternative for a related need, but does not explicitly state when to prefer this over notion_upload_file for local files.

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. It discloses that the tool returns block IDs and filenames, and implies it does not download files (by directing to another tool). It does not mention any side effects, permissions, pagination, or failure modes, but for a read-only listing operation, the core behavior is adequately covered. The score reflects that it adds some context but lacks deeper behavioral details.

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 with no fluff. The first sentence states the action and scope, the second sentence explains the return value and next step. It is front-loaded with the key information and every sentence earns its place.

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 low complexity (1 parameter, simple listing) and the presence of an output schema, the description is mostly complete. It tells what is listed, what is returned, and how to use the result. The main gap is the lack of parameter format details, but for a tool this simple, the description covers the essential context well.

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 has zero description coverage, and the description does not compensate by explaining the page_id format (e.g., UUID vs URL). The only param is page_id, and the description merely says 'on a Notion page', which is redundant with the tool's name. The description adds no meaningful semantic information beyond what the schema field name implies.

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 uses a specific verb 'List' and clearly identifies the resource: all file/image/pdf/video/audio blocks on a Notion page. It distinguishes from siblings by mentioning the return of block IDs and filenames for use with notion_download_file, setting it apart from search or upload tools. This is a precise, unambiguous statement of purpose.

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 clear context for when to use this tool: to identify files on a page for subsequent download. It explicitly directs the user to use the returned block IDs with notion_download_file, which is a concrete usage guideline. However, it does not mention explicit alternatives or exclusions (e.g., when not to use it), but the context is sufficient for a simple listing tool.

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 that the tool lists files in two specific stores and describes the source addressing forms. It does not mention side effects or edge cases, but as a read-only listing action the core behavior is clear.

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 front-loaded with a purpose statement, then uses a bulleted list for the location options, and ends with a short sentence about the filter. It is well-structured and every sentence contributes value.

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 has only two optional parameters with defaults and an output schema, and the description covers its purpose, both locations, and the filter. The cross-MCP context about google-accounts-mcp adds completeness, making the description sufficient for correct invocation.

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 has zero descriptions, but the description fully explains the 'location' parameter with its two possible values and their meanings, and the 'filter' parameter as an optional substring filter. This adds significant meaning beyond the raw 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 lists files available to notion-mcp by scheme, and explains the purpose of verifying a handoff before attaching to Notion. It distinguishes between 'files' and 'shared' locations, which sets it apart from sibling tools like notion_list_files_on_page.

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 clear context for when to use the tool—verifying a handoff before attaching—and explains the two location schemes including which files are in each. However, it does not explicitly mention alternatives or when not to use this tool versus other listing tools.

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 carries the disclosure burden. It states the returned data (names, IDs, emails, types) and the typical use of user IDs. However, it does not disclose potential pagination behavior or permission requirements, leaving some 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 two sentences, front-loaded with the main purpose. The second sentence adds valuable details about return data and use case. No unnecessary words or repetition; it is highly concise and well-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?

The tool is low complexity with an output schema, and the description covers the core purpose and returned data. It lacks explicit notes on pagination or permissions, but with an output schema in place and the simplicity of a zero-parameter list, the description is reasonably 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?

The tool has zero parameters, so there is no parameter information to add. The baseline of 4 is appropriate given that the schema is trivially empty and the description doesn't need to explain any arguments.

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 uses a specific verb ('List') and resource ('all users in the Notion workspace'), clearly distinguishing this from sibling notion_get_user which fetches a single user. The scope is explicit, and the purpose 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?

It provides clear context for when to use the tool by explaining that user IDs are needed for people properties and @mentions, implying the use case for obtaining a complete user list. It does not explicitly mention exclusions or alternative tools, but the context is clear.

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 carries the full burden. It discloses the nature of the operation ('List') and the specific output fields, which is behavioral context. It does not mention side effects or permissions, but for a read-only listing operation, 'List' and the output description give sufficient 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 with no filler. The first sentence states the purpose and output; the second provides actionable integration with other tools. Every part earns its place, and it is front-loaded with the core action.

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?

With a single required parameter, an output schema present, and a clear description of what the tool returns and how to use it with sibling tools, the description is complete. It covers purpose, usage, and follow-up actions without needing to explain return values (which the output schema handles).

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 has a single parameter (database_id) with 0% schema description coverage, so the description must compensate. The description implies that database_id identifies the Notion database whose views are listed, but it does not provide format, validation, or any additional meaning beyond the schema itself. Given the simplicity of the parameter, this is adequate but not exceptional.

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 uses a specific verb ('List') with a clear resource ('views defined on a Notion database') and enumerates the output fields (name, type, id, saved filter/sorts). It clearly distinguishes this tool from siblings like notion_query_database or notion_describe_database by focusing specifically on views.

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 and how to chain it with related tools ('Use the view id with notion_query_view... or with notion_update_view / notion_delete_view'). This provides clear guidance on the tool's role and alternatives, making it easy for an agent to decide when to invoke 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?

With no annotations provided, the description must carry the full burden. It outlines the mechanics (new row for database) but does not disclose side effects such as whether the page is removed from its original location, permission requirements, or whether the operation is reversible. This is a significant gap for a mutation tool, similar to the update_drive example.

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 compact, using a single-purpose sentence followed by a clean parameter list. Every line earns its place; there is no fluff. The formatting makes the parameter semantics easy to scan.

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 simplicity, the description covers the core action and parameters adequately. However, it omits potential edge cases (e.g., circular moves, self-parenting) and does not describe the output or failure modes, though an output schema exists. More detail on side effects would make it more complete, but it's minimally viable.

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 description adds substantial meaning beyond the raw schema by explaining each parameter: page_id identifies the page, new_parent_page_id specifies the target page, and new_parent_database_id specifies the target database. It also clarifies the 'as a new row' behavior and the exclusivity constraint, which are not present in the schema. Schema description coverage is 0%, so this compensation is essential.

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 opens with a clear verb+resource: 'Move a Notion page to a new parent page or database.' This distinguishes it from sibling tools like create/update/archive. It leaves no ambiguity about the tool's core 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 provides specific guidance on how to use the two parent parameters, noting that only one should be set. While it doesn't explicitly mention alternatives, the unique 'move' operation makes alternatives unnecessary. It gives clear context on the condition for using each parent argument.

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 disclosing behavior. It reveals a key constraint ('Rejects any filename containing path separators') and provides context about the daily TTL sweep and shared-slot semantics. However, it does not explicitly state return values, error handling on missing files, or permanence of deletion, which would be useful for a destructive 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?

The description is three sentences, each earning its place: the first states the operation, the second provides usage context and alternatives, the third adds a critical constraint. It is front-loaded with the primary action and avoids any filler.

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 simplicity (one parameter, single file deletion) and the presence of an output schema, the description covers the key behavioral and usage aspects. It explains the shared-mount context, the TTL sweep, and the exclusion of path separators. It is sufficiently complete for an agent to select and invoke the tool correctly, though it could mention side effects or idempotency.

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 only defines a 'filename' string with no description (0% coverage). The description compensates by specifying that it must be a 'bare filename' and that path separators are rejected, adding crucial meaning beyond the schema. Still, it could offer examples or clarify what happens if the file doesn't exist, but the essential semantics are covered.

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 ('Delete a single file'), the resource ('from the cross-MCP shared mount'), and the method ('by bare filename'). It also distinguishes itself from sibling tools by explicitly naming the alternative (notion_purge_shared_files) and explaining why this tool is safer.

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?

It provides explicit when-to-use guidance: 'Use this after a successful upload to free the shared slot' and contrasts with the alternative tool 'notion_purge_shared_files with max_age_hours=0' which could wipe unrelated handoffs. This gives clear usage direction and warns against misuse.

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 that only regular files are touched, subdirectories are left alone, and dry_run can list victims before deletion. This adds meaningful behavioral context beyond the raw schema, though it stops short of explicitly stating that the deletion is permanent and irreversible.

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 organized into three short paragraphs: the core action, the use case/alternative, and operational details. Every sentence adds value, and the most important information is front-loaded. No filler or redundancy.

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 an output schema exists, the description covers purpose, usage, behavioral constraints, and parameters well. One minor ambiguity remains about whether the tool recurses into subdirectories (it says 'subdirectories are left alone' but not whether files inside them are candidates), but overall the description is sufficiently complete for correct invocation.

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?

Despite 0% schema description coverage, the description fully explains both parameters: max_age_hours defines the age threshold for deletion, and dry_run switches to listing victims without deleting. This adds clear semantic meaning beyond the bare schema types and defaults.

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 opens with 'Delete files from the cross-MCP shared mount' — a specific verb and resource — and adds the age condition 'modification time is older than max_age_hours.' This clearly distinguishes it from sibling tools like notion_purge_file by targeting the shared mount and bulk age-based cleanup.

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 says 'Use this to clean up attachments handed over from the companion google-accounts-mcp server once they've been uploaded to Notion' and contrasts it with a host-level TTL sweep, noting the tool is for proactive cleanup at workflow end. It provides clear context and intent, though it does not name alternative tools 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?

With no annotations, the description carries the full burden. It discloses important behaviors: pagination via opaque cursor with next_cursor token/end marker, the hard cap of 100, silent ignoring of unknown property names, and the always-shown title column. It does not mention error handling or rate limits, but the disclosed behaviors are substantial.

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 long but appropriately so for a tool with six parameters and JSON syntax. It is well-structured, alternating usage guidance with parameter definitions. Every sentence adds value—there is no fluff or repetition.

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 of pagination, filters, and property selection, the description covers all invocation essentials: pagination semantics, default/max limits, property filtering behavior, and JSON formatting. It also notes an output schema exists, so return values need not be fully described in text. This is complete for an agent to select and call the tool.

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 0%, so the description must fully compensate. It does: every parameter (database_id, filter_json, sorts_json, limit, start_cursor, properties) is explained with JSON examples, defaults, constraints, and usage nuances. The examples for filter and sort are especially valuable.

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 'Query a Notion database with optional filter, sort, and pagination' and explains it returns matching rows with their properties. This provides a specific verb and resource, and the mention of pagination and filtering distinguishes it from simple search or read tools. The sibling reference to notion_describe_database further clarifies its role.

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 instructs to 'Use notion_describe_database first to see the schema and property names', establishing a clear prerequisite workflow. However, it does not explicitly discuss alternatives or when not to use this tool (e.g., full-text search vs. structured query), so it earns a 4 rather than a 5.

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 carries the burden. It discloses the return shape ('title + id + url') and the limit constraint ('max 100'). However, it does not mention error behavior or permissions, which is a minor gap for a read-only query.

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?

Three short sentences, front-loaded with purpose, then usage, then parameters. No filler or redundancy.

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 (2 params, one required), has an output schema, and is well-differentiated from siblings. The description covers purpose, usage, and parameters adequately for an agent to select and invoke it correctly.

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 0%, so the description compensates by explaining view_id's provenance ('from notion_list_views') and limit's semantics ('max rows to return (max 100)'). This adds real meaning beyond the schema's type/default.

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 uses the specific verb 'Run' and identifies the resource as 'a database view's saved filter and sorts'. It explicitly differentiates from sibling notion_query_database by stating 'Use this instead of... when the view already encodes the filter you want'.

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?

Explicitly states when to use: 'Use this instead of notion_query_database when the view already encodes the filter you want'. Also implies when not to use (when custom filter JSON is needed), and directs users to notion_list_views for obtaining view_id.

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 of behavioral disclosure. It explains recursive fetching of nested blocks, the max_depth limit, and the behavior of include_block_ids, including how to use the resulting block IDs with other tools. This is more than a basic read operation, though it does not mention rate limits or potential large page considerations.

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 concise, front-loaded with the main purpose, and uses a clear structure separating the core function from parameter explanations. Every sentence earns its place with no redundancy or filler.

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 covers full functionality, return format, parameter details, and even points to related operations for block IDs. It is complete for a read tool with three parameters and an output schema, though it could optionally mention read-only safety or error scenarios, but these are not critical.

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 has 0% description coverage, but the description fully compensates by explaining each parameter: what page_id is and where to get it, the range and default for max_depth, and the effect and purpose of include_block_ids. This provides complete semantic meaning beyond raw schema types and defaults.

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 reads a Notion page's properties and content as markdown, which is a specific verb+resource. It distinguishes from mutation and search siblings, but does not differentiate from the similarly named sibling notion_read_page_markdown, so it falls short of full sibling 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 implies the tool should be used to read page content, such as the title, properties, and blocks, and mentions using block IDs for updates/deletes. However, it does not explicitly state when to use this tool over alternatives like notion_read_page_markdown or when not to use it, leaving usage guidance mostly implicit.

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 burden of disclosing behavior. It reveals that the tool 'uses the direct markdown API endpoint', is 'faster than block-by-block fetching', and 'returns Notion's own markdown representation including special tags'. This adds meaningful context about performance and output format, though it doesn't explicitly state read-only safety or error behavior.

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 concise and well-structured: three sentences cover purpose, implementation benefit, and an explicit alternative. Every sentence adds value, with no redundant or irrelevant content.

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 tool with a single parameter, clear purpose, and an existing output schema, the description is complete. It covers what the tool does, why it's useful, when not to use it (with a named alternative), and the parameter meaning. There are no significant 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 schema has 0% description coverage, so the description must compensate. It adds 'page_id: Notion page ID,' which is minimal and essentially repeats the schema title 'Page Id'. This provides only basic meaning and no additional format or context details, so the compensation is weak.

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's function: reading a Notion page's content as markdown. It distinguishes itself from sibling tools, particularly notion_read_page, by explicitly naming the alternative for block-level editing, making the purpose unambiguous.

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 explicit when-to-use guidance by saying 'For block-level editing (update/delete individual blocks), use notion_read_page with include_block_ids=True instead.' This names the alternative and gives a clear exclusion, along with a performance rationale for using this tool.

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 discloses key behaviors: default return is an MCP image content block, optional base64 JSON envelope, error handling in both modes, page indexing, and parameter ranges. It does not explicitly state read-only behavior, but rendering implies no mutation, and the error description adds 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?