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

With no annotations, the description carries the full burden, and it does disclose one genuinely useful behavioral trait: columns start as text and types must be changed afterwards. It omits permissions/scoping needs, whether creation fails on an invalid page target, and what the tool returns (e.g. a database id or URL) so the agent can chain calls.

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 input format, and short overall. The middle clause ('pastes the table, turns it into a database and names it') slightly restates the opening sentence, which is minor waste but not damaging.

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 5-parameter mutation tool with no annotations and no output schema, the description covers the main flow and the column-type caveat but leaves two parameters and the return value undocumented. An agent can call it, but cannot confidently chain on the result or control placement.

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 40%, so the description must compensate; it does clarify `table` semantics (header row = property names) and that `title` names the database. However `after` and `position` are left entirely unexplained in both schema and description, and the interaction between `page` default and insertion placement is not addressed.

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

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

States a specific verb and resource ('Create a full database') plus the distinctive input mechanism ('from a Markdown table'), which cleanly separates it from row-by-row insertion siblings like notion_insert. The parenthetical mapping of header row to property names and other rows to entries makes the operation 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?

Explicitly positions itself against the alternative ('Much faster than adding rows/cells one by one'), giving a clear reason to pick it over incremental insertion. It also routes the follow-up task of changing column types to notion_run_code (n.db.headerMenu), but gives no exclusion criteria such as when a Markdown table is unsuitable or when to create an empty database instead.

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

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

With no annotations, the description carries the full burden and does well: it discloses the dry-run preview behavior, that text blocks are serialized to a local deletion log while child pages/databases go to Notion Trash, and that shared workspaces require an extra opt-in plus user confirmation. It does not say what happens to other block types (images, embeds) or whether deletion cascades to nested children, which leaves the destructiveness profile partly open.

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 short sentences, front-loaded with the action and then the safety semantics; nearly every clause carries operational meaning. Slightly dense run-on phrasing in the last clause ('only after the user said yes') costs a little precision but not readability.

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

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

For a mutation tool with no annotations and no output schema, the description covers the critical unknowns: preview mode, where deleted content goes, how to restore, and the shared-workspace authorization gate. It stops short of describing the preview response shape or the fate of non-text blocks, which an agent would still have to discover by calling it.

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

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

Schema coverage is only 25%, so the description must compensate, and it does for three of four parameters: confirm (preview gate), allow_shared (guest/shared workspaces), and block_ids (targets by id). Only 'page' is covered by the schema itself, and no parameter is left fully 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+resource ('Delete blocks by id') with the id-based targeting that distinguishes it from page-level siblings. It also names the two restore counterparts, so an agent can place it in the tool family without opening any 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?

Gives explicit conditional guidance: without confirm:true it only previews, and guest/shared workspaces need allow_shared:true gated on user consent. It names notion_restore_blocks and notion_restore_page as the recovery paths. The one gap is that it never contrasts this with notion_trash_page, leaving the delete-blocks-vs-trash-page choice to inference.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses that existing blocks are never modified and that the operation rolls back if any existing block disappears, which tells the agent the insert is atomic and safe against partial writes. It omits permissions/auth requirements and what the response returns, so it is not fully transparent.

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

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

Two tight sentences with zero filler: the capability and its supported surface come first, followed by the behavioral constraint. 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?

There is no output schema, so the description would ideally say what comes back (e.g. created block ids), and it says nothing about required permissions. Still, for a 4-parameter insert tool with 75% schema coverage, the description covers capability, accepted syntax, and atomicity well enough to call 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 75% and already documents page, after, and position (including the after-vs-position precedence). The description compensates for the undocumented 'markdown' parameter by enumerating exactly which Markdown constructs are accepted, including fenced mermaid code, which is genuinely useful syntax guidance beyond the schema.

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

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

The description gives a specific verb and resource ('Insert Markdown as new blocks') and enumerates the block types it can produce, so an agent knows exactly what the tool does. It implicitly separates itself from editing tools with 'Never edits existing blocks', but it never names a sibling tool it competes with, which keeps it 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?

'Never edits existing blocks' functions as a when-not hint, and the verb 'insert' implies the when. However, no alternative is named (e.g. notion_read or notion_outline for inspecting content first), and there is no statement of prerequisites such as page access. 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?

With no annotations, the description carries the full burden and does well: it discloses that Notion is restarted, that data is safe because Notion saves continuously, that user confirmation is expected, and that macOS is untested. It omits failure modes and what happens if Notion isn't running.

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: the action and its modes come first, then the safety/confirmation caveat and platform note. Nothing is wasted.

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

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

For a one-parameter launcher, this covers purpose, safety, prerequisites, and platform caveats. No output schema exists, but return behavior (e.g., confirmation of restart) is not described.

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

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

Schema coverage is 0% for the single parameter, but the description explains both enum meanings in functional terms - debug mode enables the other tools, normal mode restores standard operation. The default of "debug" and the parameter name itself are not mentioned, so a small gap remains.

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 specific verbs (start/restart) and the resource (Notion), plus the two modes of operation. It also explains the why - debug mode lets the other tools connect - which distinguishes it from siblings like notion_open or notion_status.

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 use (when other tools need to connect) and a prerequisite ("ask the user first"). It does not explicitly contrast with notion_open or notion_status, so the agent must infer the boundary.

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

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

With no annotations, the description carries the full burden, and it does disclose two useful traits: results are scoped to deletions recorded by this server (not all of Notion's trash) and are ordered newest-first. It says nothing about whether the listing is read-only, pagination, or retention limits on the backups.

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 compact sentence with the key scoping qualifier ('through this server') and ordering up front. No filler, though there is room for one short clause on the limit parameter without bloat.

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

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

For a simple one-parameter read tool with no output schema, the description adequately conveys what comes back ('with their Markdown backups'). The unaddressed 'limit' parameter is the main completeness gap.

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

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

Schema description coverage is 0% for the single 'limit' parameter, and the description never mentions it — no default, no maximum, no statement of what happens when omitted. The description adds no meaning beyond the bare parameter name.

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 ('List blocks deleted') and adds scope ('through this server', 'newest first', 'with their Markdown backups'), which clearly separates it from the mutating siblings notion_delete_blocks and notion_restore_blocks. It stops short of naming those siblings explicitly, so it is not a 5.

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

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

The purpose implies the use case (reviewing what was deleted, presumably to restore), but the description never states when to call this versus notion_restore_blocks or notion_trash_page, nor any prerequisites. Usage is inferable rather than instructed.

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

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

No annotations are provided, so the description carries the full burden. It discloses the UI behavior 'in the active tab', but omits authentication requirements, whether it navigates the current tab or creates one, and error behavior for invalid URLs or ids.

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

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

A single, front-loaded sentence with no filler. The verb and target resource appear immediately, making it efficient and easy to scan.

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

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

For a simple one-parameter tool, the core action is adequately described. However, with no annotations and no output schema, it still omits prerequisites and side effects, leaving some contextual gaps.

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

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

The sole parameter has 0% schema description coverage. The description adds meaningful semantics by saying the url parameter accepts a page URL or id, but gives no format details or examples.

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: opening a Notion page by URL or id in the active tab. The purpose is clear, but it does not explicitly distinguish itself from siblings like notion_read or notion_launch.

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

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

There is no when-to-use, when-not-to-use, or alternative tool guidance. An agent must infer whether to use this versus notion_read or notion_launch based only on the brief description.

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

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

No annotations exist, so the description carries the full disclosure burden. It does disclose the return shape (depth/type/id/preview), which is valuable, and 'List' implies a read-only operation. But it omits whether only top-level blocks are returned, ordering, pagination/size limits, and permission requirements.

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 with zero waste; the output contract is front-loaded and the follow-up action tip follows immediately.

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

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

With no output schema and no annotations, the description partially compensates by describing the returned tuple. But for a block-listing tool it leaves open nesting depth semantics, completeness (all blocks vs top-level only), and size limits, which an agent would want before calling.

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 'page' parameter with 100% schema description coverage already explaining the URL/id and the active-tab default. The description adds nothing about the parameter, so the schema does the work; baseline 3 applies.

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

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

States a specific verb (List) and resource (page blocks) and even specifies the exact output tuple format [depth, type, id, first 80 chars]. It is distinguishable from siblings like notion_read or notion_screenshot, though it never explicitly says how it differs from notion_read.

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 second sentence, 'Use the ids for insert/delete,' gives downstream guidance pointing at the notion_insert and notion_delete_blocks siblings, which is useful context. However, there is no explicit when-to-use-this-vs-notion_read guidance or stated prerequisites.

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

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

With no annotations, the description carries the burden, and it does deliver the one behavior an agent most needs from a read tool: content comes back as Markdown rather than raw JSON blocks. However it says nothing about permissions, size/pagination limits, or truncation on large pages, and does not explicitly confirm the operation is non-mutating.

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

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

A single front-loaded sentence with no filler, and the primary resource is named first. It is efficient but borders on under-specified rather than merely concise.

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

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

For a simple two-parameter read tool with no output schema and no annotations, the description covers the core contract (what it reads, what format it returns). It is still missing routing guidance among the many sibling read tools and any behavior for the undocumented block_ids parameter.

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%: 'page' is well documented in the schema (URL or id, defaults to the active tab), while 'block_ids' has no schema description and is only gestured at by '(or some blocks)'. The description adds partial meaning over the schema but does not explain that block_ids restricts the read to a subset.

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 ('the page (or some blocks)') plus the output serialization (Markdown). It is clear enough to distinguish from write-side siblings like notion_insert or notion_delete_blocks, but it never contrasts itself with notion_outline, which is the closest competing read 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?

The parenthetical '(or some blocks)' is the only hint about scoping, and it is ambiguous rather than instructive. There is no statement of when to prefer this over notion_outline or notion_screenshot, no prerequisites, and 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?

With no annotations, the description carries the full burden and does meaningful work: it discloses that restored blocks come back as NEW blocks (not the same identities) and are reconstructed from a Markdown backup, implying formatting/fidelity limits. It does not state permission requirements, whether the restore is reversible, or what happens if the same deletion is restored twice.

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, both front-loaded with the highest-value information (what it does, then what it does not cover). No hedging or restatement of the tool name.

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

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

For a mutation tool with no annotations and no output schema, the description covers the action, source, default, and exclusions but omits return shape (e.g., whether created block IDs come back) and idempotency, which an agent needs to chain a restore with verification.

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 the single optional parameter, so the description must compensate, and it only partially does: it explains the default ('latest unrestored deletion') but never clarifies whether deletion_id is a deletion record identifier or a block identifier, nor its format. The default behavior is a useful addition but leaves the core identifier ambiguity unresolved.

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 ('put deleted blocks back where they were') plus the source of truth ('from the Markdown backup'), so the mechanism is unambiguous. It also names the sibling it is not for (child pages/databases) and redirects to notion_restore_page, distinguishing it from a set of 14 siblings.

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

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

Gives explicit routing: child pages/databases are out of scope, use notion_restore_page instead, and states the default selection when no deletion is specified. It stops short of telling the agent whether to enumerate candidates with notion_list_deletions first or what to do if the latest unrestored deletion isn't the intended 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?

With no annotations, the description carries the burden and does meaningfully add: it reveals this is UI automation ("opens it and clicks 'Restore page'") and that title-based restore depends on the sidebar Trash of the *current* workspace, which implies a workspace-scoped, session-dependent operation. It still omits permissions, failure behavior, and irreversibility/undo notes.

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

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

One sentence, front-loaded with the action and resource, with the two selection modes parenthetically scoped. 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?

No output schema and no annotations, so the description should cover ambiguity resolution (duplicate titles), behavior when the item isn't found, and what a success response looks like. It covers the operation but leaves those decision-critical gaps for a mutation-style tool.

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

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

Schema coverage is 0% for two undocumented, optional parameters, so the description must compensate and largely does: url is the page/database URL used to navigate and click Restore, title must be an *exact* match searched in the current workspace's Trash. It stops short of explaining which parameter wins if both are provided, or what happens if neither is.

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?

Specific verb (Restore) plus specific resource (a page or database from Notion Trash), and it even discloses the mechanism used in each mode. An agent can distinguish it from notion_restore_blocks (blocks) and notion_list_deletions (listing) without opening any 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?

The two invocation modes (by URL vs. by exact title in the current workspace's sidebar Trash) are described, which implies when each applies, but there is no explicit when-not guidance, no stated precedence when both url and title are supplied, and no pointer to notion_restore_blocks for non-page objects.

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

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

No annotations, so the description carries the burden and does well: it discloses that arbitrary code runs with a helper API surface and warns about destructive use. It stops short of stating sandboxing, permissions, error behavior, or what the run returns, which matters for an open-ended code-execution tool.

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

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

Two dense sentences, front-loaded with the 'Escape hatch' framing and the safety constraint. Every clause (helpers, prefer-dedicated, never-delete, use-delete-blocks) earns its place.

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

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

Given no output schema and no annotations, the description covers invocation shape and safety well. The one gap is that it never explains how the result of the executed code is surfaced to the agent, which for a code-exec tool leaves return handling ambiguous.

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% (only `page` is documented), but the description compensates by specifying the `code` parameter's exact shape as an `async (page) => {...}` function and enumerating available helpers. The `page` default is already in the schema, so the description adds rather than repeats.

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: run an `async (page) => {...}` function against the target page. The 'Escape hatch' framing plus the `page.n` helper namespace makes it instantly distinguishable from the dedicated siblings like notion_insert or notion_read.

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

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

Explicitly says to prefer dedicated tools, gives a hard exclusion ('never delete with this'), and routes deletion to notion_delete_blocks with the reason (so a backup exists). This is textbook when/when-not/alternative guidance.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose what the tool returns (image blob, file path, base64), whether it captures the viewport or full page, whether the Notion app must be focused/foreground, or whether it fails on pages not currently open — all critical for a screenshot tool.

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

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

A single short sentence, front-loaded with what the tool produces, with the purpose in parentheses. 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 tool with no annotations and no output schema, the description omits the most decision-relevant facts: return format/where the screenshot lands, capture scope, and any focus/window prerequisites. An agent cannot predict the result shape from this definition alone.

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?

Only one optional parameter with 100% schema coverage, so the schema already explains the URL/id and the default to the active tab. The description's 'active Notion page' phrasing is consistent with that default but adds no new semantics.

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 ('Screenshot of the active Notion page') and adds the intent (checking layout/diagrams), which is far more informative than the sibling names notion_read/notion_outline. It doesn't explicitly contrast itself with those siblings, but the output type (image) makes it naturally distinguishable.

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 parenthetical '(to check layout/diagrams)' implies the use case — visual verification rather than content extraction — but it never says when to prefer this over notion_read or notion_outline, nor any preconditions (e.g., page must be open/visible).

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

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

With no annotations, the description carries the full disclosure burden. The enumerated inspection targets effectively describe what the agent will learn (workspace, tabs, access level), which is the most important behavioral detail. However, it never explicitly states that the call is non-mutating, nor what happens if the connection is down or what the result looks like on failure.

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

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

Two short clauses, zero filler, with the operational instruction ('Call first') front-loaded after the scope statement. Every element 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 zero-param diagnostic with no output schema and no annotations, the description supplies enough: it names the diagnostic categories so the agent knows what information to expect. It is only slightly incomplete in not covering failure behavior or how to react if the check reports a problem.

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 is nothing for the description to disambiguate. Baseline 4 applies; the description correctly does not waste space re-explaining an empty 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 ('Check the connection') and enumerates exactly what is inspected: debug port, workspace, open tabs, active page, access level. That is far more informative than the opaque name notion_status. It doesn't explicitly contrast itself with siblings, but the diagnostic framing makes it clearly distinct from the action tools (notion_read, notion_open, notion_launch).

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?

'Call first' gives explicit ordering guidance, which is the key usage decision for a status tool. There are no stated when-not conditions or named alternatives, so it falls short of a 5, but the priming instruction is clear and actionable.

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

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

No annotations exist, so the description carries the full load. It does disclose a meaningful behavioral trait — this mutates shared UI/session state and the agent is expected to notify the user and restore the prior workspace. It says nothing about what happens if the name is unknown, whether credentials/session change, or how subsequent calls are affected.

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

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

Two short sentences, front-loaded with the action and followed by the workflow obligation. Nothing is padded, though 'switch back when done' is slightly vague about what 'done' means.

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

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

With no annotations, no output schema, and an undocumented parameter, the description covers the core action and the restore obligation but omits failure behavior and side effects on the session. For a state-changing tool this leaves real gaps an agent would want filled.

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?

One required parameter ('name') with 0% schema description coverage, so the schema contributes nothing. The description clarifies that the value is a workspace/account name, which is genuinely useful, but gives no format, casing, matching rules, or example.

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: 'Switch the Notion window to another workspace/account by name.' That is clear and distinct from all listed siblings (launch, open, read, etc.), none of which change workspace context. It stops short of explicitly naming a sibling it differs from, so a 4 rather than a 5.

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

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

The description implies when this is needed (when work must happen in a different workspace/account) and adds a lifecycle instruction: tell the user, and switch back when done. But it names no alternative tool and gives no precondition or failure guidance, 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?

With no annotations, the description carries the full burden and mostly succeeds: it discloses reversibility (restorable for 30 days), the two-phase preview/confirm behavior, the exact-title precondition, and a workspace-level permission limit. It leaves the meaning of allow_shared and the permanence implication of confirm:true unexplained.

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

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

Four short clauses, no filler, and the primary effect plus reversibility window are front-loaded before the safety-relevant confirm and permission notes.

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 4-parameter mutation tool with no annotations and no output schema, the description covers the essentials an agent needs: what happens without confirm, that the action is reversible, and the guest-workspace restriction. It is still silent on what a preview returns and on allow_shared, so it is not fully complete.

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

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

Schema coverage is only 25% (only `page` is documented in the schema), so the description must compensate, and it does for two parameters: exact title matching and the dry-run semantics of confirm. `allow_shared` is left entirely undefined in both schema and description, which keeps this below 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?

The description names a specific verb and resource ('Move the current page to Notion Trash') and characterizes the effect (30 days, restorable), which separates it from notion_delete_blocks and notion_restore_page. It does not explicitly name a sibling for comparison, 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?

It gives a clear use protocol: call without confirm:true to preview, then confirm to act, plus the prerequisite that the title must match exactly and that guest workspaces usually disallow the operation. It never names notion_delete_blocks as the alternate path for block-level removal, so the alternative-selection guidance is incomplete.

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