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

With no annotations provided, the description carries the full behavioral burden. It discloses that unresolved mentions cause the call to fail, that no warning is returned, and that the response shape is { id, content }. This is meaningful transparency beyond the schema, though it does not address permissions or other 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?

Three sentences, no filler. The primary action comes first, the important failure caveat is second, and the return shape is last. Every sentence earns its place and the description remains compact.

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 comment-creation tool with no output schema and no annotations, the description covers the essential operational details: what the tool does, the expected return shape, and a critical failure mode. It is not exhaustive, but it is complete enough for an agent to invoke the tool correctly in most cases.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by spelling out the mention syntax @[Title](notion-url) and clarifying that this syntax is supported in inline comment text. This supplements the schema's simpler 'supports markdown inline formatting.'

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

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

The description opens with a clear verb and resource: 'Add a comment to a page.' It also differentiates itself from append_content by explaining a key mention-resolution difference, so an agent can distinguish this tool from a closely related sibling without inspecting 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 makes the primary use case clear—add a comment to a page—and provides a meaningful comparison to append_content regarding unresolved mentions. It does not enumerate all alternatives or edge cases, but the context is sufficient for an agent to choose this tool over sibling comment-related 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 behavioral disclosure burden. It meaningfully reveals per-entry results and that partial failures don't block the batch, which is important batch behavior. It doesn't address permissions or failure details of the whole call, but for a create operation this is reasonable 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?

Three short sentences with no filler. The core purpose is front-loaded, and each sentence adds useful information: batch creation, format reference, and failure behavior.

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

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

The description is adequate for a moderately simple batch-create tool. It covers the operation, the entry format, and the key behavioral nuance of partial failures. Minor gaps such as response shape details and any batch size limits are acceptable given the succinctness.

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 all three parameters are documented. The description mostly restates what the entries parameter already says about using the same format as add_database_entry, adding little new parameter-level meaning.

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

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

The description states a specific verb and resource: 'Create multiple entries in a database in one call.' It also clearly differentiates this from the singular sibling add_database_entry by emphasizing the batch nature.

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 batch context is clear: use this when creating multiple database entries at once. It does not explicitly state exclusions or name alternatives as a routing rule, but the intent is obvious enough for an agent to choose between this and the singular sibling.

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

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

With no annotations, the description carries the full burden. It discloses writable property types, notes date is start-only, and lists computed or unsupported properties that cannot be written. It doesn't discuss response format, failures, or permissions, but still provides substantial behavioral clarity.

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 structured well: purpose, prerequisite, type mappings, exclusions, and example. It is longer than average, but the density of actionable information justifies the length and it remains 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?

For a create operation with no output schema or annotations, the description provides preconditions, accepted value shapes, and unsupported properties needed to invoke it correctly. It doesn't describe response format or error behavior, but those are less critical for a straightforward creation call.

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?

Even though schema coverage is 100%, the description adds significant meaning beyond the schema by mapping each Notion property type to concrete JSON input shapes and giving an example object. It also clarifies unsupported property categories, greatly enriching the vague 'properties' parameter description.

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 'Create one database entry using simple key-value property inputs,' naming a specific verb and resource. The singular 'one' differentiates it from siblings like add_database_entries and update_database_entry.

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 explicitly directs agents to 'Call get_database first' to discover valid property names and select/status options, giving a clear prerequisite. It doesn't explicitly name alternative tools or when-not-to-use conditions, but the single-entry scope and property guidance make intended usage 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?

With no annotations provided, the description carries full responsibility for disclosing behavior, and it does so thoroughly: it explains server-side batching, rich text splitting, nested block handling, mention resolution fallback with a warning, and the exact return shape. This far exceeds typical MCP descriptions and leaves little hidden behavior.

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

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

The description is long but every sentence earns its place: purpose, conversion semantics, rate-limit handling, syntax compatibility, mention behavior, and return payload. It is front-loaded with the core purpose and contains no filler or redundant restatement of the tool name.

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 there is no output schema and no annotations, the description is remarkably complete—it covers behavior, limitations, error/warning conditions, return values, and even references a syntax guide for advanced usage. The only minor omission is explicitly stating insertion position, but 'append' already conveys that clearly.

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 adds meaningful context beyond the schema by explaining the markdown conversion behavior, pointing to the full markdown syntax guide, and detailing mention fallback behavior for the markdown parameter. This materially improves parameter understanding.

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 ('append'), a specific resource ('markdown content to an existing page'), and the semantics ('converts markdown into native Notion blocks'). It differentiates from sibling tools like create_page and replace_content by framing the action as additive to an existing page.

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

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

The description clearly indicates this tool is for appending to existing pages and explicitly notes that large documents can be sent in one call without pre-chunking, which guides when it is appropriate. It does not explicitly contrast with replace_content or create_page in a when-to-use/when-not-to-use list, but the context is clear enough.

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 does not disclose behavioral traits beyond the minimal verb. No annotations are present, so the description must cover behaviors like reversibility or side effects, but it fails to do so. The presence of the 'dry_run' parameter implies mutability, but this is not 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?

The description is a single sentence, concise and to the point. It could be improved by adding structured details, but it wastes no 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?

The description is minimal and does not address the tool's behavior in context. With sibling tools like 'archive_toggle', 'restore_page', and 'delete_*' operations, more context is needed to differentiate. The 'dry_run' parameter and return values are not described.

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

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

The input schema has 100% coverage with descriptions for both parameters. The tool description adds no additional meaning beyond the schema, so it meets the baseline of 3 without adding value.

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

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

The description clearly states the action (archive) and resource (page) within Notion. It is specific enough to distinguish from sibling tools like 'archive_toggle' by resource variation, but lacks further detail on what archiving entails.

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

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, non-archiving cases, or references to related tools like 'restore_page' or 'delete_database_entry'.

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

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

No annotations provided, so description bears full burden. Discloses recursive search, case-insensitive matching, archiving of container only (children not deleted), and behavior on missing title (returns available titles). Covers key behaviors but could mention if action is reversible.

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?

Four sentences, no fluff, front-loaded with main purpose. Each sentence adds distinct value: verb, search specifics, archiving behavior, edge case.

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

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

Covers matching logic, archival behavior, and missing title edge case. No output schema, so return value on success is not specified, but overall complete for a simple tool. Could mention permissions or reversibility.

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

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

Schema coverage is 100% with descriptions for all params. Description adds minimal extra meaning (e.g., 'case-insensitive trimmed text' reinforces title param, but overall adds little beyond schema). Baseline 3 is appropriate.

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

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

Description clearly states verb 'archive', resource 'one toggle by title from a page', and specifies matching logic including toggle blocks and headings. Distinguishes from siblings like restore_toggle and read_toggle.

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 for archiving a single toggle by title, but no explicit when-to-use vs alternatives (e.g., archive_page) or 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 fully carries the behavioral burden. It explicitly states that unknown property types 'fail with an explicit error. No silent drops,' which is critical for safe tool invocation. It also lists supported types and optional extras, ensuring the agent knows exactly what will happen.

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

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

The description is well-structured with a clear opening sentence followed by a bulleted list of property types. It is informative without being verbose, though it could be slightly more concise by omitting redundant wording (e.g., 'optional' repeated). Still, it earns 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?

Given no output schema and no annotations, the description is remarkably complete. It covers the core action, property type options, error handling, and even provides usage examples for extras. The agent has sufficient context to use 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?

The input schema has 100% coverage for parameters, so the baseline is 3. The description adds significant value to the 'schema' parameter by detailing supported property types, aliases, and extras (e.g., format for number, options for select). This exceeds the schema's basic array definition.

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 exact action: 'Create a database under a parent page.' It lists supported property types, which distinguishes it from sibling tools like create_page or add_database_entry. The verb+resource is specific 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?

The description provides clear context for when to use this tool (to create a database with specific property types). It does not explicitly mention when not to use it or provide alternatives, but the extensive type list implies applicability. A brief note about alternatives (e.g., use add_database_entry for adding entries) would improve it.

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

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

With no annotations, the description carries the full behavioral burden and does it well: it discloses server-side batching/splitting/nesting behavior, the stdio-only file:// upload constraint, and the return shape including block_map. It could add failure modes or permission requirements, but the major behavioral traits are 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 dense but free of filler. Every sentence adds operational value: purpose, server-side handling, upload constraints, syntax, and return format are all covered 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 write tool with no output schema, the description adequately covers the return object, batching behavior, and syntax rules, with parameter resolution delegated to the rich input schema. The main gaps are error/failure semantics and explicit routing guidance relative to sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful parameter-level context by defining the markdown syntax extensions (easy-notion://docs/markdown and @[Title](notion-url)) and clarifying when block_map is relevant. This goes beyond the schema's generic 'Markdown content' description.

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 is highly specific: 'Create a Notion page from markdown as native Notion blocks' names the verb, resource, input format, and conversion behavior. It also semantically separates itself from the sibling create_page_from_file by emphasizing in-memory markdown rather than file input.

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 context: the server handles batching, splitting, and nesting, so the agent should not pre-chunk input. It also documents supported syntax for uploads and mentions. It stops short of explicitly naming alternative tools or saying when not to use this tool.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses file validation, automatic 100-block batching, 2000-char splitting, deep-nesting handling, symlink resolution, workspace-root enforcement, and the exact return shape. This is unusually transparent for a tool definition.

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 every sentence earns its place. It front-loads the core purpose, then logically groups mode restrictions, file constraints, markdown reference, and return value. The bulleted restriction list improves scannability without wordiness.

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

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

For a complex tool with no output schema and no annotations, this description is remarkably complete: it covers prerequisites, environmental constraints, file validation rules, conversion behavior, return values, and edge-case options. An agent has everything needed to 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?

Although schema coverage is 100%, the description adds significant meaning beyond the schema: absolute-path requirements, workspace-root default and override, symlink resolution, file-size and encoding limits, and detailed behavior for collapse_soft_wraps with usage recommendations. The parameter descriptions are materially enhanced.

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-resource pair ('Create a Notion page from a local markdown file') and explicitly distinguishes itself from create_page by noting it produces the same result without sending file contents through the agent context. This makes its purpose unmistakable even among many sibling 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?

Usage context is explicit: it is STDIO mode only, unavailable over HTTP, and appropriate when file contents should not pass through agent context. It also names create_page as the equivalent alternative and provides concrete do/don't guidance for collapse_soft_wraps, plus a resource for supported markdown syntax.

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 notes unsupported types but fails to mention side effects, return values, or error scenarios. The minimal detail is adequate for a simple create operation but lacks depth for complex configurations.

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

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

Two concise sentences deliver all necessary purpose and usage notes without extraneous content. The front-loading of the core function is effective.

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 8 parameters, no output schema, and no annotations, the description is incomplete for a fully autonomous agent. While it covers the basic requirement and a key limitation, it lacks details on success behavior, error handling, and nested object structures.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds only a brief instruction to pass database_id and reiterates the dashboard exclusion seen in the schema, providing marginal added value.

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

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

The description clearly states 'Create a Notion database view,' specifying the verb and resource. It also distinguishes itself from sibling tools like delete_view and update_view by mentioning unsupported dashboard views, which helps avoid misuse.

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 instructs to 'Pass database_id,' indicating a prerequisite, and explicitly states 'Dashboard views and dashboard widget placement are not supported,' providing clear exclusion criteria. However, it does not compare with alternatives like update_view or query_view.

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

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

The description only states the action with no behavioral details like reversibility, side effects, or permissions; the dry_run parameter is not referenced, leaving the agent uninformed about preview capability.

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

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

Single sentence is concise and front-loaded with verb and object, but it could be more structured to include behavior or guidelines; still effective.

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

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

The description is insufficient for a deletion/archival tool; it lacks disclosure of destructive nature, reversibility, or the dry_run parameter's purpose; sibling tools like archive_page may overlap but are not differentiated.

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 provides full descriptions for both parameters (page_id string, dry_run boolean for preview), so description adds no additional value but also doesn't detract; baseline of 3 is appropriate.

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

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

The description uses specific verb 'delete' with parenthetical 'archive' to clarify the action on a 'database entry', which distinguishes it from sibling tools like archive_page or update_database_entry.

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 usage context is provided; the description does not differentiate when to use delete vs archive vs other database entry modifications.

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

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

With no annotations, the description must disclose behavioral traits. It notes the tool is destructive and requires confirmation, but does not elaborate on side effects, permissions, or reversibility. The schema adds some transparency via confirm and dry_run, but the description itself is minimal.

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

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

The description is very concise with two sentences, front-loading the purpose. No unnecessary words, making it easy for an agent to quickly grasp the tool.

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 three-parameter schema with thorough descriptions and no output schema, the description is adequate but lacks broader context such as when to prefer this tool over siblings, required permissions, or typical use cases. It meets minimum completeness but has gaps.

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

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

Schema description coverage is 100%, providing clear purpose for each parameter. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'Notion database view', making the purpose unambiguous. It distinguishes from siblings like delete_database_entry by specifying the resource type.

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

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

The description mentions that the tool is destructive and requires confirm to be true, providing a condition for safe use. However, it does not explicitly state when to use this tool over alternatives or provide exclusions, leaving some ambiguity.

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 behaviors: reads all blocks, omits unsupported types with warnings, handles AI meeting notes (converts to ordinary blocks), and notes that deep-duplication is not supported. This provides comprehensive transparency.

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

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

The description is detailed but not overly verbose; it front-loads the main purpose and uses examples for clarity. It could be slightly more concise, but the structure is logical 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?

Given no output schema or annotations, the description fully addresses the tool's complexity: it covers behavior, warnings, limitations, and edge cases (AI meeting notes, subpages). The agent has sufficient information 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?

Schema coverage is 100% with parameter descriptions. The description adds value beyond the schema by explaining the title default behavior and parent_page_id fallback resolution, which are not fully covered in the schema alone.

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 'Duplicate a page' and specifies the action: reads all blocks and creates a new page with same content. It distinguishes from siblings like move_page (moving) and create_page (creating from scratch) by detailing the duplication behavior and limitations.

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 implicitly guides usage by listing limitations (e.g., unsupported block types omitted, deep-duplication not supported), but does not explicitly state when to avoid the tool or name alternative tools. However, no other duplication tool exists among siblings, making the guidance adequate.

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

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

With no annotations, the description carries the full burden. It discloses that find_replace preserves uploaded files and untounched blocks, indicating non-destructive behavior. It could additionally mention irreversibility, but the provided info is strong.

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 no wasted words. The purpose is stated first, followed by valuable usage context. Perfectly front-loaded and 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?

Given the tool's complexity, full schema coverage, and lack of output schema, the description covers purpose, usage guidelines, and behavioral transparency adequately. No gaps remain.

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

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

Schema coverage is 100% and all parameters are well-described in the schema. The description adds value by giving usage examples (typos, URLs, terms) but does not significantly extend parameter meaning beyond the schema.

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

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

The description clearly states 'Find and replace text on a page.' and explicitly differentiates from sibling tool replace_content by highlighting efficiency for targeted changes like fixing typos, updating URLs, or renaming terms.

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

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

The description provides explicit when-to-use guidance ('targeted text changes') and when-not-to-use ('more efficient than replace_content'), along with behavioral notes like preserving untouched blocks.

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 it excels: it declares 'Read-only, makes no Notion API call, and never returns credentials.' This discloses safety and scope explicitly. It also states the exact return fields, adding transparency beyond typical descriptions.

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 well-structured sentences. The first fronts the purpose and key outputs; the second gives usage context and safety guarantees. Every sentence earns its place, and there is no 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?

This is a simple diagnostic tool with no parameters, no annotations, and no output schema, but the description supplies everything needed: what it does, when to call it, its read-only nature, and the exact return structure. Nothing is missing for an agent to use 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 tool has zero parameters, so the schema (empty) already covers them 100%. The description doesn't need to add parameter details, and the baseline for no parameters is 4. It adds no unnecessary parameter information, which is appropriate.

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

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

The description clearly states the tool 'Reports this server's own settings' and names specific elements: version, transport, workspace root, and visible tools count. It is a diagnostic tool distinct from the many content-focused siblings, so an agent can tell it apart without confusion.

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

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

The description explicitly says 'Call this when a file-path or configuration error occurs and you need the server's actual settings rather than a guess.' This provides a concrete trigger condition. It doesn't mention when not to use it or alternatives, but the tool is unique enough that no alternative is obvious; still, some negative guidance is missing.

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 disclosure burden. It communicates that this is a retrieval operation and specifies what the response contains, though it does not explicitly discuss errors, side effects, or permission expectations.

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 the purpose front-loaded and a concrete usage directive following immediately. Every sentence earns its place, and there is no redundant phrasing.

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 schema-lookup tool, the description plus the complete schema gives the agent the accepted identifiers, the output scope, and the follow-up tools. The absence of an output schema is mitigated by the explicit summary of return content.

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

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

Schema coverage is 100%, and both parameters are fully described in the input schema, including the page_id alias rule. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description names an explicit action and object: 'Get a database's schema' and specifies the returned content (property names, types, and select/status options). This clearly distinguishes it from query_database and other tools in the sibling list.

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 explicitly tells the agent to call this before query_database or add_database_entry to discover valid property names and values. It does not describe negative cases or alternatives exhaustively, but the usage context is clear.

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

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

No annotations are provided, and the description lacks any behavioral details (e.g., read-only, permissions, or side effects). For a simple get operation, a statement like 'Read-only, returns user object' would help.

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

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

The description is one concise sentence with no wasted words. It could be improved by adding return info without sacrificing conciseness.

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

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

For a parameterless tool with no output schema, the description is minimally adequate but fails to mention what the tool returns (e.g., user object). Adding a brief return description 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?

The tool has zero parameters, and schema description coverage is 100%. According to rules, 0 parameters earns a baseline score of 4, as no additional parameter documentation is needed.

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 'Get the current bot user' uses a specific verb ('Get') and a clear resource ('current bot user'), which distinguishes it from sibling tools that operate on pages, comments, databases, etc.

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?

While no explicit when-to-use or alternative guidance is provided, the tool's purpose is unique among siblings (only tool for bot user info), so implicit context is sufficient.

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?

Discloses the default output as a curated summary with specific fields (id, name, type, url, data_source_id) and the alternative full raw object. No annotations provided, so description carries the burden well.

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, no wasted words. Front-loaded with core action, followed by parameter tip.

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

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

Given no output schema and 2 parameters with full schema coverage, the description sufficiently explains what the tool returns and the key parameter behavior. Could mention prerequisite that the view ID must exist, but not critical.

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

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

Schema coverage is 100%, but description adds value by explaining the distinction between the default curated summary and the full object when include_config=true, beyond the schema's 'Return the full raw' statement.

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

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

Description uses specific verb 'Retrieve' and resource 'Notion database view by ID', clearly distinguishing from sibling tools like create_view, delete_view, update_view, list_views.

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

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

Provides a usage hint for the include_config parameter but does not explicitly state when to use this tool versus alternatives (e.g., list_views, query_view). The context is adequate but lacks exclusions or when-not-to-use 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, and the description does not disclose behavioral traits such as whether it returns all comments or paginated data, ordering, or required permissions. The description carries the full burden but fails to provide this context.

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

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

One succinct sentence that directly states the tool's purpose with no extraneous information.

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

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

The description is minimal but sufficient for a simple list tool with one parameter. However, it lacks details on pagination, sorting, or comment threading, which could be relevant.

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

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

Schema coverage is 100% with a single parameter 'page_id' described as 'Page ID'. The description adds no extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description 'List comments on a page.' clearly identifies the action (list) and resource (comments on a page), distinguishing it from sibling tools like add_comment or list_pages.

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

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

No guidance on when to use this tool versus alternatives (e.g., search_in_page for filtered comments) or when not to use it. The description does not provide usage context.

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

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

No annotations exist, so description must cover behavior. It discloses that the tool lists accessible databases, implying read-only and access control, but omits details like error handling, rate limits, or whether results are ordered.

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

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

Two sentences, front-loaded with purpose, no extraneous words. Efficient 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?

For a zero-parameter list tool with no output schema, the description adequately explains what it returns and suggests a next action. Could mention empty results or errors, but is sufficient for typical use.

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

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

Input schema has 0 parameters with 100% coverage; baseline is 4. Description adds no parameter info, but none is needed.

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

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

Description clearly states verb "List" and resource "databases", specifies scope "all databases the integration can access", and distinguishes from sibling list tools (e.g., list_pages). Offers a concrete next step: use get_database on results.

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 clear context by stating the action and return values, and implicitly guides to use get_database for schema. However, no explicit when-not or alternative specifications.

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 behavioral burden. It usefully discloses timestamp formatting (ISO-8601, rounded to the minute), the fact that last_edited_time updates on content and property edits, and the returned row structure. It does not mention pagination or ordering, but the disclosed details are meaningful and not redundant.

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 and front-loaded: the primary action appears first, followed by the returned fields and a useful timestamp caveat. Every sentence adds value, and there is no 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?

For a simple one-parameter read tool with no output schema, the description adequately covers what the result contains and important timestamp nuances. It could also mention pagination, sorting, or whether archived pages are included, but the core invocation and return semantics are sufficiently specified.

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%, and the parameter's schema description ('Parent page ID') already explains its role. The tool description adds no further parameter-level detail such as ID format or validity rules, 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 clearly states the action ('List child pages under a parent page'), identifies the target resource, and lists the returned fields. This makes the tool's purpose concrete and easily distinguishable from siblings like list_databases or list_views.

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

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

The description makes clear this tool is for listing child pages directly under a given parent page. It does not explicitly name alternatives or state when not to use it, but the parent-page scoping and single required parameter imply the correct usage context.

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

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

Without annotations, the description does not disclose any behavioral traits such as read-only nature, permission requirements, or output characteristics. It provides no additional behavioral context beyond the implied listing 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 a single sentence, containing no unnecessary words. Every word is purposeful, efficiently conveying the tool's function.

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 (no parameters, no output schema), the description is adequate but minimal. It lacks details about pagination, sorting, or potential filtering, which could be useful context for the agent.

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?

There are no parameters, so schema coverage is effectively 100%. The description adds no parameter details, but none are needed. The baseline for zero parameters is 4, as the description adequately covers the schema's emptiness.

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

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

The description clearly states the action (list) and the resource (workspace users), making the purpose unambiguous. However, it does not differentiate from sibling list tools like list_pages or list_databases, which share similar verb-noun construction.

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

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

No guidance is provided on when to use this tool versus alternatives. With many list tools available, the description lacks any context about prerequisites, scope, or exclusions.

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

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

Discloses return format (curated summary with fields, pagination cursors) and the effect of include_config, but does not explicitly state that the tool is read-only, which is important given no annotations.

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

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

Two sentences, each with essential information: purpose, parameter constraint, return format, and configuration option. No wasted 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?

Covers main return structure and pagination, but lacks default page_size, error handling, or explicit mention of optional parameters. With no output schema, a bit more detail could be beneficial.

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?

Adds meaning beyond schema by clarifying the exclusivity of database_id/data_source_id and the behavior of include_config. Schema coverage is 100%, so a 3 is baseline; the description provides added value.

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

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

The description clearly states it lists Notion database views and specifies the mutually exclusive parameters (database_id or data_source_id). However, it does not differentiate from sibling tools like get_view, query_view, or create_view.

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 specific guidance on parameter exclusivity and the include_config option, but no explicit guidance on when to use list_views versus alternatives like query_view or get_view.

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

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

No annotations provided; description fails to disclose side effects (e.g., child pages, permissions) or behavioral constraints.

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

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

Single sentence, front-loaded, no extraneous content.

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

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

Adequate for a simple two-parameter tool, but lacks detail on expected behavior or 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 coverage is 100% with clear descriptions; tool description adds no extra meaning beyond schema.

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

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

Description clearly states action (move), resource (page), and target (new parent page), distinguishing it from sibling tools like duplicate_page 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?

No guidance on when to use this tool vs alternatives (e.g., duplicate or archive), nor any prerequisites or limitations.

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 behavioral burden. It discloses the response shape, warning behavior, max_property_items cap, truncated_properties emission, and links to relevant docs. It stops short of explicitly stating read-only behavior or error handling, but overall it is transparent for a query tool.

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

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

The description is front-loaded with a concise purpose, followed by usage guidance and a compact response-shape explanation. Each sentence earns its place, including the links to edge-case documentation.

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 6-parameter query tool with no output schema, the description covers the response format, parameter usage, and important edge-case behavior. It could optionally explain top-level result pagination, but the linked docs and warning details make it sufficiently complete for an agent to invoke 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 covers 100% of parameters, so baseline is 3. The description adds value by explaining text search fields, advising get_database for advanced filter options, and detailing max_property_items behavior beyond the schema.

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

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

The description clearly states the tool queries a database and lists the available operations: filters, sorts, and text search. It differentiates from siblings like query_view by specifying the resource as a database, though it does not explicitly name the 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?

Provides practical guidance on when to use text search versus advanced filters, and instructs the agent to call get_database first for valid property names. It does not explicitly contrast with query_view or state exclusion criteria, but the in-tool routing is clear and actionable.

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, so description carries burden. It discloses the create-fetch-delete lifecycle, which is important behavioral context. However, it doesn't mention error states, permissions, or side effects beyond deletion of the temporary query.

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

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

Single sentence front-loading the core action. Every word is necessary and no filler. Highly efficient.

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

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

Adequate for a 3-parameter tool with no output schema. The lifecycle is explained, but lacks detail on return format or error handling. Given the absence of output schema, some expectation for return structure description is unmet.

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

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

Schema coverage is 100% with basic descriptions. The tool description adds no additional meaning beyond the schema. At baseline, no value added.

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

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

Description clearly states verb+resource: 'Query a Notion database view.' It adds lifecycle detail (creates, fetches, deletes) which distinguishes it from a simple read. However, it doesn't explicitly differentiate from sibling tool 'query_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?

No guidance on when to use this tool versus alternatives like 'query_database' or 'get_view'. No exclusive or prerequisite conditions mentioned. The description only states what it does, not when to choose it.

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

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

No annotations are provided, so the description fully bears the burden of disclosure. It comprehensively covers behaviors: recursive children for containers, error for unsupported root blocks, omission with warnings for nested unsupported types, rendering of AI meeting-notes as synthetic toggles with warnings, and exclusion of transcripts. No missing critical traits.

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 with four sentences, each adding value. The main purpose is front-loaded. Minor redundancy could be trimmed, but overall it is efficient 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 complexity of block reading (multiple block types, recursive containers, unsupported types), the description covers key behaviors. No output schema exists, but the description partially compensates by mentioning markdown and warnings. Lacks structural details about the markdown output format.

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

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

The input schema has 100% description coverage for the sole parameter (block_id). The description adds no additional semantic meaning beyond restating 'by ID'. Baseline of 3 is appropriate as schema already documents the parameter adequately.

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

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

The description clearly states the tool reads one block by ID as markdown and includes details about container blocks and error handling. However, it does not explicitly differentiate from sibling tools like read_page or read_toggle, which reduces clarity for selection.

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 (to read a block by ID) but does not provide explicit guidance on when not to use it or when alternatives like read_page are more appropriate. No exclusions or contextual triggers are mentioned.

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

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

No annotations provided, but the description fully discloses key behavioral traits: recursive fetching, handling of unsupported block types with warnings, synthetic rendering of Notion AI meeting notes, and max_blocks counting rules. This compensates for missing annotations.

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

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

The description is well-organized with paragraphs and bullet points, front-loading the core purpose. Slightly verbose in places, but each sentence adds value. Could be compacted slightly without losing information.

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

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

Despite lacking output schema, the description covers the response structure (metadata, markdown, warnings) and directs to external resources for conventions. Given the tool's complexity and 5 parameters, the description is remarkably complete and self-contained.

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% but the description adds significant nuance beyond the schema: max_blocks boundary behavior for meeting-notes descendants, max_property_items default and truncation handling, and include_transcript inclusion scope. Each parameter is enriched with practical context.

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 explicitly states 'Read a page and return metadata plus markdown' and specifies recursive fetching, making the purpose clear. It distinguishes from sibling tools like read_block by focusing on entire page content with markdown conversion.

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 actionable guidance: warns against round-tripping markdown when omitted_block_types warnings are present, and clarifies when to use include_transcript. Does not explicitly list alternatives but the context is clear enough for correct invocation.

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 carries the burden of behavioral disclosure. It explicitly states case-insensitive heading matching, hierarchical boundary rules, handling of nested children, omission warnings for unsupported blocks, and synthetic rendering of Notion AI meeting-notes blocks with warnings.

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 paragraph that front-loads the purpose. It is concise but includes necessary behavioral details without being verbose.

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

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

The description covers key aspects of behavior (heading matching, boundary rules, children rendering, warnings) but lacks explicit details about the return format and error cases (e.g., heading not found). Given no output schema, it is moderately complete but has gaps.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds minimal additional meaning beyond confirming the case-insensitive matching behavior for the heading parameter. Per guidelines, a score of 3 is appropriate when schema coverage is high and description adds limited value.

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 purpose: to read a single page section by heading name. It uses a specific verb ('Read') and resource ('page section'), and distinguishes itself from siblings like update_section and read_page by referencing its unique behavior.

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 explains the tool's behavior in detail but does not provide guidance on when to use this tool over alternatives (e.g., read_page, read_block). There are no explicit 'when to use' or 'when not to use' statements.

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

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

No annotations provided, so the description fully covers behavior: recursive search, case-insensitive trimmed matching, missing titles returning available toggle titles, synthetic toggle rendering for Notion AI meeting-notes blocks with a warning, and exclusion of transcripts.

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

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

The description is concise, front-loaded with the main purpose, and every sentence adds value. It uses clear language without unnecessary repetition, making it efficient for an AI agent to parse.

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

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

Given no output schema, the description adequately covers input usage, special behaviors, and limitations (transcripts not included). It is complete for the tool's scope and complexity.

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

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

Schema describes page_id and title briefly. The description adds meaning by explaining how 'title' is matched (case-insensitive, trimmed text) and the recursive search behavior. This goes beyond the schema, though no per-parameter details are added for page_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 reads a single toggle by title from a page, specifying it searches recursively and matches plain toggle blocks plus toggleable headings. It distinguishes itself from siblings like read_block or search by focusing on toggles by title.

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 for reading a specific toggle by title but lacks explicit when-to-use or when-not-to-use guidance. It does not reference alternative tools like search or read_block for other scenarios.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers extensively. It discloses atomicity, block-ID preservation, unmatched block replacement, dropped page types, bookmark/embed preview loss, and warning codes. It also describes the dry-run behavior and response shape, so the agent knows exactly what to expect.

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 every sentence earns its place, covering core behavior, preservation caveats, alternatives, parameter effects, docs references, and return values. The most important facts are front-loaded, with the atomic replacement behavior stated first and supporting details organized in a logical progression.

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?

This is a complex tool with five parameters, no annotations, and no output schema, yet the description is nearly self-contained. It covers the return value with success/truncated/warnings/block_map details, documents the dry-run response, names warning codes, and points to docs for further detail. The only minor gap is that not every warning code is enumerated, but the description references docs and gives representative examples, which is sufficient.

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, but the description adds meaningful semantic value beyond the schema. It explains the effect of collapse_soft_wraps on single line breaks, mentions that replace_content renders in-paragraph line breaks as separate paragraphs regardless of the option, and clarifies that bookmarks/embeds are written as bare URLs. These details help the agent choose parameter values correctly.

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 and resource: 'Replaces all page content with the provided markdown atomically (one Notion API call).' This makes the tool's core action unmistakable and distinguishes it from sibling tools like append_content, which adds rather than replaces content. It also clarifies that this is an all-page replacement, not a targeted edit.

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 explicit when-to-use and when-not-to-use guidance, including 'use duplicate_page first or edit those types via the Notion UI' when the source contains child_page subpages or other unsupported constructs. It also provides concrete parameter-level guidance, such as recommending collapse_soft_wraps for hard-wrapped prose files and warning not to use it when re-uploading content read from Notion. This routes the agent to alternatives and away from misuse.

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

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

No annotations are provided, so the description must carry the burden. It only states the action without disclosing permissions, failure conditions, or return behavior, which is insufficient for a mutation tool.

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

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

The description is a single sentence that gets straight to the point with no unnecessary words, fulfilling the requirement of being concise and front-loaded.

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 tool, the description is minimally adequate but does not explain return values or edge cases, which would be helpful given the absence of an 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 has 100% description coverage for 'page_id', and the description adds no additional meaning beyond what the schema provides. Baseline score is appropriate.

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

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

The description clearly states the tool restores an archived page, using a specific verb and resource. It distinguishes itself from the sibling tool 'archive_page' which performs the opposite action.

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 for unarchiving pages, but lacks explicit guidance on when to use this tool versus alternatives. However, the context of sibling tools makes it 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 provided; description lacks details on side effects, permissions, or consequences (e.g., what happens if block is not archived).

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

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

Two concise sentences with no filler, efficiently conveying key information.

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

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

Covers prerequisite and limitation, but lacks details on restore behavior (e.g., children, return value) given no 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?

Schema coverage is 100% with descriptions; description adds context for block_id but not significantly beyond schema. Baseline 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 clearly states it restores an archived toggle or toggleable heading by block ID, distinguishing it from siblings like archive_toggle.

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?

Specifies to use the block ID from archive_toggle and notes that Notion does not expose archived child enumeration, guiding when and how to use the tool.

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

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

No annotations provided, and description lacks disclosure of behavioral traits such as read-only nature, authentication needs, rate limits, pagination, or results format. For a search tool without annotations, more transparency expected.

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?

Extremely concise: two sentences with no filler. Front-loads the verb and resource, and includes a practical tip for using the filter. Every sentence earns its place.

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

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

Given the number of siblings and lack of output schema, the description is adequate but incomplete. It does not explain return values, pagination, or sorting. The workflow hint is helpful but not comprehensive for an agent to fully anticipate behavior.

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

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

Schema description coverage is 100%, but description adds value by explaining the 'databases' filter usage and linking to a workflow. The query parameter is minimally described; however, the description compensates by providing context beyond the schema.

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

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

Description clearly states 'Search Notion pages or databases' with specific verb and resource, and distinguishes from sibling tools like search_in_page. It provides actionable workflow (use filter 'databases' then get_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?

Explicitly says when to use the filter for databases and directs to get_database for schema details. Does not explicitly mention when not to use, but the sibling list implies alternatives.

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

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

No annotations are provided, so the description carries the full burden of revealing behavioral traits. It discloses that matching is case-insensitive and substring-based, but does not describe what is returned (e.g., block IDs, context, count), whether pagination exists, or any side effects. For a read-only tool, this is insufficient.

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, no redundant words, and front-loads the core purpose. Every phrase earns its place without being verbose.

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

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

Given no output schema, the description should cover what the tool returns, but it does not. It explains the search behavior and optional scope adequately, but leaves the return format and coverage (e.g., which block types) unstated. It is functional but not fully 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 100%, so baseline is 3. The description adds minimal detail: it only reemphasizes that the search is case-insensitive and that the optional scope is a toggle title. This does not add significant meaning 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 clearly states it searches raw Notion block plain text inside a page, with optional scoping to a toggle. This distinguishes it from sibling tools like 'search' (global search) and 'find_replace' (find and replace). The verb 'search' and resource 'page' are specific and directly convey the function.

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

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

The description implies when to use this tool: for searching within a page's raw block text, optionally restricted to a toggle. However, it does not explicitly state when not to use it or contrast with alternatives like the global 'search' tool. The guidance is clear but lacks exclusions.

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

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

No annotations are provided, and the description lacks details on behavioral traits such as side effects, permissions, or rate limits. It only states what it returns without clarifying if it modifies state.

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 sentence that is front-loaded and contains 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 simplicity of the tool (one parameter, no output schema), the description is fairly complete. It could mention the return format or error handling, but overall it suffices.

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

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

Schema coverage is 100% with one parameter described as 'Page ID'. The description adds no additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it returns a shareable URL for a Notion page, using a specific verb and resource. It distinguishes itself from sibling tools like read_page or get_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?

No guidance on when to use this tool vs alternatives. The purpose is implied, but there are no explicit when-to-use or when-not-to-use conditions.

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 disclosure burden and does so extensively: it reveals type lock-in, identity preservation, container-block depth limits, non-updatable type behavior, and deletion via archived. These are non-obvious behavioral traits an agent could not infer from the schema or tool name.

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

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

The paragraphs are dense but each sentence adds a distinct constraint or usage rule; there is no filler. The core purpose is front-loaded, followed by when to use it, type restrictions, edge cases for containers and non-updatable types, and finally deletion semantics.

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

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

For a complex tool with six parameters and no output schema, the description covers the full decision space: valid types, invalid types, deletion, container behavior, and alternatives. No necessary calling condition or constraint appears to be missing, so an agent has enough information to invoke it correctly and predict side effects.

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?

Although schema coverage is 100%, the description adds critical relational semantics: exactly one of markdown or archived is required, markdown must parse to a single block of the same type, and archived true means deletion. It also clarifies the checked parameter's relationship to to_do markdown syntax, going beyond individual field 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 opens with a specific verb and resource: 'Update a single block in place by ID,' and differentiates itself from multi-block tools by labeling these as surgical edits. It also clarifies what identity preservation means with concrete examples (deep-link anchors and inline-comment threads), leaving no ambiguity about 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?

It explicitly states when to use the tool ('fixing a heading, toggling a checkbox, rewriting one paragraph') and names alternatives for multi-block edits (append_content, replace_content, update_section). It also gives exclusion criteria for type changes, directing to replace_content or delete + append, so an agent can route accurately.

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, description fully discloses behavior: omitted properties unchanged, writable types enumerated, non-writable types listed. No contradictions.

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?

Well-structured with bullet points and clear sections. Front-loads purpose. Slightly verbose but every sentence is informative. Could be tightened slightly without losing clarity.

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

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

Given the complexity of updating various property types, the description is complete. Covers all writable types, non-writable types, and a prerequisite step. No output schema, but behavior is fully explained.

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%, but description adds significant value by explaining the properties object format and listing all writable property types with examples, going beyond the schema's brief 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 updates an existing database entry with key-value properties. It distinguishes from siblings like add_database_entry and delete_database_entry by specifying that only properties to change are passed, and omitted properties remain unchanged.

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 explicit guidance: call get_database first to see property names and valid options, pass only properties to change, and lists which properties are not writable. This answers when to use and what to avoid.

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 of behavioral disclosure. It does this exceptionally well, disclosing that omitted options are permanently removed, affected rows are silently reassigned with no signal, and that is_inline changes are unsupported. This is precisely the kind of destructive and surprising behavior an agent must know before calling.

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 lengthy but each sentence carries substantive guidance. It is front-loaded with the critical destructive warning, followed by the inline exception and a clear summary of what the tool does. The structure is slightly unconventional—the core purpose statement appears near the end—but the density and organization are strong enough that nothing feels 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?

For a complex mutation tool with zero annotations and no output schema, this description is exceptionally complete. It covers destructive edge cases, prerequisite calls, unsupported operations, accepted payload modes, documentation references, and required arguments. An agent has everything needed to invoke the tool correctly and avoid irreversible mistakes.

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 adds meaningful semantics beyond the schema, especially for the properties parameter: it explains full-list semantics for select/status options, the silent reassignment behavior, and the safe procedure for adding an option by first calling get_database. This extra guidance justifies a score above baseline.

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

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

The description explicitly states that this tool updates a database's schema: renaming properties, adding/updating/removing property definitions, changing the title, and moving to/from trash. This is a specific verb+resource and clearly distinguishes it from sibling tools like update_database_entry or update_view.

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 explicit usage context: 'Use after get_database', mandates reading the docs resource for modes and limitations, and warns that is_inline cannot be toggled on existing databases. It also explains the required parameters ('At least one of title, properties, or in_trash must be provided'), leaving little ambiguity about when and how to invoke the tool.

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

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

No annotations provided, so description carries burden. It discloses that file:// URLs are rejected in HTTP transport, which is important behavioral detail. Does not cover auth or side effects, but acceptable for a simple update.

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 sentences, front-loaded purpose, each sentence adds necessary detail without 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?

No output schema, but update operations often have simple responses. Description covers key behavioral nuances (URL types, transport). Missing potential partial update info, but adequate.

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%, yet description adds value: clarifies icon is emoji, and cover has transport-specific handling. This goes beyond 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 updates page title, icon, or cover, with specific detail on cover URL types. This verb+resource combination is distinct from sibling tools like archive_page or duplicate_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?

Provides specific guidance on when to use file:// vs https:// cover URLs and notes transport-specific rejection. However, it does not explicitly compare to siblings like update_block for content updates.

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 at all, the description carries the full disclosure burden and succeeds impressively. It opens with 'DESTRUCTIVE, no rollback,' details the mid-call failure mode (section partially or fully emptied, retry can fail with 'heading not found'), and specifies exact preserve_heading semantics: which attributes survive and which blocks are still destructively replaced.

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 every sentence earns its place and the most critical safety warning is front-loaded. The return-value enumerations for both normal and dry-run paths are dense run-on prose rather than structured lists, which is a minor readability cost for an otherwise information-dense definition.

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 high complexity (7 params, destructive semantics, two operational modes), zero annotations, and no output schema, this description is remarkably complete: it covers safety, failure modes, recovery, boundary semantics, preserve_heading nuances, efficiency trade-offs, mention syntax, and exact return shapes for both normal and dry-run invocations. Nothing an agent needs to call it safely 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?

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: heading boundary rules for H1 vs H2/H3, the requirement to include the heading in the markdown, the first-block edge case requiring matching heading type, the leading-heading-stripping behavior under preserve_heading, and the full dry_run return shape including would_delete_block_ids.

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: 'Update a section of a page by heading name.' It precisely defines the operation — finds the heading and replaces everything from that heading to the next section boundary — which unambiguously differentiates it from siblings like replace_content, append_content, and update_block.

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

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

The description names the closest alternative and the deciding condition: 'More efficient than replace_content for editing one section of a large page.' It also gives active safety guidance — 'For irreplaceable sections, duplicate_page the target first so you have a restore point' — and explains when preserve_heading is the right mode.

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, and it excels. It openly states the destructive nature, no rollback, that child block IDs change, and the risk of partial emptying on mid-call failure. It explains server-side handling of API limits (batching, splitting, nested passes) and clarifies that markdown becomes native blocks, not plain text. It also details the dry-run behavior and return structure. This is far beyond minimal transparency.

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

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

The description is lengthy but every sentence earns its place given the tool's complexity. It opens with the critical destructive warning, then states the core purpose, then details behavior, limits, and response. It is well-organized, flows logically, and avoids redundancy. The density of information is appropriate for a tool with this many nuances, and there is no 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?

Given the tool's destructive nature, API limit handling, markdown-to-native-block conversion, and multiple return scenarios (including dry run), the description covers all essential aspects. It explains what changes, how failures affect state, how to create a restore point, what the server does automatically, and the exact response shape. No output schema exists, so the description's detailed return documentation is crucial, and it provides it comprehensively.

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 complete descriptions for all six parameters (coverage 100%), so the baseline is 3. The description adds extra meaning primarily for the 'markdown' parameter—clarifying it is replacement body content, not a wrapper, and that the server converts it to native Notion blocks. It also clarifies the effect of 'collapse_soft_wraps' under specific scenarios. This goes beyond the schema's short descriptions and justifies a 4.

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: 'Update the body of one toggle by title from a page.' It clearly delineates scope by specifying it matches plain toggle blocks and toggleable heading_1/2/3 blocks, and distinguishes itself from siblings like replace_content by clarifying it updates a toggle's body, not renaming it or acting as a wrapper. The wording is unambiguous and directly relatable to the tool's 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?

While the description does not explicitly name alternative tools like replace_content or update_section, it provides rich context on when to use it: it targets a specific toggle by title, handles nested structures, and automates API limit batching. The warning about destructiveness and the recommendation to duplicate_page for irreplaceable content implicitly conveys when caution is needed. It lacks explicit 'when not to use' exclusions, but the context is strong enough for an agent to infer appropriate usage.

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

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

No annotations provided, so description carries full burden. It discloses that null values are forwarded to clear fields and that dashboard configuration is rejected, adding behavioral context beyond a simple 'update'.

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 efficient sentences front-load purpose and convey key behavioral details 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?

Covers null clearing and configuration rejection, but lacks mention of return value (no output schema) or error conditions. With 6 parameters and nested objects, more detail would be useful.

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

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

Schema coverage is 100%, baseline 3. Description adds value by stating 'Pass at least one update field' (required but not in schema) and clarifying null behavior for filter, sorts, and quick_filters.

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

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

Clearly states 'Update a Notion database view' with specific verb and resource. Additional info about passing update fields and clearing with null distinguishes it from create_view, delete_view, and other siblings.

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 clear context on how to use null values to clear filter, sorts, or quick_filters. However, does not explicitly mention when not to use (e.g., vs. query_view) or list alternatives.

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