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

With no annotations, the description carries the full behavioral burden, and it discloses nothing: no permission requirements, no note that this is an additive mutation, no ordering or positional semantics, and no per-request limits (Notion caps appended children). This is a mutation tool with zero behavioral context.

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

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

A single short sentence, front-loaded and free of filler. It is arguably too terse rather than wasteful, which keeps it from a 5.

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

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

The tool is simple (2 required, documented params) and has no output schema to explain, so the description is minimally adequate. Still, for an append mutation it omits anything about return behaviour, ordering, or limits that an agent would want before invoking it.

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 both parameters are documented in the schema itself, so the baseline of 3 applies. The description adds no format, nesting, or ordering detail beyond what the schema already states.

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

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

States a specific verb ('Append') and resource ('blocks') with the target ('parent block'), so an agent can tell it apart from update_block or get_block_children. It does not, however, explicitly name those siblings or clarify scope beyond the parent 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?

No indication of when to prefer this over notion_update_block or notion_create_page, and no prerequisites or exclusions. The agent must infer usage from the name alone.

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

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

With no annotations, the description carries the full burden, yet it discloses nothing about permissions required, whether commenting is supported on all page/block types, whether replies/threading are supported, or any rate limits. Only the mutation intent itself is conveyed.

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?

A single front-loaded sentence with no wasted words. It is efficient, though the extreme brevity leaves no room for the behavioral context a mutation tool needs.

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 annotations, no output schema, and a nested parent object, the description should say more about permission requirements and the expected result. As written it is too thin to call correctly in ambiguous 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 description coverage is 100%, so the two parameters (parent, rich_text) are already documented. The phrase "on a page or block" loosely maps to the parent parameter but adds no format or structural detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Create a comment") plus the target scope ("page or block"). It is clear on its own but never distinguishes itself from the sibling notion_get_comments or explains what makes commenting different from other write operations.

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 when-to-use guidance, no prerequisites, and no mention of the related notion_get_comments tool for reading existing comments. Usage is only implied by the verb "Create".

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 supplied, so the description carries the full disclosure burden. It reveals nothing about required permissions, whether the parent must be a page, what the created database contains, or any side effects of the write operation.

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

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

Three words with zero waste and a front-loaded verb, but the size reflects under-specification rather than disciplined conciseness. It neither buries nor spends words well because it says almost nothing.

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

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

For a mutation tool with nested object parameters, three required fields, no annotations, and no output schema, the description is wholly inadequate. An agent cannot determine prerequisites, permission needs, or the shape of a successful result.

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

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

Schema description coverage is 100%, so all five parameters (parent, title, properties, icon, cover) are already documented in the schema. The description adds no parameter meaning beyond the baseline, which is acceptable given the high coverage.

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

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

The description states a specific verb and resource ('Create a new database'), so the purpose is legible. However, it merely rewords the tool name (notion_create_database) and offers no differentiation from sibling database tools like notion_create_database_from_template or notion_duplicate_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?

There is no indication of when to use this tool versus notion_create_database_from_template or notion_duplicate_database, nor any stated prerequisites. No context or exclusions are provided.

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, but it does add one genuinely useful behavioral fact: only the schema is copied, not the template's rows. It is silent on permissions, whether views/properties are preserved, and reversibility of the mutation.

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?

A single front-loaded sentence with no filler; the schema-copying scope is stated immediately. It is minimal but nothing is wasted.

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

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

For a mutating, no-annotation, no-output-schema tool, the description is thin: it omits permission requirements, whether the resulting database inherits views/properties, and what a caller should expect back. The schema-only clarification is the main compensating detail.

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 (title, parent, template_database_id) are already documented in the schema. The description adds no syntax, format, or constraint details beyond that, so the baseline 3 applies.

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

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

Clear specific verb+resource: 'Create a new database by copying schema from a template database'. The 'from template' qualifier distinguishes it in spirit from notion_create_database and notion_duplicate_database, though no sibling is named explicitly.

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

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

No guidance on when to choose this over notion_create_database (blank database) or notion_duplicate_database (copy an existing one with content). The agent must infer the distinction from the name alone.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does add genuinely useful context about the workspace-root permission restriction, but says nothing about the return value, failure modes, or how children/properties interact with the created page.

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

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

Two short sentences with the core action front-loaded and the caveat immediately after. Nothing is padded, though the note could be folded more tightly.

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

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

For a mutation tool with no annotations, no output schema, and nested object parameters, the description covers the key permission gotcha but leaves the agent without information on results or edge cases (e.g., required properties for database parents, which only the schema hints at). Adequate but with clear 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%, so the schema already documents all five parameters, making 3 the baseline. The description marginally reinforces the parent parameter by naming valid parent kinds (database or page), but adds no format or structural detail beyond that.

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

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

States a specific verb and resource ('Create a new page'), which is unambiguous on its own. It does not differentiate itself from close siblings like notion_create_page_from_template or notion_duplicate_page, so it stops short of a 5.

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

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

The note steers the agent away from workspace-root creation and suggests database or page parents instead, which is a real usage constraint. However, it gives no guidance on when to use this tool versus notion_create_page_from_template or notion_duplicate_page, so the alternative-routing is incomplete.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses that blocks are copied from the template page, which is useful, but it omits permissions needed, whether the template page is modified, rate limits, and error conditions for an invalid template or parent.

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

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

The description is a single, front-loaded sentence with zero wasted words. It immediately communicates the core action and mechanism.

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

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

For a mutation tool with no annotations and no output schema, the description is too minimal. It does not explain what the tool returns, how failures are handled, or behavioral details beyond the copy mechanism, leaving an agent without enough context to call it correctly in edge 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 description coverage is 100%, so the schema already documents all four parameters. The description adds no syntax, format, or meaning beyond what the schema provides, 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?

States a specific verb (Create), resource (new page), and mechanism (copying blocks from a template page). This distinguishes it from notion_create_page, which creates a page without a template, and from notion_duplicate_page, which duplicates 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?

No explicit when-to-use guidance, no alternatives, and no exclusions. The description implies the tool is used when you want a page based on a template, but it does not mention notion_create_page or notion_duplicate_page as alternatives or specify when not to use it.

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

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

With no annotations, the description carries the full behavioral burden, and it discloses nothing: not whether deletion is destructive/permanent, not whether child blocks are also removed, not whether the block must be empty, and not what (if anything) is returned. For a delete mutation this is a major gap.

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

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

A single front-loaded sentence with zero waste. It is appropriately sized for the parameter surface, though the extreme brevity is also what leaves behavioral gaps, so it is not a 5.

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 destructive operation with no annotations, no output schema, and cascade/permanence questions unaddressed, the definition is not complete enough to call safely. An agent cannot tell whether this is reversible or what side effects accompany it.

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% for the single block_id parameter, so the schema already documents it fully. The description contributes nothing beyond the schema. Baseline 3 is appropriate when structured data does the work.

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

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

States a clear verb and resource ('Delete a block'), and the tool name plus sibling set (notion_update_block, notion_get_block) makes the intended operation unambiguous. However, the description adds no differentiation beyond the name itself and doesn't clarify scope (e.g., whether child blocks go with it).

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

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

There is no guidance on when to use this versus notion_update_block (which can archive/detach) or how it relates to append/get children. No prerequisites, no warning that deletion is irreversible or requires the block to exist. The agent is left to infer usage entirely.

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 full behavioral burden. It usefully signals that only the schema is duplicated (implying rows/data are not copied), which is genuinely valuable, but it says nothing about permissions required, parent defaulting behavior beyond the schema, or reversibility of the created copy.

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?

A single efficient sentence with the verb and scope front-loaded, and no wasted words. It is appropriately sized, though the extreme brevity means it under-delivers on guidance rather than being bloated.

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

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

For a mutation tool with no annotations and no output schema, the description is only minimally complete. The schema covers parameters well, but key behavioral aspects—whether data rows are copied, permission requirements, and the result of the operation—remain unaddressed.

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 (title, parent, database_id) are already documented with default behavior in the schema. The description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

States a specific verb (duplicate) and resource (database) with a scope qualifier ('with its schema'), which distinguishes it from notion_create_database. However, it does not explicitly reference the sibling tools or contrast the behavior beyond the verb choice.

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 offers no guidance on when to use this versus notion_create_database or notion_create_database_from_template, nor any prerequisites or exclusions. Usage must be inferred entirely from the name.

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 mentions that content blocks are duplicated, which is useful, but omits critical behavioral details: what happens to permissions, comments, child pages, or workspace placement; whether the operation is reversible; or any auth/rate-limit constraints. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

A single, front-loaded sentence with no wasted words. The core action and scope are stated immediately.

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

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

The tool is a mutating duplicate operation with a nested parent object, no annotations, and no output schema. The description does not address what gets copied beyond content blocks, nor does it mention permissions, failures, or side effects. Given the complexity and lack of structured behavioral disclosures, it is incomplete.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (including defaults for title and parent). The description adds no parameter-level detail beyond what the schema provides. Baseline 3 applies when the schema does the heavy lifting.

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

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

The description states a specific verb ('Duplicate') and resource ('existing page'), and adds scope ('with its content blocks'), which distinguishes it from notion_create_page and notion_create_page_from_template. However, it does not explicitly name or contrast with those sibling tools, so it falls just short of a 5.

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

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

There is no guidance on when to use this tool versus creating a new page, duplicating a database, or creating from a template. No prerequisites, exclusions, or alternative conditions 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 are provided, so the description carries the full burden, and it discloses nothing beyond the verb. It does not say whether the block's children are included, what happens on a missing/invalid ID, or what permission scope is required.

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?

A single four-word phrase with zero waste and the essential information front-loaded. It is efficient rather than padded, though the terseness contributes to the gaps elsewhere.

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

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

The tool is genuinely simple: one required string parameter and no nested objects. With no output schema and no annotations, the description does not explain the returned block shape, but for a trivial ID lookup the minimal statement is nearly 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% and the single parameter is already documented in the schema as 'Block ID to fetch'. The description adds no format or sourcing detail beyond that, so the baseline 3 applies.

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

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

States a specific verb+resource ('Get block') and includes the lookup key ('by ID'), which is enough to distinguish it from notion_get_block_children or notion_get_page. It does not explicitly name or exclude any sibling, so it stops short of a 5.

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

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

There is no guidance on when to use this tool versus notion_get_block_children, notion_get_page, or notion_search. The agent must infer the use case purely from the name.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. 'Get' weakly implies a read-only operation, but the description says nothing about return format, pagination behavior (despite page_size/start_cursor params), permissions, rate limits, or error conditions. This is far from sufficient for a tool with no annotation coverage.

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

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

The description is three words and front-loaded, but it is under-specified rather than concise. It omits essential information that would make the tool callable without opening the schema, similar to the LOW calibration example where brevity reflected incompleteness.

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

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

With no output schema, the description should explain what the tool returns (e.g., a paginated list of child blocks) and how pagination works. It provides none of this. For a read tool with pagination parameters, the description is substantially incomplete.

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

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

Schema description coverage is 100%, so the schema fully documents block_id, page_size, and start_cursor. The description adds no param semantics beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description 'Get block children' simply restates the tool name without adding distinguishing detail. It names a verb (get) and resource (block children), but does not differentiate from siblings like notion_get_block or notion_append_block_children. This qualifies as a tautology per the rubric.

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

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

There is no guidance on when to use this tool versus alternatives such as notion_get_block, notion_get_page, or notion_query_database. No prerequisites, context, or exclusions are provided. An agent must infer usage entirely from the name.

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 does not state that this is a read-only operation, that results are paginated (only implied by the schema params), what a comment object contains, or any permission/rate-limit constraints. Only the minimum is conveyed.

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?

A single front-loaded sentence with zero waste. It is efficient, though its brevity borders on under-specification rather than optimal 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 read tool with no annotations and no output schema, the description does not explain the returned comment structure, pagination behavior, or access requirements. The schema covers the inputs, but the agent is left guessing about the result and operational context.

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

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

Schema description coverage is 100%: block_id, page_size (max 100), and start_cursor are all documented in the schema. The description adds no format or semantic detail beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('comments') scoped to a page or block, which is clear on its own. It does not differentiate itself from the sibling notion_create_comment or explain how it relates to block/page reads, so it stops short of a 5.

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

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

No guidance on when to use this versus notion_get_block or notion_get_page, nor any mention of prerequisites (e.g., integration must have comment access) or how to handle paginated results. The agent must infer all usage context from the schema.

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. The word "Get" weakly implies a read-only, non-destructive operation, but there is no statement about permissions, rate limits, or what the returned database object contains (e.g., schema/properties vs. rows).

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 single short phrase is front-loaded and contains no filler or repetition. It is efficient, though its brevity is closer to under-specification than optimal economy for a tool in a crowded sibling set.

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

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

For a one-parameter getter with full schema coverage and no output schema, the description is minimally adequate. It still leaves open what is returned (metadata/schema vs. contents) and how it relates to notion_query_database, which matters given the dense sibling ecosystem.

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% (database_id is documented as "Database ID to fetch"), so the baseline is 3. The description's "by ID" merely restates the schema and adds no format, source, or lookup guidance beyond it.

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 clear verb and resource ("Get database by ID"), so an agent knows it retrieves a database object by identifier. However, it does nothing to differentiate this from sibling tools like notion_query_database or notion_get_page, which is the main ambiguity an agent faces in this toolset.

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

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

There is no guidance on when to use this tool versus notion_query_database (which returns rows/pages) or notion_search (which finds databases by name). The agent must infer usage entirely from the tool name and sibling names.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses nothing beyond the verb: no indication that this is a safe read-only, idempotent call, no auth/permission notes, and no statement of what the response contains. For a low-risk zero-param get this is tolerable but still an unexplained gap.

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

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

A single four-word phrase that is front-loaded and wastes nothing. It is appropriately sized for a trivial zero-parameter tool, though it is terse enough that it borders on under-specification rather than true 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?

With no output schema and no annotations, the description never says what is returned (a bot user object / its fields) or how it behaves. For a trivial identity lookup this is minimally sufficient, but one clause about the return value would close the gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly conveys that no input (such as a user ID) is required, since it targets the current bot.

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

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

States a specific verb (Get) and resource (current bot user), and the word 'current' meaningfully distinguishes it from notion_get_user and notion_list_users, which require an ID or return a list. It is clear without opening the schema, though sibling differentiation is only implicit rather than stated.

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 offers no when-to-use guidance, no prerequisites, and does not point to notion_get_user or notion_list_users as alternatives. An agent must infer from the name alone that this returns the authenticated bot's own identity.

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 supplied, so the description carries the full behavioral burden and supplies almost none of it: nothing about what is returned (page object vs. property values), whether a missing or inaccessible ID errors, or whether it requires integration permissions. For a read tool with zero annotation coverage this is a meaningful gap.

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

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

A single four-word phrase, fully front-loaded with zero padding. It is efficient, but the brevity edges into under-specification rather than deliberate 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?

With no output schema and no annotations, the description is the only source of information about the tool's contract, and it says nothing about return shape, error behavior, or the ID format. For even a simple retrieval tool this leaves the agent under-informed before calling it.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema ('Page ID to fetch'), so the baseline is 3. The description's 'by ID' adds nothing the schema does not already say.

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 pairs a specific verb ('Get') with a specific resource ('page') and its identifier, so the operation itself is unambiguous. It fails to distinguish this tool from lookalike siblings such as notion_get_database, notion_get_block, or notion_get_page_property, so it stops short of a 5.

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

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

There is no guidance on when to reach for this tool versus notion_search (to find a page you don't yet have an ID for) or notion_get_block_children (to read a page's contents). The agent is left to infer usage entirely from the name.

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 disclosure burden. It implies read-only via 'Get' but does not describe permissions, rate limits, or pagination behavior, even though pagination parameters exist in the schema.

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?

A single, front-loaded sentence with zero waste. It is arguably under-specified for the tool's complexity, but the dimension rewards conciseness rather than completeness.

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

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

With no output schema and no annotations, the description should clarify what is returned and how the pagination parameters affect the response. It does not, leaving significant ambiguity for a four-parameter tool.

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

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

Schema coverage is 100%, so all parameters are documented in the schema itself. The description adds only 'by ID', which is redundant with the required parameters, so the baseline of 3 applies.

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

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

States a specific verb 'Get' and resource 'page property', implicitly distinguishing it from sibling notion_get_page. However, it offers no explicit sibling differentiation or scope clarification beyond the 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?

No when-to-use guidance or alternatives are provided. 'By ID' implies a precondition but does not explain when to choose this tool over notion_get_page or notion_query_database.

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

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

With no annotations, the description carries the full behavioral burden and discloses essentially nothing beyond the operation name. It doesn't say whether the user must exist, whether public/bot users are returned, what auth is required, or what the response contains.

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?

A single front-loaded clause with zero waste. It is arguably under-specified rather than verbose, but the sentence itself is as tight as possible.

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 full schema coverage and no output schema, the minimum is met. However, the absence of any sibling differentiation or return-value context leaves avoidable ambiguity.

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

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

Schema coverage is 100% and the single user_id parameter is already documented as 'User ID to fetch'. The description adds no format, source, or ID-type detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a clear verb (get) and resource (user) with a scoping qualifier (by ID). It implicitly distinguishes a single-user fetch from notion_list_users, but never explicitly differentiates itself from notion_get_me or the list sibling.

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 when-to-use guidance, no prerequisites, and no mention of alternatives. Given siblings notion_list_users and notion_get_me exist, the agent gets no help deciding which to call.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read operation but does not disclose permissions, workspace scope, pagination behavior, or result limits beyond what the parameter schema already implies.

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

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

The description is a single, front-loaded phrase with no wasted words. However, it is so terse that it lacks any structural elaboration, keeping it from being a fully exemplary concise 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?

For a list tool with no annotations and no output schema, the description should convey more about returned user data or scope. The parameter schema covers pagination inputs, but the description leaves significant behavioral and return-value context unstated.

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 page_size and start_cursor are already documented in the schema. The description adds no parameter meaning beyond the schema, which is the expected baseline when coverage is high.

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

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

States a specific verb and resource: 'List all users.' This distinguishes it from retrieval siblings like notion_get_user and notion_get_me by using list/all, but it does not explicitly name or differentiate those alternatives.

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 when-to-use guidance or exclusions are provided. It does not say when to prefer this over notion_get_user, notion_get_me, or notion_search, leaving selection entirely to inference from the name.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing. It does not say whether results are paginated (despite page_size/start_cursor), whether access is read-only, what permissions are required, or what a response contains.

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 words is not wasteful, but for a five-parameter query tool with nested filter and sort objects it is under-specified rather than genuinely concise. There is no front-loaded context beyond the bare purpose.

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

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

For a tool with nested objects, pagination parameters, no annotations, and no output schema, the description omits the query semantics an agent needs: filter shape, default result ordering, and pagination behavior. The schema covers parameter naming but not behavior.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema, which sets the baseline at 3. The description adds nothing about the nested filter/sorts object structure, but the schema carries that burden here.

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

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

States a specific verb (Query) and resource (database pages), which is enough to separate it from notion_get_database (retrieves schema) and notion_get_page (retrieves a single page). It stops short of naming those siblings, so the distinction must be inferred from the verb/resource pair.

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

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

There is no guidance on when to use this versus notion_get_database, notion_search, or notion_get_page. Nothing tells the agent whether this returns all pages or only filtered ones, or what prerequisites exist.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Search' implies a read-only operation, but the description does not confirm safety, permissions, rate limits, result ordering, or pagination behavior. It adds almost no behavioral context beyond the verb itself.

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

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

The description is a single front-loaded phrase with no filler. It is appropriately sized for a concise name, though its extreme brevity leaves no room for useful clarifying context.

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

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

Given five parameters, nested filter/sort objects, no output schema, and no annotations, the description is too sparse. The schema documents parameters, but the description omits usage guidance, behavioral traits, and result format, leaving notable gaps for an agent choosing between search and database-query siblings.

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 five parameters already have descriptions. The tool description adds no additional meaning for query, filter, sort, page_size, or start_cursor. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

States a specific verb ('Search') and resources ('pages and databases'), so the core operation is clear. However, it does not differentiate from sibling tools like notion_query_database or notion_get_page, leaving the agent to infer when this workspace-wide search applies versus structured database queries.

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

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

The description gives no when-to-use guidance, prerequisites, or alternatives. It does not mention that this is workspace-wide search rather than a database query, nor does it point to notion_query_database for filtered database retrieval. An agent receives no routing 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 are provided, so the description carries the full behavioral burden, yet it discloses nothing about mutation semantics. It does not explain that only the key matching the block's actual type should be supplied, whether the update is partial or whole-block replacement, permission/auth requirements, or how the 'archived' flag behaves. This is a substantial gap for a mutation tool with zero annotation coverage.

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

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

The single short phrase is front-loaded and free of waste, but it is undersized for a 28-parameter mutation tool; the terseness signals under-specification rather than efficient 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 highly complex tool with 25 mutually exclusive block-type objects, no annotations, and no output schema, the description is far too thin. It omits the critical operating rule that the caller must pass the object keyed to the block's real type, leaving the agent to infer this entirely from the 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 description coverage is 100%, so all 28 parameters (including the 25 block-type objects and the archived flag) are documented in the schema itself. The description adds no parameter meaning beyond that, so the baseline of 3 applies.

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

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

The description states a verb and resource (update a block's content), but 'content' is the only word distinguishing it from the tool name notion_update_block, making it near-tautological. It gives no basis for telling it apart from siblings like notion_append_block_children, notion_get_block, or notion_delete_block. A minimally viable statement of purpose with no differentiation.

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

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

There is no guidance on when to use this tool versus alternatives. An agent cannot tell from the description whether to update an existing block here versus append/replace via notion_append_block_children or notion_delete_block, nor are any prerequisites stated. No usage guidance at all.

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 supplied, so the description carries the full behavioral burden, and it discloses nothing: not that this is a mutation, not whether changes are additive or replacing, not the required auth scope, and not the effect on properties omitted from the call. For a destructive-capable write tool this is a serious gap.

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

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

It is short, but this is under-specification rather than conciseness — three words that convey almost no actionable information about a 5-parameter, nested-object mutation 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?

With no annotations, no output schema, five parameters, and nested objects, the description would need to shoulder the full explanation burden. Instead it is a fragment that leaves auth requirements, mutation semantics, and the richer icon/cover/title update capability entirely undocumented.

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 every parameter (database_id, icon, cover, title, properties) has its own schema description, so the baseline of 3 applies. The description adds no semantics beyond the schema and notably fails to hint at the nested structure of the properties object.

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 three-word description 'Update database properties' essentially restates the tool name notion_update_database, adding only the word 'properties'. It is also narrower than reality: the schema shows icon, cover, and title can be updated too, so the description under-describes its own scope. No sibling differentiation against notion_update_page or notion_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?

There is no when-to-use guidance, no prerequisites (e.g. integration permissions), and no mention of alternatives such as notion_update_page. An agent gets zero routing information.

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 falls well short. It never discloses that this is a partial update, whether archiving is reversible, what permission scope is needed, or what happens to unspecified fields. 'Archived' in the schema is a state change with destructive implications that goes entirely unexplained.

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?

It is three words with no wasted text and the core action is front-loaded. But this is under-specification rather than genuine conciseness: the brevity comes at the cost of any routing or behavioral 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?

For a five-parameter mutation tool with nested objects, no annotations, and no output schema, the description should at minimum explain partial-update semantics and the archive behavior. Instead it omits all of that, leaving the agent to guess at 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?

Schema description coverage is 100%, so the schema already documents every parameter and the baseline is 3. The description adds no syntax, format, or semantics beyond the schema. If anything, calling everything 'properties' conflicts with the separate icon/cover/archived parameters.

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?

It states a clear verb and resource (update a Notion page), which is better than a tautology. However, it narrows the tool to 'properties' even though the schema also exposes icon, cover, and archived, so an agent may misjudge the tool's reach. It also does nothing to separate it from siblings like notion_update_block or notion_get_page_property.

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

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

There is no when-to-use guidance at all: no mention of prerequisites, no indication of when to prefer this over notion_append_block_children or notion_update_block, and no statement that only the supplied fields are changed. The agent must infer usage entirely from the name and schema.

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