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

Annotations already carry readOnly/idempotent/non-destructive, but the description adds real behavioral detail: multi-select/people/relation rows count once per group, and dates can be bucketed by day/week/month/quarter/year. It also discloses the shape of the return ('totals and the top groups'), which annotations cannot convey.

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

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

Front-loaded with the agent's intent ('how many / how much by X'), then dense but purposeful clauses about filtering, grouping, and metrics. The parenthetical syntax examples earn their space; nothing reads as filler.

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

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

For a 9-parameter tool with 11% schema coverage and no output schema, the description covers grouping and metrics well but omits the pagination/ordering controls (top, sort, max_rows) and data_source_name. An agent could still call it, but would be guessing on those knobs.

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 only 11%, so the description must compensate and it partially does: it explains where/filter semantics (same as notion_query), group_by including date bucketing, and gives a concrete metric syntax example ("sum:Points"). However top, sort, max_rows, and data_source_name are left entirely unexplained, so the compensation is incomplete.

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?

Names a specific verb+resource (aggregate row metrics over a Notion database) and frames it by the question it answers ('how many / how much by X'). This clearly separates it from notion_query, which pulls full rows into context.

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

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

Explicitly states the use case (aggregate counts/sums instead of reading every row) and notes filters behave like notion_query, implying when to pick each. It stops short of a direct 'use notion_query when you need the actual rows' exclusion, so not quite a 5.

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

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

Annotations only flag destructive/openWorld/non-idempotent; the description adds far more: dry_run never writes, run writes with one undo_id per rule, run errors unless every rule succeeded and reports succeeded/partial/failed, failed rows retry from the failed step, scheduled occurrences only count as fired when fully successful, and expected_revision guards against concurrent overwrites. This is exactly the behavioral depth annotations cannot carry.

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 long, but for a 15-action tool with a nested rule grammar the density is largely earned, and it is front-loaded with the core purpose before descending into rule structure and action semantics. A few clauses (e.g., the step-ordering narrative) could be tightened, but nothing is filler.

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

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

With no output schema, 14 parameters, nested objects, and destructive actions, the description carries a heavy load and does so: it covers rule grammar, all actions, run status semantics, retry behavior, and revision safety. An agent has enough to select an action and invoke it correctly.

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

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

Schema coverage is 86%, so the baseline is 3, but the description meaningfully supplements the near-empty `rule` object by specifying its shape (when/schedule/actions/then, marker requirement, action ordering) and explains confirmed-vs-merge update semantics and the revision/edit contract. It adds real meaning beyond the schema's `additionalProperties: {}` without fully specifying every field's syntax.

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 ('Manage and run automation rules') and grounds it in concrete state (rules.json or NOTION_PLUS_RULES), which no sibling covers. It even positions itself relative to siblings by noting the `when` condition reuses notion_query's where/filter and `then` reuses notion_build_report args, making its scope unambiguous.

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

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

The description enumerates every action (list, get, add, update, validate, dry_run, enable, disable, delete, run, history, waive, export/import, deploy) with a short gloss of what each does, which is strong per-action usage context. It stops short of explicit when-to-use-this-vs-a-sibling routing (e.g., vs notion_bulk_update or notion_undo), so it is clear rather than exhaustive.

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?

Annotations declare a non-read-only, non-idempotent, non-destructive write, and the description adds value beyond them: it discloses that charts may be live views or rendered images, that image charts are refreshable via notion_create_chart, and that notion_undo trashes the created page (i.e. it is reversible). It still omits permission requirements and what exactly is returned.

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

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

Front-loaded with the verb and outcome, then the optionality/scope rule, then related-tool notes. Three dense sentences that each carry information, though the section enumeration is somewhat packed.

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 10-parameter nested tool with no output schema, the description adequately conveys what is produced and the optionality/scope behavior. The main gap is that it does not describe the return value (e.g. the created page id/url), which has no schema to fall back on.

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 only 30%, so the description must compensate more than it does. It clarifies the role of `where` (scopes the whole report) and maps sections (summary, kpis, charts, table, gantt) to params, but leaves database, parent, title, and data_source_name unexplained.

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 (build) plus resource (a report page for a database) and explicitly notes it happens 'in one call'. It enumerates exactly what the page contains (summary callout, KPIs, charts, table, Gantt), distinguishing it from lower-level page/block 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?

Gives clear context: every section is optional, `where` scopes the whole report, and it routes the agent to notion_create_chart for refreshing images and notion_undo for trashing. It does not explicitly say when to prefer this over manually composing pages with notion_create_page/notion_insert_blocks, so no full exclusion set.

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?

Goes well beyond the annotations by disclosing pre-write validation ('Every row is validated before anything is written'), partial-failure semantics ('Rows that fail while writing are reported; the rest stay'), and the fact that one notion_undo trashes all created rows — none of which is in readOnly/destructive/idempotent hints.

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?

Five dense sentences, each carrying distinct information, front-loaded with the core action and input modes and closing with failure/undo behavior. No repetition of the title or filler.

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

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

For a mutation tool with no output schema and 7 parameters, the description covers the essential risk surface (validation, dry_run default, partial failure, undo) and value semantics via notion_update_properties. It is slightly short on the two undocumented secondary parameters but otherwise complete enough to call safely.

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 only 14%, so the description must compensate, and it does partly: it maps rows/csv/csv_path, notes the dry_run default, and clarifies forgiving key matching and empty-cell handling. However, data_source_name and allow_new_options get no explanation at all, leaving gaps the schema cannot fill.

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 up to 1000 database rows') with concrete input modes (JSON objects, CSV text, CSV path), which cleanly distinguishes it from notion_create_page and notion_bulk_update.

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?

Explains the input paths and the dry_run default, and points to notion_update_properties for value semantics plus notion_undo for reversal. It does not explicitly state when to prefer this over notion_create_page or notion_bulk_update, so it stops short of full alternative routing.

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?

Annotations already declare destructive=true and idempotent=true, but the description adds major behavioral context: dry-run defaults on and returns current values, validation happens before writes, changed rows are snapshotted, failures are reported per row, and the entire batch can be reverted with one notion_undo.

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 front-loaded: it states the core operation and its two modes immediately, then layers safety behavior and limits. Every sentence carries information useful for correct invocation.

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 9-parameter mutation tool with no output schema, the description covers the important operational contract: modes, row cap, dry-run default, validation, snapshots, per-row failures, and undo. It is only slightly incomplete because a few supporting parameters are left to 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?

With schema coverage at 44%, the description compensates well for the core parameters: it explains set with where/filter, rows as [{page, set}], the 500-row cap, and dry_run behavior. It adds filter operator examples via notion_query syntax, though less common parameters such as database, data_source_name, and allow_new_options remain unexplained in the prose.

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 many rows at once, with two distinct modes. It distinguishes bulk update from single-row siblings like notion_update_properties by naming the where/filter and rows approaches.

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 clearly explains the two supported usage modes and recommends dry_run=true as the default confirmation step. It references notion_query for filter syntax and notion_undo for reverting, but does not explicitly state when not to use this tool versus single-row update 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?

Annotations already declare this as read-only, idempotent, open-world, and non-destructive, so the bar is lower. The description still adds meaningful behavior: capabilities are probed with read-only calls and write capabilities show as unknown until an actual write occurs, which tells the agent how reliable each capability answer is.

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 that begins with the core purpose before parenthetically listing the details. It is dense but every listed element (areas, API version, limits, capability availability) is relevant and 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?

There is no output schema, so the description must convey what the tool returns, and it does so by enumerating areas, API version, limits, and capability status. For a zero-parameter introspection tool with clear safety annotations, this is complete enough, with only the exact response structure left unspecified.

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 there are no parameter semantics to document and the baseline is 4. The description correctly avoids inventing parameters and focuses on the returned information instead.

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 what the server can do with the current integration and enumerates the specific deliverables: covered areas, Notion API version, planning-relevant limits, and available capabilities. It is a distinct discovery/introspection purpose, though it does not explicitly differentiate itself from any sibling tool.

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 is implied through 'limits that matter for planning' and the note that write capabilities only become known after a write, suggesting this tool is for pre-flight discovery. However, there is no explicit when-to-use instruction, no when-not-to-use guidance, and no named alternative among the many sibling tools.

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

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

Annotations declare openWorldHint and non-idempotent but leave the mixed read/write nature and deletion semantics opaque. The description supplies the important gaps: the API does not return resolved threads, added comments are removed via notion_undo, and an integration can only delete its own comments.

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 tight paragraph, front-loaded with the action breakdown before the format and lifecycle notes. Every clause carries information; nothing is repeated from the schema or 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?

For a no-output-schema mutation/read tool with 5 params, the description covers the return shape for list (open comments plus discussion ids) and the write lifecycle. Pagination via `limit` and the exact add/reply response shape are unstated, but the essentials for correct invocation are present.

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

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

With schema coverage at 60%, the description compensates by explaining that `text` is markdown with bold/links/mention syntax (a concrete example format the schema lacks) and by tying `discussion_id` to action=list. It adds real meaning beyond the 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 opening verb triad ('Read, add, or reply to comments') names both the resource and each operation, and then disambiguates the three actions line by line. An agent can distinguish this from notion_insert_blocks or notion_patch_block without opening the schema.

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 specifies the condition selecting each action (list for a page/block's open comments, add to start a discussion, reply to answer by discussion_id) and routes removal to notion_undo. It stops short of stating when to prefer this over other comment-adjacent siblings, but the action-level guidance 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?

Goes well beyond the destructiveHint annotation: moved blocks get new ids and lose comments, sub-pages use page-move semantics and land at the destination end, moves are refused for non-recreatable content, and one notion_undo reverts everything. This is exactly the operational context an agent needs before mutating 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?

Dense but front-loaded: the core operation comes first, then caveats and safety. Every sentence carries information, though the paragraph is long enough that it could be split for faster scanning.

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 six-parameter destructive mutation with no output schema, the description covers the safety model, edge-case refusals, id-loss behavior, and undo path thoroughly. Return-value details are unspecified, but the absence of adverse outcomes for the caller is largely addressed.

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

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

With only 50% schema coverage, the description compensates by explaining the semantics of move, dry_run (default true for moves), and position (start/end/after a block). It adds real meaning beyond the terse schema, though after_block_id's linkage to position=after_block edges is only implied.

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 concrete verb (copy/move) and resource (blocks, with nested children) and the destination options. It clearly distinguishes itself from siblings like notion_insert_blocks and notion_patch_block by covering relocation rather than creation or editing.

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?

Explains the copy-vs-move decision (move=true trashes originals) and the dry_run default that makes moves safe to preview, giving clear context for when to use each mode. It stops short of naming an explicit alternative tool for the plain-insert case, but the mode guidance is strong.

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

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

Annotations disclose mutation (readOnlyHint=false, destructiveHint=false, openWorldHint=true), but the description adds genuinely behavioral facts beyond them: the recipe is remembered so refresh re-renders from current data, vega_lite does no fetching ('nothing is fetched'), and operations are reversible via notion_undo. It also discloses that vega_lite is 'Not refreshable', a real limitation.

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

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

Front-loads purpose, create/refresh, and the notion_views alternative in the first sentence, but the long run-on enumeration of 22 chart types and data-shape rules makes the body dense. The content mostly earns its place, though a bulleted chart-type reference would read better.

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 12-parameter, nested-object tool with no output schema, the description covers data sourcing (inline vs `source` query), chart-type semantics, placement, refresh behavior, the escape hatch (vega_lite), and reversibility. Nothing an agent needs to call it correctly appears 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?

With only 58% schema coverage, the description supplies the missing semantics: per-chart-type meaning of x, y and series (heatmap x=column/series=row, waterfall ordering, dual_axis two-series rule, sankey forward-only flows), plus `bins`, `annotations`, `palette`, and `data_table` behavior. This is meaning well 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?

States a specific verb+resource ('Render a chart image... and put it on a page, or refresh an existing chart image in place'), covering both create and refresh modes. It explicitly distinguishes itself from the sibling notion_views ('Prefer notion_views chart views when a live Notion chart is enough'), so an agent can route without opening a schema.

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?

Names the primary alternative (notion_views chart views) with the condition that selects it, and explains the refresh path via `refresh_block_id` plus the fallback to `vega_lite` 'for anything the types don't cover'. Both when-to-use and when-to-prefer-something-else are present.

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?

Annotations already declare readOnly=false, openWorld=true, idempotent=false, and destructive=false. The description adds useful behavior: full schema creation in one call, automatic 'Name' title property, and that notion_undo trashes the database. It does not cover permission requirements or rate limits.

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

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

The description is front-loaded with the core action and remains dense with useful schema details. It is long, but the complexity of the property schema justifies most of the length; phrases like 'and more' are slightly imprecise.

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 output schema and only 43% schema description coverage, the description gives solid creation semantics, default title behavior, and next-step routing. It stops short of covering permissions, return value expectations, or all parameter details.

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 only 43%, so the description must compensate. It does so substantially for the complex 'properties' parameter by enumerating property types, status groups, number formats, formulas, relations, rollups, unique ID prefixes, and the default title property behavior, though it leaves icon, cover, inline, parent, and description parameters mostly to the schema.

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

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

The description uses a specific verb and resource: 'Create a database under a page with its full schema in one call.' It also names sibling tools for adding rows and undoing the operation, so an agent can distinguish this from notion_create_page, notion_bulk_create, and notion_undo without opening 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?

It clearly routes post-creation row insertion to notion_bulk_create or notion_create_page and notes that notion_undo trashes the database. However, it does not explicitly state when not to use this tool or compare it to other database-related tools.

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

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

Annotations flag it as a non-idempotent, non-destructive, open-world write, and the description adds real behavior beyond that: properties are schema-validated, template applies a database template, and content can arrive as markdown or blocks. It doesn't mention auth/permission needs or what is created on failure, but the added context is substantive.

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

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

Front-loads the core action, then orders clauses by parameter importance. Dense but every clause carries information; no filler sentences, though it is on the longer side.

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 11 parameters, nested block objects, no output schema, and 45% schema coverage, the description covers the branching logic and content formats an agent needs. Gaps remain around the return value and the unmentioned params (allow_new_options, data_source_name).

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 only 45%, so the description must carry weight and largely does: it explains parent (database vs page), properties validation, title filling, template, markdown/blocks, icon, and cover. It silently omits icon_emoji, data_source_name, and allow_new_options, so not fully compensating for the low 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?

States a specific verb+resource ('Create a page') and elaborates on the two creation modes (database parent vs page parent), which distinguishes it meaningfully from sibling reads like notion_get_page. It does not explicitly contrast itself with notion_duplicate_page or notion_bulk_create, so it lands at 4 rather than 5.

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

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

The description branches on parent type to explain what each mode does, and routes the agent to notion_update_properties, notion_list_templates, and notion_insert_blocks for adjacent semantics. It never states when to prefer this over siblings like notion_duplicate_page or notion_bulk_create, so no 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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation profile is known. The description adds real value beyond that: a precise blast radius ('Nothing else on the page is touched') and recoverability ('Reversible with notion_undo'), which the annotations do not convey.

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 tight sentences, zero filler, with the core action front-loaded and the safety/recovery note trailing. Every clause earns its place.

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

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

For a single-parameter destructive tool with no output schema, the description covers action, scope, and reversibility. It could be improved by noting the 100-item cap or failure behavior on invalid IDs, but nothing essential is missing for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the burden. 'By id' clarifies that block_ids are identifiers and the plural phrasing hints at multi-block input, but it omits the 1–100 cardinality constraint and any ID format detail, leaving the schema array underspecified in prose.

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 ('Move specific blocks ... to the trash') and immediately scopes the blast radius ('Nothing else on the page is touched'), which distinguishes it from sibling mutators like notion_patch_block, notion_insert_blocks, and notion_trash_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?

Usage is implied but never stated: the description doesn't say when to prefer block-level deletion over notion_trash_page, nor any prerequisites (permissions, block type restrictions). Referencing notion_undo as a recovery path is useful context, but there is no explicit when-to-use/when-not 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered; the description reinforces it with 'Changes nothing.' It earns credit beyond the annotations by disclosing that it both detects problems and prescribes fixes ('say how to fix what isn't') and by scoping the inspected state precisely.

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

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

Front-loaded with the core purpose, then a scannable inventory of checks, then two short directive sentences. The middle list is long but every item is a distinct diagnostic surface, so it earns its space.

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-only diagnostic with no output schema, the description is nearly self-sufficient: it names what is checked, promises remediation guidance, and states side-effect behavior. It does not describe the shape of the report it returns, which is the main remaining 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?

There is a single optional parameter at 100% schema coverage, so the schema fully documents 'offline' ('Skip checks that call Notion.'). The description adds nothing about the parameter, which is acceptable given the schema does the work — 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 ('check that the server is set up and working') and enumerates the exact surfaces it inspects, from settings and token to the chart renderer and automation runs. It does not differentiate itself from a sibling like notion_capabilities, which also concerns the integration's capabilities, so it falls 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?

'Run it first when something doesn't work' gives a clear triggering condition, and 'Changes nothing' signals it is safe to run speculatively. It does not name a when-not case or an alternative sibling, so it stops short of explicit routing.

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?

Annotations mark it as non-read-only and non-destructive, but the description adds rich behavioral detail: what gets skipped, status 'partial', re-uploading of files, relation handling, and the role of dry_run and notion_undo. This goes well beyond the 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 a single dense paragraph that front-loads the core behavior. It is efficient but could be slightly more structured for readability; every sentence does contribute useful 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?

Given the complexity (9 parameters, no output schema), the description covers most operational aspects: copy scope, database handling, file re-upload, and undo/dry-run. However, it doesn't address error conditions, rate limits, or the exact format of the 'partial' status 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 coverage is 67%, so the description must compensate. It explains the 'databases' parameter behavior, the effect of dry_run, and what max_rows controls. However, it doesn't clarify all parameters (e.g., data_source_name, include_subpages) fully, leaving some ambiguity.

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 specifies exactly what is copied (icon, cover, content blocks, writable properties) and what is not (views, linked views, read-only blocks). It clearly distinguishes the tool from siblings like notion_create_page and notion_copy_blocks by focusing on full page duplication.

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 implies use cases (e.g., dry_run for preview, notion_undo for reversal), it doesn't explicitly state when to use this tool versus alternatives such as notion_copy_blocks or notion_create_page. The guidance is implied rather than spelled out.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds value by disclosing the return fields (block id, type, text, last_edited_time), which the annotations do not. It omits limits on depth/results and pagination 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?

Three tight sentences: what it does, what it returns, and when to use it. Front-loaded with the core action and no filler.

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

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

For a 6-parameter tool with low schema coverage and no output schema, the description covers the core search semantics and return shape but leaves four behavioral parameters (depth, result cap, case sensitivity, regex flag behavior) undocumented anywhere.

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 only 17%, so the description must carry the load. It clarifies that query matches as a string or regex, tying the query and regex parameters together, but says nothing about max_depth, max_results, case_sensitive, or the page parameter format.

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 (find) and resource (blocks on a page) with the matching criterion (string or regex). It is clearly distinguishable from notion_get_blocks (retrieval by structure) and notion_replace_text/notion_update_page, which it implicitly contrasts.

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

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

Gives a concrete when-to-use: locate the exact block to edit rather than rewriting the page. It does not name a specific sibling alternative or state exclusions (e.g., when to use notion_get_blocks instead), so it falls short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds value they don't: the return format (outline with block ids) and the incremental-read strategy for large pages, which is behaviorally meaningful for an agent.

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 the core action and scope, with no wasted words. 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?

With no output schema, the description's brief mention of the outline/block-id return shape is helpful. However, given three parameters with only 33% schema coverage, the limits on depth and block count remain unexplained, leaving the definition incomplete for correct invocation.

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

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

Schema description coverage is only 33% — 'block' is documented but max_depth and max_blocks have no descriptions. The description does not explain depth limiting or block-count limits, leaving two of three parameters semantically undocumented despite the low schema 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?

States a specific verb and resource ('read the children of a page or block') and clarifies the return shape ('as an outline with block ids'). It does not name or differentiate against close siblings like notion_find_blocks or notion_get_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?

'Use for large pages to read one section at a time' gives a genuine usage context, but no alternatives are named and no when-not-to-use condition is stated (e.g., how it differs from notion_find_blocks or notion_get_page). Usage is implied rather than explicit.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds genuine extra context: the outline format includes block ids for later surgical edits, and last_edited_time can be echoed back as expected_last_edited_time to avoid clobbering concurrent edits — a concurrency-control hint annotations cannot express.

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

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

Front-loads the purpose in the first clause, then the format semantics, then the concurrency tip. Dense but every sentence carries information; slightly long for the payload but no filler.

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

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

No output schema exists, so the description rightly describes returns (properties, database, content, block ids, markdown flavors). It does not mention truncation/pagination behavior for max_blocks, which is the main remaining gap for an agent deciding how much will come back.

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 only 40%, and the description only elaborates on 'format' (its enum values and downstream consumers). max_depth, max_blocks, and include_content are left to their names and defaults, so the description does not fully compensate for the coverage gap.

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

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

Opens with a specific verb+resource ('Read a page') and enumerates exactly what is returned: properties as simple values, parent database, and content. This distinguishes it from block-level siblings like notion_get_blocks and notion_find_blocks without needing to inspect schemas.

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

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

Explains the two format modes and routes the agent to the right consumers: 'outline' for surgical edits via notion_patch_block/insert/delete/copy_blocks, 'markdown' for round-tripping into notion_insert_blocks/notion_create_page. It does not explicitly contrast against notion_get_blocks or notion_find_blocks, so it stops short of full when-not 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds real value beyond them by disclosing the shape of the result, including status groups and which properties are read-only, plus the dependency on write operations. No pagination or error behavior is mentioned.

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 filler. The content it returns is listed first and the operational reason to call it is front-loaded as the closing admonition.

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 usefully enumerates the fields returned and the write-prerequisite workflow. It is close to complete for a two-parameter read tool, though it omits any mention of multi-data-source ambiguity resolution beyond what the schema's data_source_name already implies.

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 both parameters (database, data_source_name) are fully documented in the schema itself. The description adds no syntax, format, or selection guidance for them, 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 ('Read') and resource ('a database's properties') and enumerates exactly what the read returns: names, types, select/status options, status groups, relation targets, and read-only flags. It is not differentiated from the similarly-named sibling notion_schema, which is the only gap.

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

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

Gives explicit just-in-time guidance: 'Read this before writing properties so values match exactly.' That tells the agent both when to call it and why. No exclusion or alternative tool is named, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description earns credit for going further: it discloses result ordering, that entries carry undo ids with revert scope, and that interrupted/failed entries stopped part-way with input retained. This partial-failure semantics is genuinely useful and not derivable from 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 dense sentences, front-loaded with the tool's purpose and no filler. The second sentence about interrupted/failed entries is slightly cryptic but earns its place by clarifying an edge case in the results.

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 usefully characterizes the return payload (undo ids, revert extent, partial-failure entries), which is exactly what an agent needs. The remaining gap is pagination — the cursor param exists but nothing explains paging 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?

The description says nothing about limit or cursor, and schema coverage is only 50% (limit is undocumented in the schema). With half the parameters lacking any definition, the description needed to compensate for limit's default and max, but it adds no 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?

States a concrete verb (list) and resource (changes made through this server), plus ordering (newest first), so the agent immediately knows this is a change-log reader. It distinguishes itself from notion_undo only implicitly by surfacing undo ids rather than naming the sibling, so it falls short of a 5.

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

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

Usage is implied rather than stated: surfacing undo ids and revert scope suggests reviewing history before calling notion_undo, but the description never says when to use this versus notion_undo, nor names any exclusion. Adequate context, no explicit 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?

Annotations already cover safety (readOnlyHint=false, destructiveHint=false, non-idempotent, open-world). The description adds meaningful beyond-schema behavior: 'Everything is validated and uploaded before the first write' (validation/atomicity) and 'Existing content is never rewritten.' It also states the return value ('Returns the new block ids'), which is useful since no output schema exists.

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 core purpose and positioning are front-loaded, followed by a dense but content-rich enumeration of markdown/block features. It is a single long paragraph rather than structurally broken up, but nearly every sentence carries specific, actionable detail, so 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 the tool's complexity (many block types and markdown features), no output schema, and existing annotations, the description is quite complete. It covers positioning, content formats, validation behavior, and return value; only permission prerequisites and parent constraints are left to 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?

With only 40% schema description coverage, the description compensates well by detailing the markdown parameter's supported syntax (headings, nested lists, callouts, mermaid, equations, tables) and the structured blocks types. It also clarifies the position semantics (start/end/after a specific block id), adding meaning beyond the enum and 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 states a precise verb and resource ('Insert new content at an exact spot') and enumerates the insertion positions, clearly distinguishing this tool from modification tools. An agent immediately understands this is for adding new blocks, not rewriting existing content.

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

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

It gives clear context — insert at start, end, or after a specific block — but never names or compares to sibling tools like notion_patch_block or notion_replace_text. The statement that 'Existing content is never rewritten' is a behavioral constraint rather than a routing guideline, so usage is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value beyond that by naming the returned fields (name, id, default), which matters since there is no output 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 tight sentence with the purpose front-loaded and the downstream usage appended; no filler or redundancy.

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

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

For a read-only list tool with no output schema, the description usefully sketches the return shape and the consumer of that output. However, it leaves the second parameter undocumented, which is a real gap given 0% schema coverage.

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

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

Schema description coverage is 0% for two parameters. The description implies the `database` parameter via 'a database's page templates' but says nothing about `data_source_name` or the expected id/name format, so it fails to compensate for the coverage gap.

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

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

States a specific verb (List) and resource (a database's page templates) and even enumerates the returned fields (name, id, default). No sibling tool covers templates, so it is unambiguous which tool to pick.

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 tells the agent the follow-on action: feed a returned name or id into notion_create_page's `template` parameter, which implies when this tool is used. It does not state any when-not condition, but the workflow 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?

Annotations already declare the safety profile (non-destructive, idempotent), but the description adds meaningful behavior: it snapshots the old content for notion_undo and clarifies that it edits only a single block by id. It does not explain concurrency or error behavior, but it goes beyond what the annotations alone provide.

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

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

Front-loads the core purpose and scope, then packs the per-block-type capabilities into one efficient sentence. The third sentence covers the API limitation and undo snapshot. It is dense but well-structured with no obvious filler.

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

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

For a 10-parameter mutation tool with no output schema, the description is nearly complete: it explains the edit scope, supported operations, the block-type limitation, and the undo-snapshot behavior. It omits details on expected_last_edited_time and error handling, which are relatively minor against the full picture.

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 60%, so the schema already documents some parameters. The description compensates by explaining what many parameters do in context: text supports inline markdown/colors/mentions, checked toggles a to-do, language/caption apply to code blocks, toggleable applies to headings, icon applies to callouts, and cells replace table-row content. It leaves expected_last_edited_time unexplained, which keeps it from a 5.

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

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

States a specific verb and resource ('Edit a single block in place by id') and immediately scopes it ('without touching anything else on the page'). The list of supported edits makes it easy to distinguish from siblings like notion_insert_blocks or notion_bulk_update.

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

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

Gives a clear when-not condition for block type changes and names the alternative workflow (insert a new block and delete the old one). It does not explicitly route the agent between this tool and siblings like notion_replace_text or notion_bulk_update, but the context is otherwise 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?

Annotations already declare this a read-only, idempotent, open-world, non-destructive operation, so the bar is lower. The description still adds real behavior: `where` and `filter` are combined with AND, and names/options are 'matched forgivingly and validated', which tells the agent it can be loose with casing/labels. Return shape ('rows with simple values and page ids') is also disclosed.

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

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

Front-loaded with the core action, then the `where` reference. The operator enumeration is dense but every clause carries usable syntax information, and the alternate-tool pointer is placed at the end where it matters. Slightly long, but nothing is truly redundant.

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

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

For a query tool with no output schema and 8 params, the description covers the query semantics and the return shape adequately. Gaps remain around pagination/sorthing behavior (cursor is only explained in the schema), but nothing essential to correct invocation is missing.

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

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

Schema description coverage is only 38% with 8 parameters, so the description must compensate. It does so thoroughly for the two hardest params (`where` and `filter`), enumerating equality, operators, lists, or-groups, relative dates, and $created/$last_edited, plus the AND combination. It leaves limit, sorts, and data_source_name unaddressed, keeping it below 5.

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

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

Opens with a specific verb+resource ('Query database rows') and immediately clarifies scope: rows, not aggregates. The closing sentence names the sibling it is not and why ('For counts or totals use notion_aggregate'), so an agent can distinguish it from notion_aggregate and notion_search without opening 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?

Explicitly routes count/total needs to notion_aggregate instead of reading every row, which is a genuine when-not rule. It does not cover other plausible alternatives (e.g. notion_search for cross-database lookups) or prerequisites, so it falls short of a full 5.

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

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

The description goes well beyond the annotations (which only say non-read-only, non-destructive, non-idempotent, open-world). It discloses formatting preservation, regex support with $1 groups, dry_run default with before/after preview, cross-mention matches being skipped/reported, sub-page exclusion, and that changes revert together with notion_undo – all critical behavioral traits for safe invocation.

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 dense paragraph, front-loaded with core purpose and scope, then safety default and edge cases. Every sentence adds unique information with zero filler.

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

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

For a multi-param mutation tool with no output schema and sparse schema descriptions, the description covers scope, safety, regex, formatting preservation, limitation handling, and undo integration. It provides everything an agent needs to call correctly and safely.

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 only 22%, so the description must compensate. It explains include_title, regex, dry_run, and block_ids behavior meaningfully. However, it doesn't clarify case_sensitive or max_replacements defaults, leaving two parameters (case_sensitive, max_replacements) undocumented semantically.

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 (find and replace text across a page) and details the exact scope: every text block, table cell, code caption, and the page title. This clearly distinguishes it from siblings like notion_update_page or notion_patch_block, which don't perform cross-page text substitution.

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 mentions the default dry_run=true safety behavior and that sub-pages aren't searched, which helps an agent decide when to use this tool. It does not name alternative sibling tools for narrower edits, but the scoping ('across a page') implies when this bulk-replace approach is appropriate.

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?

Annotations already flag destructiveHint=true and non-idempotent, and the description goes well beyond them: delete defaults to a dry run showing affected row counts and snapshots up to 2000 rows' values for notion_undo recovery. It also discloses a hard API limitation (options cannot be renamed or recolored; the API ignores or rejects it), which is genuinely new 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?

Front-loaded with the core action and one sentence per action variant, so every clause carries information. It is a dense single paragraph, though, and some clauses (the full option-recolor workaround) run long relative to their marginal selection value.

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

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

For a 6-action, 10-parameter mutation tool with no output schema, the description covers dry-run defaults, undo/snapshot behavior, per-action parameter intent, and an API constraint. An agent has enough to choose the right action and predict side effects without further research.

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 50% across 10 parameters, and the description adds real meaning by mapping each action to the parameters it consumes (to=rename, property=existing property, definition=add, options=add_options). It does not mention data_source_name or clarify number_format/description handling for the settings actions, leaving minor gaps.

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 ('Change a database's properties') and then enumerates every action the tool supports (add, rename, delete, add_options, set_number_format, set_description). It clearly distinguishes itself from siblings like notion_create_database and notion_update_properties via explicit cross-references.

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

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

Gives per-action guidance and names concrete alternatives: notion_create_database for the add definition syntax, notion_bulk_update to move rows when changing options, and notion_undo to re-create/restore a deleted property. It even explains when NOT to expect a capability (rename/recolor of options) and prescribes the workaround.

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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description earns credit by adding the integration-visibility constraint ('Only content shared with the integration is searchable') and enumerating returned fields, both of which are not in the 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?

Three short sentences, all front-loaded: purpose, return shape, then usage. No filler and each sentence carries distinct 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?

With no output schema, the description correctly compensates by listing the returned fields. Usage and scoping constraints are present; the only gap is that the limit/pagination behavior of the search is never addressed.

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 67%: 'query' and 'type' are documented in the schema, but 'limit' (default 20, max 100) is undocumented anywhere. The description adds no parameter detail, leaving the limit parameter's semantics entirely implicit.

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 ('Search pages and databases ... by title') plus a scope qualifier ('shared with the integration'). This implicitly distinguishes it from notion_query (database-scoped retrieval) and notion_find_blocks (block content search), 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?

Gives clear intent: 'Use this to find ids before reading or editing,' which tells the agent where this fits in a workflow. It stops short of naming alternatives or stating when NOT to use it versus notion_query or notion_find_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?

Annotations declare readOnlyHint=false, openWorldHint=true and destructiveHint=false; the description usefully augments this by stating preview 'writes nothing' and that render can be reversed via notion_undo. It also implicitly flags mutation (create/append) and that render uploads charts and places live views, which are real side effects. Return formats and error behavior are not disclosed, but the safety-relevant behavior is well covered.

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

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

Purpose is front-loaded, but the remainder is one enormous run-on paragraph with nested parentheticals that buries the per-action guidance mid-sentence. The length is arguably justified by the DSL complexity and every clause conveys something, yet the lack of structure (no separation of actions vs. template spec) hurts scanability.

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 nine-action, deeply nested tool with no output schema, the description is substantively complete: it covers every action, built-in templates, the template object shape, variable syntax, and all node types. Only the return values of list/export/import and error handling are left unspecified, which is a minor gap given the richness elsewhere.

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 78%, so the schema documents most params (name, parent, append_to, compare_to). The description goes well beyond it by defining the free-form `template` spec, the `variables` interpolation syntax, `slots`, and the full node DSL, which the schema cannot express. That is meaningful added semantics for the two most complex, free-form 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?

The opening sentence states a specific verb+resource+benefit ('Build pages from reusable templates instead of many block calls'), distinguishing this tool from siblings like notion_insert_blocks and notion_create_page. It then enumerates all nine actions and the four built-in templates, so an agent can tell exactly what the tool does and when it replaces lower-level block calls.

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?

Per-action conditions are given inline: validate checks a template and compiles variables, preview 'writes nothing', render targets `parent` or `append_to`, and delete/export/import are self-evident. The routing away from 'many block calls' is explicit, but it never names a specific sibling alternative (e.g. notion_list_templates or notion_create_page) to prefer for a given case, so it stops short of full when-not 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?

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=true, so the safety profile is covered. The description adds valuable context beyond annotations: that the action is reversible via notion_undo or Notion's trash. It doesn't cover permissions or rate limits, but the reversibility note is meaningful added value.

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, front-loaded with the core action and followed by the reversibility note. Every word earns its place with no redundancy.

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

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

For a single-parameter mutation tool with rich annotations, the description covers the essential action and reversibility. It doesn't explain permissions or potential side effects (e.g., what happens to child blocks), which would be helpful, but it's largely complete for the scope.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'page' as the target but doesn't clarify that the parameter is a page ID string. Since there's only one parameter and its name is self-explanatory, baseline 3 is appropriate given the low schema 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?

States a specific verb ('Move') and resource ('page or database row') with a clear destination ('the Notion trash'). This distinguishes it from siblings like notion_delete_blocks and notion_update_page by identifying exactly what operation occurs.

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

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

The description implies usage (when you want to trash a page), but doesn't explicitly compare to alternatives like notion_delete_blocks or notion_update_page. It mentions recovery via notion_undo, which is helpful, but doesn't state when to prefer trash over other deletion methods.

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?

Annotations already declare destructiveHint=true and idempotentHint=false, so safety is covered; the description goes well beyond them by explaining the restore-from-snapshot mechanism, the conflict-detection-and-refusal behavior (including that it lists blocking objects), and a real limitation (minute-rounded edit times make same-minute edits undetectable). That is exactly the kind of behavioral disclosure that cannot be inferred from structured fields.

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, front-loaded with the core action and default behavior, then escalating to the lookup tool, the refusal semantics, and the edge-case limitation. No filler, no restatement of the title or annotations.

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, non-idempotent mutation with no output schema and only two params, the description supplies everything an agent needs: default behavior, id acquisition path, refusal conditions, override flag semantics, and a known blind spot. Nothing material is left implicit.

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 only 50% (undo_id has no description), and the description compensates: it defines undo_id as optional with 'no id reverts the most recent change that has not been undone' plus a lookup path, and it defines force by tying it to the conflict refusal rather than merely repeating the schema's terse 'Overwrite edits made after the original change.' Both parameters gain 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?

States a specific verb+resource ('Revert a change made through this server') with scope qualifier ('through this server'), which cleanly separates it from siblings that write (notion_update_page, notion_patch_block) and from the read/inspection tools. The default no-id behavior is spelled out, so the agent knows the operation is optional-argument driven.

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

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

Explicitly routes the agent to notion_history to obtain ids, defines the no-id fallback, and states the precise when-not condition: the tool refuses if anything it would restore was edited later, unless force is true. That is a complete use/avoid decision rule rather than an implied one.

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?

Annotations already declare idempotentHint=true and destructiveHint=false, and the description adds real value beyond them: it discloses that changes are reversible via notion_undo and that an uploaded icon/cover file is re-uploaded on undo. It does not mention permission requirements or what happens to unspecified fields, so it falls short of a 5.

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 tightly packed sentences, front-loaded with the core capability, then value-format details, then sibling routing and undo behavior. No filler; every clause carries information an agent 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?

With no output schema and 8 parameters at low coverage, the description would need to carry more. It handles the icon/cover/move semantics well but leaves data_source_name and expected_last_edited_time unexplained, so an agent cannot fully infer correct invocation for those fields.

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 only 25% of 8 parameters, so the description has to compensate. It does clarify icon/cover value formats and the 'none' sentinel that removes either, but title, locked, data_source_name, and expected_last_edited_time (notably a concurrency guard) get no explanation in either place.

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 precise verb plus resource and enumerates the exact operations available (title/icon/cover, lock/unlock, move under a page or into a database). It also explicitly distinguishes itself from notion_update_properties for database row fields, so an agent can separate the two siblings without opening either schema.

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 names the alternative for a specific case ('For database row fields use notion_update_properties') and points at notion_undo for reverting, which gives clear routing. It stops short of covering other near siblings (notion_create_page, notion_patch_block) or stating exclusions for arbitrary block content.

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

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

Annotations only cover the safety profile (non-read-only, idempotent, non-destructive, open-world); the description adds substantial behavior the annotations do not: forgiving name/option matching, full-schema validation before writing, aggregated error reporting, and a saved snapshot enabling notion_undo. These are exactly the mutation-time facts an agent needs.

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 dense sentences, front-loaded with the core action and value formats, then validation guarantees, then side effects and preview. No filler and nothing repeated from the schema or annotations verbatim.

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 and no output schema, the description covers value encoding, validation timing, error aggregation, undo support, and preview mode. An agent can call this correctly without further 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?

With schema coverage at 80%, the baseline is 3, but the description adds real meaning: it defines how each value type maps to property kinds (arrays for multi-select/people/relations, ISO dates or {start,end}, null to clear) and explains what dry_run actually previews. The remaining params (allow_new_options, expected_last_edited_time) are already documented in the schema.

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

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

The description gives a specific verb and resource ('Set properties on a database row') and enumerates accepted value types, so the agent knows exactly what is being written. It does not explicitly differentiate itself from close siblings like notion_update_page or notion_bulk_update, so a routing agent still has to infer which one to pick.

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 tells the agent to use dry_run to preview, and that paths through validation happen before any write, which implies a cautious first-call workflow. However, it never states when to prefer this tool over notion_update_page, notion_bulk_update, or notion_patch_block, nor any prerequisite like fetching the schema first.

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?

Annotations declare destructiveHint=true and idempotentHint=false, and the description adds that 'Every change is reversible with notion_undo' — genuine value that softens the destructive profile. It does not detail permissions or what the response looks like, but the annotation coverage lowers the bar and the reversibility note is the most important behavioral fact.

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

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

Front-loaded with the action list and packed densely with concrete examples rather than filler. It is somewhat long but nearly every clause (types, placement, chart spec, reversibility) earns its place for a complex 8-parameter 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?

For a complex tool with nested objects and no output schema, the description covers the action set, view types, placement modes, filter/sort/group references, chart specifics, and reversibility. It is largely self-sufficient, though it could note pagination or update semantics more explicitly.

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 75%, so the schema already documents most parameters. The description adds concrete semantics beyond the schema, e.g. the chart spec example `{type: "column", x: "Owner", y: "count"}` or `y: "sum:Estimate"`, and group_by examples ('board by Status, dates by week'), which clarify usage beyond bare field names.

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 resource (database views) with the full CRUD verb set (list, read, create, update, delete), which an agent can immediately distinguish from siblings like notion_query or notion_create_chart. It also enumerates the view types, making the scope of the tool concrete.

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

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

Gives clear context for the `on` parameter's two placements (linked view on a page, widget on a dashboard) versus the default tab. It references notion_query for filter syntax and notion_undo for reversibility, but does not explicitly state when to prefer this tool over siblings like notion_query or notion_create_chart.

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

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

Despite annotations already declaring destructiveHint=true and openWorldHint=true, the description layers substantial extra behavior: secrets are referenced as ${secret:NAME} and 'never stored or shown', http/slack are restricted to NOTION_PLUS_HTTP_ALLOW hosts, runs are durable and resume after the last finished step with double-create protection, and approval/delay pause until the next scheduler pass. This is exactly the kind of operational context annotations cannot convey.

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?

Content is dense and mostly relevant, and the core purpose is front-loaded, but the body degenerates into a long semicolon-heavy run-on mixing step actions, reference syntax, durability, and action enums. It would benefit from paragraph or bullet structure; nearly every clause is useful but hard to parse as one block.

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 8 params, no output schema, and nested objects, the description covers triggers, step actions, reference variables, durability/idempotency, host allow-lists, approval/delay pauses, and the full action set. What is missing is per-action return behavior, but that is a modest gap given how much ground is already covered.

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 only 50% across 8 params. The description explains the `inputs` param ('run: values for ${inputs.*}') and extensively documents the `workflow` object's internal structure, but leaves run_id, event_id, limit, and status semantics to the schema. It adds meaningful value for the nested workflow spec but does not fully close the coverage gap.

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

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

The opening sentence gives a precise verb+resource: 'Multi-step workflows (version 2 of automations): a trigger (manual, schedule, or Notion webhook events) and typed steps run in order.' It names the sibling relationship to automations v1 via the 'convert (a v1 rule into a workflow)' action, so an agent can distinguish it from notion_automation without opening a schema.

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 is implied through the enumerated actions (list, get, save, run, runs, resume, cancel, convert) and the mention that convert migrates a v1 rule, but there is no explicit 'use this instead of X when Y' routing against the obvious alternative notion_automation. The agent can infer the lifecycle but gets no exclusions or conditions.

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