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

With no annotations, the description carries the burden and mostly succeeds: it discloses dual read/write behavior, the condition that triggers each mode, and the Markdown list return format for reads. It does not mention auth, rate limits, or what an add operation returns, but the core behavioral contract is transparent.

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

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

The description is well-structured with a front-loaded summary, two labeled usage sections, code examples, and a short note on page references. Every section earns its place and no filler is present.

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

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

For a two-parameter dual-mode tool with no output schema, the description covers the main scenarios, return format for reads, and accepted page reference forms. The only notable gap is the unspecified response of an add operation, which is minor for practical use.

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

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

Schema coverage is 100%, so the baseline is 3. The description mostly repeats what the schema already says, though it adds concrete invocation examples and confirms the page name/ID/URL flexibility already present 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 opening sentence 'Add or read comments on a Notion page' states a specific verb, resource, and scope, and separates the two modes with clear headers. This distinguishes it from generic siblings like read/write by scoping it to comments.

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

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

The description gives explicit context for when to use each mode: omit body to read, include body to add. It does not explicitly name sibling alternatives or say when not to use this tool, but the usage context 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?

With no annotations provided, the description carries the full burden and does well: it discloses the page moves to Trash, can be restored from Notion's UI, and is not permanently deleted. It does not mention output/response details or edge cases like already-archived pages, but the core behavioral trait is clearly exposed.

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

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

Three short sentences with no filler. The key action is stated first, and the important caveat about not permanently deleting is given immediately, making the definition efficient and easy to parse.

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

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

For a one-parameter, no-output-schema tool, the description covers the essential behavior and reversibility. It does not describe the return value or potential errors, but those are less critical for an archive action whose semantics are already clearly defined.

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

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

Schema description coverage is 100% and the single 'page' parameter already documents 'Page ID or Notion URL to archive.' The description adds no additional parameter-level semantics, but none are needed given the schema already fully explains the parameter.

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 identifies the action as 'Archive (soft-delete)' applied to a Notion page, which is a specific verb+resource. It also clarifies the non-permanent nature, distinguishing this from what the name 'delete' might imply and from any truly destructive delete operation.

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 intended use is implied: use this when you want to archive or soft-delete a page. However, there is no explicit guidance about when not to use it or which sibling tool to prefer in alternative scenarios, such as permanent deletion or moving pages.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format, provides an example output, explains name resolution via search, and gives detailed filter/sort semantics. This goes well beyond what the tool name alone implies.

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

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

The description is appropriately organized with headers and examples. The main behavior is front-loaded, and the length is justified by the complexity of the filter/sort syntax. No sentence feels wasted.

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

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

For a list operation with no output schema, the description supplies return formats, an example table, target resolution rules, and enough syntax detail to construct valid filters and sorts. There is no critical gap preventing an agent from calling the tool correctly.

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

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

Although the schema already documents all four parameters, the description adds essential meaning: a full filter expression grammar, sort syntax, and target resolution behavior. The schema even references the tool description for filter syntax, making this added detail necessary for correct invocation.

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 first sentence clearly states the action (list) and the two concrete resource types: database records as a Markdown table and child pages as a numbered list. It is unambiguous about what the tool does, though it does not explicitly name sibling tools like read/search to draw the boundary.

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

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

The description explains when to use each mode (databases vs pages), how targets are resolved via search, and how to construct filter and sort expressions. It does not explicitly say 'use read for page content' or 'use search to find targets,' but the context is clear enough for an agent to invoke it correctly.

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

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

With no annotations, the description carries the behavioral burden, and it does so well by explicitly stating that the page keeps its content and properties and only the location changes. It does not mention permissions, errors, or response shape, but the core side-effect model—non-destructive relocation—is clearly 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?

Every sentence earns its place: the first states the core action, the second clarifies the behavioral guarantee, and the third gives concrete usage examples. The information is front-loaded and contains no fluff.

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

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

For a two-parameter tool, the description is nearly complete: it covers purpose, behavior, parameter semantics, and examples. The main gaps are return-value/error semantics and explicit sibling differentiation, but these do not prevent correct invocation for the primary use case.

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

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

The schema already covers both parameters clearly, and the description adds useful semantic nuance by framing 'to' as a parent page or database and giving practical examples. This goes beyond the baseline expected from the high 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?

The description uses a specific verb and resource: 'Move a Notion page to a different parent page or database.' It clearly distinguishes the operation from the sibling tools by defining the scope as relocation, with examples of moving to an Archive or database.

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

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

The description establishes clear use context: move content between locations while preserving content and properties, and gives concrete examples. It does not explicitly list when not to use it or name alternatives like 'update,' so it stops 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?

With no annotations, the description carries the full behavioral burden. It clearly discloses the return format (frontmatter fields and body), the depth recursion behavior, and marks the created/last_edited fields as read-only. This gives an agent a solid understanding of what to expect without needing additional metadata.

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

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

The description is well-structured with the main purpose first, followed by output details, a usage tip, and a concrete example. While it is somewhat long, every section adds value and the example makes the tool's behavior tangible.

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?

Since there is no output schema, the description appropriately explains the return value in detail (frontmatter fields and Markdown body). It also covers the depth parameter and the round-trip with 'write', making it sufficient for an agent to call the tool correctly. Minor gaps like error behavior are not critical here.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds an example output and rephrases depth behavior, but it does not significantly extend the parameter semantics beyond what the schema provides.

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

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

The description states a specific verb ('Read'), resource ('a Notion page'), and output format ('Markdown with YAML frontmatter'). It is clear what the tool does, though it does not explicitly contrast with sibling tools like 'search' or 'list' to aid differentiation.

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

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

The description mentions a concrete use case—'output can be edited and passed directly to the write tool'—and explains the depth parameter for including children. However, it does not provide explicit when-to-use or when-not-to-use guidance compared to alternatives like 'search' or 'list'.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly explains each action's effect (list returns schema, add creates property, remove deletes, rename renames) and notes the return for list. However, it does not mention potential side effects (e.g., irreversible removal, permission requirements, or error conditions). For a schema-modification tool, the described behavior is transparent enough, but missing edge-case details keep it from 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?

The description is front-loaded with the purpose in the first sentence, then organizes actions under clear headers with code examples. Every section earns its place: actions, supported types, and option guidance. It is comprehensive without being redundant, striking an ideal balance between detail and brevity.

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 6 parameters, 4 actions, and no output schema, the description is highly complete. It covers all actions with examples, lists valid types, and explains parameter roles. It does not explicitly address error scenarios or prerequisites, but the scope is well-defined and the examples cover typical use cases. Nothing essential for calling the tool correctly 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?

Despite 100% schema coverage, the description adds substantial meaning beyond the schema. It provides concrete usage examples for each action (e.g., how to pass property, type, options, name), enumerates supported types for 'add', and clarifies the default action. This goes well beyond the schema's dry descriptions, making parameter usage intuitive and error-free.

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

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

The description states a clear verb+resource: 'View or modify database schema (columns/properties).' It enumerates four distinct actions (list/add/remove/rename) with concrete examples, making it unambiguous what the tool does and distinguishing it from generic sibling tools like write/update/delete. The purpose is fully articulated.

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

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

The description clearly defines the actions and their semantics, providing examples for each. However, it does not explicitly contrast this tool with sibling tools or state when not to use it (e.g., for data operations vs. schema changes). The guidance is implicit through the tool's specific scope, but an explicit alternative route would elevate it.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses the Markdown response format, the kind of metadata shown (icon, last-edited date), and that the tool returns IDs suitable for downstream operations. It does not discuss pagination, sorting, or no-result behavior, so it is good but not exhaustive.

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

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

The description is compact: a one-line purpose, a routing sentence, and a concrete example. Every section adds distinct value with no redundancy, and the main action is front-loaded.

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

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

Since there is no output schema, the example output compensates well by showing the exact list format, ID style, and metadata. The description also covers downstream usage across siblings, and the input schema already covers parameter constraints. Missing details like pagination are non-critical for a search 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?

All three parameters are already fully documented in the schema (100% coverage), so the baseline is 3. The description adds no new parameter-level meaning beyond the schema; it reinforces how returned IDs are used afterward, which is useful but not parameter 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?

The description opens with a specific verb ('Search'), resource ('the Notion workspace'), and scope ('by title keyword'), and immediately defines the return shape as a Markdown list with page/database IDs, titles, and metadata. The example output further clarifies the purpose and distinguishes it from read/list/write tools.

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

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

It explicitly tells the agent to use returned IDs with other tools and names each sibling role: read (get full content), write (update), list (query a database), delete, or move. This is strong routing guidance; no explicit 'when not to use' is needed because the alternatives are clearly assigned.

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 behavioral burden. It usefully discloses that page content/blocks are never touched and only properties are updated, but it does not cover merge/overwrite semantics, permissions, failure modes, or return values.

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 moderately long but well-structured with sections for parameters, examples, and value types. Each section adds practical guidance, though the parameter section partly restates the schema.

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

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

For a two-parameter update tool with no output schema, the description provides enough guidance to invoke it correctly: page identifier format, properties object shape, and value encodings. It omits response/error details, but those are not essential for this simple 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?

The input schema already describes both parameters, so the baseline is 3. The description adds examples and a supported value-type list (date ranges, multi-select, checkboxes, URLs) that clarify how to encode property values, going beyond the schema.

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

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

The description clearly states it updates page properties without rewriting content, and explicitly contrasts itself with the write tool for property-only changes. This makes its purpose distinct from sibling tools.

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

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

It names the write tool as the alternative for content changes and frames itself as the simpler option for property-only updates. It does not spell out explicit when-not-to-use conditions or cover other siblings, but the intended use case 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does this thoroughly: it explains that body content replaces existing blocks unless position is append/prepend, read-only fields are safely ignored, properties are auto-matched, and the '===' separator enables batch mode. This is far more transparency than expected for a mutation tool.

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

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

The description is long but extremely well organized with headers, a frontmatter table, and multiple examples. Every section adds operational value, and the most important information (mode behavior) is front-loaded. It could be slightly trimmed without loss, but the structure supports usability well.

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 three parameters, no annotations, and no output schema, the description is remarkably complete. It covers all modes, batch behavior, position semantics, property handling, ignored fields, and includes practical examples. An agent has all the information needed to construct valid calls for create, update, append, and batch scenarios.

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

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

Although schema description coverage is 100%, the description adds substantial meaning beyond the schema. It details the YAML frontmatter structure, the meaning of 'id', 'parent', 'database', 'icon', 'cover', and 'properties', and provides concrete examples for each mode and position. This goes well beyond the baseline of 3.

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

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

The description states a clear action: 'Create or update Notion pages from Markdown with YAML frontmatter.' This names the resource, the operation, and the input format. However, it does not explicitly differentiate itself from the sibling tool 'update', and the dual create/update scope blurs the boundary somewhat, so it misses the top score for explicit sibling distinction.

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

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

The description gives explicit guidance on when to create vs update based on presence of an 'id' in frontmatter, and clearly explains when to use append/prepend versus replace. It also explains batch usage. However, it does not state when to prefer this tool over sibling alternatives such as 'update' or 'read', so it lacks the 'when-not-to-use' component of a 5.

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