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

With no annotations present, the description carries the full burden of behavior disclosure. It does reveal a genuinely non-obvious operational detail — the tool refuses/expects a file-path indirection rather than inline JSON — which prevents a likely failure mode. Beyond that, it discloses nothing about side effects, auth requirements, error behavior, or what gets modified on the parent block.

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

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

Two sentences with the high-priority operational warning front-loaded and marked with 'IMPORTANT'. No filler. The only minor waste is that the final clause 'Appends content blocks' is terse to the point of vagueness, though not redundant.

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 tool with full schema coverage and no output schema, the description covers the single most dangerous operational trap (the file-path indirection), which makes correct invocation achievable. It is nonetheless thin: no return-value expectations, no failure-mode hints, and no statement that block_id must reference an existing block with appendable children.

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

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

Schema description coverage is 100%, so block_id, file_path, and extract are already documented in the schema. The description adds marginal value by clarifying that the file must contain an array of children, but this largely repeats the schema's 'JSON must include a children array' note. Baseline 3 applies.

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

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

The description uses a specific verb ("Appends") plus a clear resource ("content blocks"), which distinguishes it from sibling tools like notion_retrieve_block_children (retrieval) and notion_update_block (mutation of existing properties). The target (a parent block) is not stated explicitly, but the tool name and the block_id parameter carry that meaning.

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 delivers a critical invocation requirement — write the JSON payload to a file first and pass file_path — which is essential for successful calls. However, it gives no guidance on when to choose this tool over alternatives such as notion_create_page or notion_update_block, and no exclusions or conditions are stated.

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 does disclose a critical non-obvious behavior: the JSON payload must be written to a file and passed via file_path, and it clarifies the creation scope. However, it does not mention permissions, idempotency, error behavior, or any side effects beyond the creation itself.

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 zero filler. The most urgent operational requirement (write JSON to file first) is front-loaded in all caps, and the core action is stated immediately after. Every word contributes.

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 two-parameter tool with 100% schema coverage, the description covers the essential non-obvious requirement (file-based payload), the required payload fields, and the resource being created. It does not explain the structure of the parent object or what happens after creation, but the schema and extract parameter cover most of the remaining operational context.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces that the file must contain 'parent', 'properties', and optionally 'title' but adds no meaning beyond what the file_path parameter description already provides. No additional parameter semantics are introduced.

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

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

The description states a specific verb and resource: 'Creates a database as a subpage in a specified parent.' This clearly distinguishes it from sibling tools like notion_create_page and notion_retrieve_database, and the parent/subpage scope adds precision beyond the tool name.

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 no guidance on when to use this tool versus alternatives among the siblings, such as notion_create_page or notion_update_database. The 'IMPORTANT' instruction explains how to call the tool (write JSON to a file first) but does not cover when it is the right choice or when another tool should be preferred.

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 does disclose the most critical non-obvious trait: the tool requires a file-first workflow and will not accept an inline JSON body. This is exactly the kind of hidden behavior that causes agent failures. It could additionally note side effects like duplicate creation on repeat calls, but the key behavioral trap is 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?

Two sentences with zero wasted words. The critical warning is front-loaded in caps, and the purpose statement follows immediately. Every element earns its place, and the structure guides attention to what matters most.

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 two-parameter tool with fully covered schema, the description is nearly complete: it states the essential workflow, the payload requirements, and the creation context. The extract parameter in the schema already addresses return-field behavior, so the absence of an output schema is not a gap. Only minor details like failure behavior are 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 100%, so the schema already documents both file_path and extract parameters well. The description reinforces the file_path requirement with emphasis and reiterates the payload structure, but adds little semantic value beyond what the schema provides.

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

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

The description states a specific verb and resource ('Creates page') with clear scope ('in database or as subpage'). This cleanly distinguishes it from siblings like notion_retrieve_page, notion_update_page, and notion_create_database without needing to inspect schemas.

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 clear operational guidance on the required workflow (write JSON payload to file, then pass file_path), but it never states when to prefer this tool over alternatives or when not to use it. Usage context is implied by the 'creates' framing rather than explicitly stated.

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

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

The parenthetical is a genuine behavioral disclosure: deletion is implemented as setting in_trash=true, implying soft-delete semantics rather than permanent destruction. However, with no annotations provided, the description carries the full burden and leaves side effects such as child blocks, permissions, reversibility, and error behavior unstateed.

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

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

The description is a single front-loaded sentence: verb, object, then the valuable in_trash qualifier. Every word earns its place and there is zero wasted 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?

For a low-complexity two-parameter tool, the schema covers parameters and the description covers the core operation. Yet with no annotations and no output schema, there is no guidance on prerequisites, side effects, or error cases, so the definition is adequate but incomplete.

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

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

Schema coverage is 100%: block_id and extract are both documented, and the extract description even explains default and 'none' response behavior. The description adds no parameter-level detail beyond the word 'block,' so the schema does the heavy lifting.

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

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

The description names the exact verb and resource ('Deletes a block') and adds the non-obvious qualifier 'sets in_trash: true,' which clarifies this is a soft-delete/trash operation. This distinguishes it clearly from sibling tools that retrieve, update, create, or append blocks.

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

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

There is no when-to-use guidance, no when-not-to-use conditions, and no reference to alternatives among the siblings. The only usage signal is the verb itself, so an agent must infer when this tool is the right choice.

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 full burden. It does disclose that the operation returns pages and supports pagination, but does not mention whether it is read-only, any side effects, permissions, or how pagination is performed. This is a minimal but accurate behavioral overview.

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 deliver the core message without fluff: querying with filters/sorts, returning pages, and pagination support. It is concise and front-loaded with the primary purpose.

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

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

With no output schema and no annotations, the description correctly identifies the return type and key capability. Minor gaps exist around pagination mechanics and default extract behavior, but the schema covers the extract default, making the description complete enough for most agents.

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 already describes all parameters, including the important extract default behavior and page_size max. Since schema_description_coverage is high, the baseline is 3, and the description itself adds no extra parameter-level meaning beyond what the schema provides.

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

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

The description clearly states the tool 'Queries database with filters/sorts' and that it 'Returns array of pages (results)', which distinguishes it from retrieving a database object or searching. It names the primary verb and resource, but does not explicitly differentiate from sibling tools like notion_retrieve_database or notion_search.

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

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

The phrase 'Queries database with filters/sorts' implies the primary use case: querying a database to get matching pages. However, it does not provide explicit guidance on when to choose this over alternatives, nor any exclusions, so usage context is only implied.

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 behavioral burden. 'Retrieves' implies read-only intent, but the description does not disclose response behavior, extract effects, error cases, or permissions. It adds little beyond the operation name itself.

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

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

The description is one short, front-loaded sentence with no filler or repetition. Every word 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?

The tool is simple enough that the current description is minimally usable, but with no annotations and no output schema, it leaves sibling differentiation and expected-return context to inference. A sentence clarifying block vs. block-children retrieval would meaningfully improve completeness.

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

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

Schema description coverage is 100%, so the schema already documents block_id and extract clearly. The description adds no parameter-level meaning, so the baseline score of 3 applies.

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

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

The description names a specific verb and resource: 'Retrieves a block by ID.' This clearly identifies a single-block lookup operation. However, it does not explicitly differentiate from siblings like notion_retrieve_block_children or notion_delete_block, so it is clear but not fully distinguishing.

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?

There is no guidance on when to use this tool versus alternatives. It does not mention that children should be fetched with notion_retrieve_block_children, pages with notion_retrieve_page, or that update/delete operations have dedicated tools. Selection is left entirely to inference.

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 conveys that the operation is a read ('Retrieves') and that pagination is supported, which is useful. It does not mention response format, error behavior, or rate limits, but for a simple read operation the disclosed traits are reasonable.

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 zero wasted words. The core action is front-loaded, the parenthetical makes the content type concrete, and the pagination note is a valuable addition. It neither repeats the tool name nor pads with 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 schema is rich enough to cover all parameter semantics, and the description states the core operation and pagination support. However, with no output schema and no annotations, the description does not explain what the response looks like beyond the extract parameter's schema description. It is functional but slightly minimal for a tool with four parameters.

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 100% coverage with descriptive entries for all four parameters, including the extract behavior and pagination cursors. The description adds no parameter-specific information beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb 'Retrieves', a specific resource 'children blocks', and gives concrete exmples (paragraphs, headings, lists). The phrase 'of page or block' also signals that both container types are valid inputs. This clearly distinguishes it from sibling tools like notion_retrieve_block, which would fetch a single block rather than its children.

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 clearly implies usage: call this when you need the child blocks of a page or block. However, it does not explicitly mention when not to use it or point to any alternative tool, such as using notion_retrieve_block for the block itself. The context is clear, but the routing guidance is left implicit rather than stated.

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. The verb 'Retrieves' and the enumerated result set ('property definitions, title, description') make the read-only behavior and return scope clear. It does not mention auth or failure modes, but for a simple retrieval tool that is not a serious gap.

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?

One sentence with no filler: every word earns its place. The semantic content is front-loaded: 'Retrieves database schema' comes first, followed by the concrete parts of that 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 two-parameter read tool with a fully documented schema and no output schema, the description plus schema is sufficient: it identifies the resource, the required parameter, and the response categories. It could add an explicit pointer to notion_query_database for database contents, but that is a usage nicety rather than a completeness gap.

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

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

Schema description coverage is 100%: both database_id and extract have explicit descriptions, including the extract special values. The description adds no parameter-level meaning beyond confirming that the target is a database, so baseline 3 applies.

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

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

The description names a specific verb ('Retrieves'), a specific resource ('database'), and a precise object ('schema: property definitions, title, description'). This clearly separates it from sibling retrieval tools like notion_retrieve_page and notion_retrieve_block, and from notion_query_database which retrieves database rows/content.

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 usage when schema metadata is needed, but it does not explicitly state when to use this tool over alternatives such as notion_query_database for contents. The usage context must be inferred from the word 'schema' rather than being directly stated.

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 behavioral burden. The verb 'Retrieves' signals a non-mutating read and the field list clarifies scope, but it does not disclose response format, error behavior, authentication requirements, or rate-limit 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 one compact sentence with no filler. It front-loads the verb and resource, then lists the scoped fields, making it immediately scannable and informative.

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 read operation with two parameters and 100% schema coverage, the description is largely complete: it states the operation, the target resource, and the categories of returned data. It lacks explicit alternatives and output shape details, but those are not critical for straightforward 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?

Schema description coverage is 100%, so the schema already documents both page_id and the extract behavior in detail. The description adds no meaningful parameter semantics beyond what the schema provides, warranting the baseline score of 3.

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

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

The description uses a specific verb ('Retrieves') and resource ('page metadata'), then enumerates the exact metadata categories: properties, parent, timestamps, archived status. This clearly distinguishes it from sibling tools like retrieve_block or retrieve_database.

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: when you need page metadata. However, it gives no explicit guidance on when not to use it or which sibling alternative to choose, such as notion_search for finding pages or notion_retrieve_block for block content.

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

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

The description discloses search-by-title behavior, object type filtering, and last_edited_time sorting, which adds context beyond the tool name. With no annotations, it doesn't mention pagination, result limits, or whether search is full-text, but the core non-destructive search 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?

Two short, front-loaded sentences convey the primary action, resource, and key options without redundancy. Every word 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 search tool with no output schema, the description covers the essential operation and primary parameters. It omits workspace scope and return shape nuances, but the schema documents the extract parameter, reducing the need for description to explain response handling.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by linking query to 'by title', explaining filter values (page/database), and clarifying the sort timestamp, which enriches the bare 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 searches pages/databases by title, which is a specific verb and resource. It does not explicitly differentiate from sibling notion_query_database, but the search scope over pages/databases is evident.

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 usage when you need to find pages or databases by title, and mentions filtering and sorting options. However, it gives no explicit guidance on when to prefer this tool over alternatives like notion_query_database or notion_retrieve_database.

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

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

The file-first workflow requirement is a genuinely valuable non-obvious behavioral disclosure, emphasized with 'IMPORTANT' and 'MUST,' which prevents a likely failure mode. However, with zero annotations provided, the description carries the full burden and fails to disclose update semantics (merge vs. replace), effects on existing block content, or response behavior — significant gaps for a mutation tool.

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

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

Two sentences with the critical constraint front-loaded and zero wasted words. The structure is efficient, though the purpose clause is so terse that the description under-uses its available space for behavioral context.

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

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

For a mutation tool with no annotations and no output schema, this description is thin: it covers the biggest gotcha (file requirement) but omits update semantics, expected payload shape, and selection context. An agent could invoke the tool correctly but cannot predict its behavior or side effects with confidence.

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

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

Schema description coverage is 100% — all three parameters (extract, block_id, file_path) already carry descriptions, so the baseline is 3. The description reinforces the file_path workflow and its mandatory status but adds no new semantic meaning about any parameter beyond what the schema already provides.

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

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

The description states 'Updates a block,' which gives a clear verb and resource, but this essentially restates the tool name (notion_update_block) without specifying what aspects of a block can be updated (content, properties, archived status, etc.). It differentiates from sibling read/delete tools only through the naming convention itself, not through descriptive content.

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

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

The description provides a procedural constraint ('You MUST write the JSON payload to a file first') but no guidance on when to choose this tool over alternatives like notion_update_page, notion_append_block_children, or notion_delete_block. There are no when/when-not statements or conditions directing tool selection.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It prominently discloses a critical behavioral requirement: the JSON payload must be written to a file first and the file path passed. This is essential for correct invocation. It also implies a write operation via 'Updates'. However, it does not disclose what the response contains or any side effects on existing properties, which could be relevant.

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 zero redundancy. The critical file-path instruction is front-loaded with an IMPORTANT marker, making it impossible to miss. Every word serves a purpose and the structure is efficient.

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

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

The description captures the essential calling convention and purpose, but omits guidance on when to choose this tool over similar ones, expected return format, and any behavioral nuances (e.g., whether existing properties are merged or overwritten). Given the absence of an output schema and the presence of a relevant extract parameter, additional context on return values would improve completeness.

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

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

Schema coverage is 100%, so parameters already have descriptions. The description adds meaningful value by explaining what the file_path should contain ('JSON should include title, description, or properties'), which directly clarifies the expected payload structure beyond the schema's generic 'Path to file containing updates (JSON)'. This compensates for the schema's brevity on content.

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 a specific action ('Updates') and a specific resource ('database') with a clear scope ('title, description, or properties'). This distinguishes it from sibling tools like notion_update_page and notion_update_block. The purpose is immediately clear and 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?

No guidance is provided about when to use this tool versus the many sibling tools. It does not mention scenarios, alternatives, or exclusions. The only contextual hint is the resource type ('database'), but no explicit 'use this when...' statement exists.

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 behavioral disclosure burden. It does disclose the mutation scope and the mandatory file-path worklow, which is valuable. However, it does not describe side effects such as whether existing properties are overwritten, whether archiving is reversible, or what happens on failure.

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 short, purposeful sentences with no fluff. The critical operational constraint is front-loaded, and the function statement follows immediately. An agent can parse the must-do action and the tool scope in one pass.

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 moderately complex mutation tool with all parameters documented in the schema, this description covers the essential file-based invocation worklow and the accepted update payload. The 'extract' parameter description already handles response-field expectations, so the absence of an output schema is not a significant omission. Lack of sibling routing is a minor gap but was already reflected in usage_guidelines.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description adds meaningful value by requiring a preliminary write of the JSON payload to a file and by reinforcing that the JSON should contain 'properties', 'archived', 'icon', or 'cover'. This clarifies the expected usage without merely restating the schema's 'Path to file' phrasing.

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 concrete verb 'Updates' and specifies the resource: page properties, archive status, icon, or cover. This clearly identifies it as a page-mutation tool and distinguishes it from the block/database siblings in intent, though it does not explicitly nod to any sibling alternative.

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 'IMPORTANT: You MUST write the JSON payload to a file first' instruction provides strong operational guidance on how to invoke the tool, but it does not explain when to choose this tool over alternatives like notion_update_block or when not to use it. Usage context is implied by 'Updates page properties...' rather than explicitly articulated.

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