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?

No annotations are present, so the description carries the burden. It discloses that this mutates an existing database and that a title property is mandatory in the schema, but says nothing about required permissions, whether the added data source can be removed later, or rate limits. An output schema exists, so return values need not be explained.

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?

Opens with the action and the disambiguating fact, then presents parameters in an aligned block. Every line carries information an agent needs; nothing is repeated from the schema.

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 3-parameter mutation with no annotations and a declared output schema, the description covers purpose, sibling routing, and all parameter meanings. Only the operational envelope (permissions, reversibility) is absent, which is a minor gap given the additive, low-risk nature of the 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 coverage is 0%, and the description compensates by documenting all three parameters, including the non-obvious constraint that schema_json must contain a title property and the format pointer to notion_create_database. The schema_json format itself is only described by analogy, leaving some inference.

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?

States a specific verb and resource ('Add another data source ... to an existing database') and immediately defines the concept as 'a second table with its own schema'. It also distinguishes itself from every sibling database tool by noting they operate on a database's FIRST data source.

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 line 'Most databases have one; the other database tools here operate on a database's FIRST data source' gives a clear condition that selects this tool over notion_update_database or notion_describe_database. It stops short of an explicit 'do not use this if...' exclusion, but the routing signal is strong.

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?

No annotations are provided, so the description carries the full burden. It usefully discloses that page_id may be any block supporting children, that position defaults to 'end', and the exact tab object shape, but says nothing about permission requirements, what happens with an invalid block ID or malformed JSON, or whether existing page content is affected.

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?

Front-loaded one-line purpose followed by a tight param list with a compact example; no sentence is filler and the example JSON substitutes for paragraphs of prose.

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 an output schema present, return values need not be described, and the parameter contract is complete. However, for an unannotated write tool the description should say something about permissions, failure modes, or interaction with existing page content; those gaps leave it adequate but not complete.

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

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

Schema description coverage is 0%, yet the description fully compensates: it explains the page_id semantics (page or any child-supporting block), gives a concrete JSON example for tabs_json with required/optional fields spelled out, and enumerates position's three accepted forms including the 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?

States a specific verb ('Add') plus a precisely defined resource ('a tab block (a row of tabs, each with its own content)'), so an agent knows exactly what will be created. It does not differentiate itself from content-insertion siblings such as notion_append_content or notion_insert_page_content, which is the only thing keeping it from a 5.

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 never says when to use this tool versus alternatives, nor any prerequisites or exclusions. Given siblings like notion_append_content, notion_insert_page_content, and notion_replace_page_content, an agent is left to infer that 'add tabs' is the choice when tabbed layout (not plain content) is needed.

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 well: it discloses that markdown is parsed into blocks, enumerates the supported markdown constructs, and notes that 'silent' suppresses the notifications this write would otherwise send. It does not cover permission requirements or size limits, but the core behavior of this mutation is well surfaced.

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?

Front-loaded with a one-line purpose, followed by a compact parsing note, a supported-syntax list, and per-parameter notes. The markdown feature list is slightly long but each item prevents a real ambiguity, so little is wasted.

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?

An output schema exists, so return values need not be described, and all four parameters are explained. What remains missing is permission/auth requirements and any content-size or error behavior for this write tool with zero annotation coverage.

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 and it does: page_id explains it can be any block supporting children, content is markdown text, position enumerates 'end'/'start'/block ID plus how to obtain block IDs via notion_read_page(include_block_ids=True), and silent is explained. Every parameter gains 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?

States a specific verb and resource ('Add markdown content to an existing Notion page') and clarifies scope ('existing'). However, it does nothing to distinguish itself from near-identical siblings such as notion_insert_page_content, notion_replace_page_content, and notion_update_page_content, which an agent must choose between.

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?

Implied usage is clear from 'existing page' (not for creating pages) and the position parameter describes insertion modes, but there is no explicit when-to-use guidance and no mention of when to prefer insert/replace/update siblings instead.

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, the description carries the full behavioral burden. It does disclose meaningful defaults (inline=False means a full-page database; title is optional for typed databases since they are named after their type) and that a title property is required. It is silent on permissions/integration access to the parent page, failure modes (name collisions, invalid schema), and whether the operation is reversible — significant gaps for a mutation tool with zero annotation coverage.

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

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

The one-line summary is front-loaded and each parameter block is clearly labeled. The 9-property schema_json example is long for a description, but it substitutes for absent schema documentation and illustrates several property types, so most of it earns its place; some pruning (e.g., Notes/Link/Assignee) would tighten it.

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?

An output schema exists, so return values need no explanation, and the description fully covers the non-trivial input surface including the typed-vs-custom fork and the required follow-up call. What's missing is authority/error context — whether the integration must already have access to the target page and what happens if schema_json is malformed.

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 carry all five parameters — and it does. It explains parent_page_id, title's conditional optionality, inline's True/False effect, database_type's three values and exclusivity with schema_json, and shows the full Notion API schema_json shape with a worked example plus the 'title property is required' constraint.

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?

Opens with a specific verb + resource + placement: 'Create a new Notion database under a page.' That distinguishes it from notion_update_database and notion_query_database by scope. It stops short of naming a sibling or stating when to prefer notion_create_page with a database, so it isn't a full 5.

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?

Gives concrete routing rules: database_type ('tasks', 'projects', 'skills') creates a typed database INSTEAD of schema_json, and the two 'cannot be combined'; plus a follow-up instruction to run notion_describe_database for exact property names. That is real when/when-not guidance, though it never addresses the create_database vs create_page/add_data_source boundary.

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 and does so well: it discloses async processing ('processing continues after this returns'), the required polling loop and terminal status, and the non-idempotency consequence ('calling it twice creates two sets of notes'). It also notes that Notion may rewrite the title during summarisation — exactly the surprises an agent needs warned about.

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?

Front-loaded with purpose and the polling contract, then a labelled parameter block. Every line carries information an agent would otherwise have to guess; nothing is padding.

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?

An output schema exists so return values needn't be explained, and the description still supplies the async lifecycle state to poll for, the source/parent-page coupling, and the non-idempotency caveat. Nothing essential for a correct call 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 compensate, and it documents all five parameters: the four source prefixes with their semantics, parent_page_id's file-sources-only constraint, the language hint format and auto default, and summarize=False behaviour. This is meaning well beyond the bare types in 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?

Opens with a specific verb+resource+output: 'Create AI meeting notes (transcript + summary) from a recording.' That cleanly separates it from the read/query meeting-notes siblings, which merely retrieve notes.

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 routes the agent to notion_read_meeting_notes for polling and warns it is NOT idempotent, plus spells out which source form goes with or without parent_page_id. It stops short of contrasting with adjacent tools like notion_upload_file or notion_extract_file_text, so no explicit 'when not to use'.

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 and does substantial work: 'silent: True skips the update, @mention and Person-property notifications this write would send' discloses the side effect of a mutation, and 'The template supplies the body, so leave content empty' flags a destructive interaction between two parameters. 'notion then processes as a background task' for very large native pages and the '(a preview)' warning on markdown_version v2 add further behavioral context. Missing: any statement of permission/access requirements or what happens on a failed write.

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?

Front-loads purpose and the parent_page_id vs database_id fork before the parameter glossary, so an agent can decide fast and read detail only for the branch it picked. The glossary form is dense but purposeful; the only marginal line is the content-format enumeration ('headings, lists, quotes, code blocks'), which is low-value relative to the rest.

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 an 11-parameter, no-annotation mutation tool this covers what an agent needs: which parameters are mutually exclusive, how template and content interact, what silent suppresses, and when to escalate to native_markdown. The presence of an output schema removes any need to describe return values.

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 compensate entirely — and it does, defining all eleven parameters with format examples: emoji literal, 'custom_emoji:<name-or-id>', 'icon:<name>[:<color>]', and 'start'/'end'/block-ID for position. It even spells out the exact properties_json shape for wiki verification, which the schema cannot convey.

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?

Opens with a specific verb+resource: 'Create a new Notion page with optional markdown content.' The two-branch routing (standalone page via parent_page_id vs database row via database_id) makes the tool's scope unambiguous. It stops short of naming the closest sibling alternatives (notion_append_content, notion_insert_page_content), so it is differentiated by implication rather than explicitly.

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 the selection condition between the two creation modes: 'For a standalone page under another page, provide parent_page_id' and 'For a database row, provide database_id and properties_json.' It also routes to siblings for sub-tasks (notion_list_custom_emojis for icon names, notion_list_templates for template IDs) and tells the agent when to pick native_markdown. It never says when NOT to use this tool (e.g. adding content to an existing page).

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?

With no annotations, the description carries the burden of behavioral disclosure. It usefully explains that the write is asynchronous and that the task ID came from the initiating tool, but it does not describe status semantics, polling expectations, task expiration, or whether the check is strictly read-only.

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 short and front-loads the core purpose and triggering condition. The parenthetical is slightly dense, but no sentence is wasted and the parameter note is directly useful.

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 one-parameter async-status tool with an output schema, the description covers what it does, when to call it, and where the task ID comes from. Additional details about polling or terminal states would help, but the core call path is sufficiently documented.

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 for the lone undocumented parameter. It does so by explaining that task_id is 'the task ID from that reply,' which gives the parameter real meaning beyond its type.

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 ('Check') and resource ('background write') and explicitly ties the tool to async writes initiated by notion_create_page or notion_replace_page_content. This clearly distinguishes it from sibling read/write tools.

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 states exactly when to use the tool: after a large create/replace call returns a task ID instead of finishing synchronously. It does not explicitly discuss when not to use it or polling behavior, but the triggering condition 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. 'Get' implies a non-mutating read, and the description does enumerate the returned fields (text, author, timestamps, thread), but it says nothing about permissions, behavior for deleted/inaccessible comment IDs, or error conditions — gaps that matter for a tool with zero annotation coverage.

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

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

Two short sentences, with the purpose front-loaded and the parameter note trailing usefully. The stray colon-prefixed 'comment_id:' line is slightly awkward but costs almost nothing.

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 one-parameter read-only getter with an output schema present, the description covers purpose, targeted entity, returned content, and ID provenance. Nothing an agent needs in order to call it correctly 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% and the single property is labeled only 'Comment Id', so the note that the ID comes from notion_get_comments or notion_add_comment adds genuine sourcing semantics the schema lacks. It doesn't describe ID format or validation, so not a 5.

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?

States a specific verb and resource ('Get a single comment by ID') and enumerates what it returns (text, author, timestamps, thread), which implicitly contrasts with the list-oriented notion_get_comments. It doesn't explicitly name a sibling as the alternative, so it stops short of a 5.

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?

Usage context is only implied by 'comment_id: from notion_get_comments or notion_add_comment', which tells the agent where to source the ID but not when to prefer this tool over notion_get_comments or the update/delete comment siblings. That is useful but partial routing 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.