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

No annotations are provided, so the description must carry the full behavioral disclosure burden. It only states that blocks are added, without mentioning side effects, permission requirements, error behavior, or whether existing content is preserved. For a write operation, this is inadequate.

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

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

Two short sentences with no filler. The action is front-loaded and the usage clause is immediately helpful.

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 append operation, the description provides sufficient selection context. It lacks details on return values or edge cases, but the tool is low-complexity and no output schema exists to explain.

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 both parent_id and content are already documented. The description adds no additional parameter meaning beyond restating that content is added to a page or block.

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 ('Add new content blocks to a page or block') and clarifies the target is an existing page, which distinguishes it from create_page. It does not explicitly name alternatives like update_block, but 'new content blocks' conveys that this tool creates rather than modifies blocks.

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

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

It explicitly states when to use the tool: when the user wants to add content to an existing page. It does not provide exclusions or name sibling alternatives, but the primary 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states that a database is created, but it does not mention whether the parent page must already exist, what side effects occur, what the response looks like, or any permission requirements. This is a significant gap 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?

Two compact sentences with no filler. The core action is front-loaded, and the use-case sentence immediately follows without repetition.

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

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

The description covers what the tool does and when to use it, and all required parameters are documented in the schema. However, there is no output schema and no annotation, and the description omits the return value, constraints on the properties schema, and failure behavior, leaving meaningful gaps for an agent invoking the 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 all three parameters, so the baseline is 3. The description adds only a general relationship via 'child of a page' and a high-level purpose for properties, but it does not explain the structure or constraints of the nested properties object.

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

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

The description uses a specific verb ('create'), identifies the resource ('database'), and scopes the operation ('as a child of a page'). The phrase 'structured data collection' clarifies the database's role, helping distinguish this tool from siblings like create_page or query_database.

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

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

'Use when user wants to set up a new structured data collection' is an explicit trigger condition, so an agent knows when to select this tool. It does not list exclusions or directly compare with alternatives such as create_page, but the context is clear enough for basic 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?

With no annotations provided, the description carries the behavioral disclosure burden. It does clarify that the page can be created in a database or as a child, but it says nothing about failure cases, permissions, side effects of creation, or what happens when invalid parent IDs are supplied.

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

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

Two short sentences with the core purpose front-loaded. The second sentence provides a usage hint, though it is imprecise and arguably could be sharpened to reference creating a page rather than generic 'new content.'

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

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

For a simple create tool, the description plus full schema coverage is mostly adequate. However, there is no output schema, no mention of what the response contains, and no guidance about required parent constraints or nested properties, leaving some ambiguity for an agent deciding what to pass.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds modest context by mapping 'in a database or as a child' to the parent_type enum, but it does not explain semantic relationships between properties, content, and parent types beyond what the schema states.

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

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

The description states a specific verb and resource ('Create a new page') and clarifies the two kinds of parents: a database or another page. However, it doesn't explicitly distinguish itself from append_blocks, which also adds content to Notion in a different way.

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 phrase 'Use when user wants to add new content to Notion' gives some usage context but is overly broad and could lead an agent toward create_page when append_blocks is the correct choice. No alternatives or exclusions are mentioned.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that deletion is actually archiving, which prevents an agent from promising permanent deletion. However, it does not explain consequences such as what happens to child blocks, whether the operation is reversible, or what response to expect.

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

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

Two short sentences deliver the action, the archival nuance, and the primary use case. There is no filler or redundant information.

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

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

For a single-parameter tool with no output schema, the description covers the core behavior and the triggering user intent. It omits minor details like response shape or error behavior, but an agent has enough information to invoke it correctly in most cases.

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

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

Schema description coverage is 100%, and the only parameter block_id is already described as 'Block ID to delete.' The description adds no additional context about where the block ID comes from or its format, but the schema fully documents 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 states a specific action and object: 'Delete a block (archive it).' The parenthetical 'archive it' clarifies the exact semantic, and 'remove content from a page' distinguishes this from sibling tools like append_blocks or update_block.

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

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

The description explicitly says when to use the tool: 'Use when user wants to remove content from a page.' It doesn't mention alternatives or exclusion criteria, but the usage context is clear and unambiguous.

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 adequately conveys a read-only retrieval operation. It states what the call returns (schema and properties), but does not mention permissions, errors, or rate-limit 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?

Two sentences, no filler, and the core action is front-loaded. Every sentence adds 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?

For a one-parameter get operation, the description is largely complete: it explains the purpose, return object type, and likely user intent. It could still clarify how this relates to query_database or what 'properties' includes, but the information is otherwise sufficient.

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

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

The input schema already documents database_id at 100% coverage, so the baseline applies. The description adds no extra meaning about the format, origin, or use of the database_id 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 states a specific verb and resource: retrieve database schema and properties. It is clear about the informational vs content-oriented nature by mentioning structure, though it does not explicitly distinguish itself from sibling query_database.

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

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

The description gives an explicit usage condition: use when the user wants to understand database structure. It does not provide exclusion criteria or name alternative tools, 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 provided, the description carries the behavioral burden. 'Retrieve' and 'view' clearly signal a read-only operation, and 'properties and metadata' scopes what the agent should expect. It does not go into auth or error behavior, but for a simple read tool this is adequate.

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 resource, followed by a clear usage condition. 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 read tool with no output schema, the description adequately states what is retrieved and when to use it. It could be slightly more explicit that page content is not included, but 'properties and metadata' already implies that boundary.

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 page_id property is already described as 'Notion page ID or URL.' The tool description adds no additional parameter meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description begins with a specific verb and resource: 'Retrieve a page's properties and metadata.' This clearly distinguishes the tool from get_page_content (which likely returns content) and get_database (which targets databases).

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 an explicit usage cue: 'Use when user wants to view page details or check properties.' It does not, however, mention when not to use it or name alternatives like get_page_content, so it stops 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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states that it 'Retrieves' content, which implies a read operation, but does not disclose pagination behavior, output format implications, authentication requirements, or any potential size limitations. The schema's 'format' parameter suggests significant behavioral variation that the description ignores.

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

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

Two concise sentences with no filler. The first sentence states the core function, and the second provides a usage trigger. Every piece of text 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 and no annotations, the description should provide more context about return values and behavior. It does not mention that the 'format' parameter changes the response shape, nor does it clarify what 'content blocks' means or how the result differs from get_page. The description is too minimal for an agent to fully understand consequences of 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 100%, so both parameters ('page_id' and 'format') are already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, such as guidance on choosing between markdown, blocks, or plain_text. Baseline 3 is appropriate.

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

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

The description clearly identifies the action ('Retrieve all content blocks') and the resource ('a page'). It is specific enough to distinguish from the sibling 'get_page', which likely fetches page metadata, though it does not explicitly name that sibling as an alternative.

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

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

The description provides an explicit usage condition: 'Use when user wants to read the full content of a page.' This gives clear context for when the tool is appropriate, though it does not discuss when not to use it or mention alternatives like 'get_page' for metadata-only requests.

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. 'Get details' reasonably implies a read operation, but the description does not disclose return content, error behavior, or whether any permissions are needed. It is adequate but minimal.

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

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

Two short sentences with no filler. The action and usage context are front-loaded, and every word contributes to the tool's purpose.

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

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

For a simple single-parameter lookup, this is mostly sufficient. However, with no output schema, the description leaves the exact return details unspecified and gives no guidance on invalid user IDs or failure cases, which is a clear 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 100% and the single user_id parameter is already documented as 'User ID'. The description adds no additional semantic meaning, but the schema fully handles parameter understanding, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Get') and resource ('details about a specific user'), clearly indicating a singular lookup. It distinguishes from the sibling list_users by emphasizing 'specific user', though it does not name that alternative.

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

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

Provides an explicit usage context: 'Use when user needs info about a team member.' It does not mention when not to use the tool or point to alternatives like list_users, but the condition is clear enough for basic 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?

With no annotations, the description carries the full burden of behavioral disclosure. It clearly implies a read-only operation, but it does not mention pagination behavior, ordering, or response structure, even though page_size exists as a parameter.

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

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

The description is two short sentences with no redundant content. The primary action is stated first, and the usage context follows immediately. It earns its place efficiently.

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

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

The tool is simple with one optional parameter, but there is no output schema and no annotations. The description leaves out return-value details and pagination expectations, which would help an agent fully anticipate the tool's 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 schema covers page_size 100% with 'Number of users to return,' so the description adds no new parameter meaning. Per the baseline, this is sufficient since the schema already documents 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 states a specific verb and resource: 'List all users in the workspace.' This clearly identifies the tool's function. However, it does not explicitly differentiate from the sibling tool get_user, though 'all users' implies a collection-level 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 description provides clear context: 'Use when user needs to reference team members.' This tells the agent when it is appropriate, but it does not mention alternatives or exclusions such as using get_user for a single user.

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 communicates a read-only query operation with optional filters and sorts, but does not disclose response shape, pagination behavior, or how filters/sorts are applied. This is adequate but thin.

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

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

Two sentences with no filler. The core operation is front-loaded, and the usage cue is stated immediately afterward. Every sentence contributes 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?

The description is adequate for simple invocations, but with no output schema and nested filter/sort objects whose schema descriptions are vague, an agent still lacks concrete guidance on constructing complex filters or interpreting results. It relies on external Notion knowledge.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds that filters and sorts are optional and that the goal is retrieving specific entries, but it does not add meaning beyond the schema's own parameter 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 names a specific verb ('Query'), a target resource ('a database'), and the intended outcome ('retrieve specific entries'). This distinguishes it from sibling tools like get_database (metadata) and search (global search) without needing to inspect their schemas.

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

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

The description explicitly says to use the tool when the user wants to retrieve specific entries from a database. It does not name alternatives or exclusions, but the primary usage context is clear and not misleading.

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 workspace-wide search scope and that it matches keyword or title, which gives basic behavioral context. However, it doesn't state whether the operation is read-only, how results are returned, or what limits/defaults apply, leaving noticeable ambiguity.

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

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

Two sentences with no filler: the primary action and scope are front-loaded, followed by a direct use-case statement. Every word earns its place, and the length is appropriate for a straightforward search 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?

The tool has four parameters and no output schema or annotations, so the description must provide adequate context for correct invocation. It explains what is searched and when to use it, but it leaves out details like result format, pagination, default sorting, and any implicit limitations, which an agent might need for reliable 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 all four parameters are already documented in the input schema. The description adds a slight hint that the query targets keyword or title, which maps to the query parameter, but it adds nothing about page_size, filter_type, or sort_direction. Baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Search across all pages and databases in the workspace.' It also clarifies the intended use ('find content by keyword or title') and the workspace-wide scope. It doesn't explicitly name sibling tools like query_database, but the scope distinction is evident.

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 phrase 'Use when user wants to find content by keyword or title' provides a clear trigger condition for invocation. It doesn't explicitly mention alternatives or when not to use the tool, but the context is sufficient for an agent to select it in obvious search scenarios.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool updates content but does not disclose that existing content is replaced, whether the block must already exist, or any side effects or permissions required. This is a significant gap 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 two concise sentences with no redundant wording. The core action is front-loaded in the first sentence, and the usage guidance is brief and direct.

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 tool, the description covers the basic action and usage context. However, the absence of annotations and output schema means the description should ideally note replacement behavior or error conditions to be fully complete. It is adequate but has clear gaps.

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

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

Schema description coverage is 100%, so each parameter (block_id and content) is already documented in the schema. The description adds the context of 'modify specific content' but does not provide additional parameter-level detail beyond what the schema offers, aligning with 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 specific verb ('Update') and resource ('an existing block's content'), clearly identifying the tool's function. It differentiates from sibling tools like update_page and append_blocks by focusing on modifying existing block content rather than page-level updates or adding new blocks.

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 phrase 'Use when user wants to modify specific content' provides an explicit trigger condition for when to invoke this tool. It gives clear context for usage, though it does not explicitly mention exclusions or compare against alternatives like append_blocks or delete_block.

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 disclosing behavioral traits. It only clarifies that content blocks are not updated; it does not mention permissions required, whether updates merge or replace existing properties, whether archived changes are reversible, or any side effects.

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

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

The description is two sentences with no filler. The core action and exclusion are front-loaded, and the use case is stated efficiently.

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

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

For a mutation tool with no annotations and no output schema, the description is too thin. It does not specify the expected format for database properties, how archived behaves when combined with properties, or what the response will be, leaving an agent to guess about important invocation 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 100%, so the baseline is 3. The tool description adds some contextual meaning to the 'properties' parameter by tying it to page metadata and database properties, but it does not explain the expected structure of the nested object or how archived interacts with properties.

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

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

The description clearly states the action ('Update a page's properties'), the resource (page), and explicitly excludes content blocks, differentiating it from sibling tools like update_block and append_blocks. It also names the intended use case: modifying page metadata or database properties.

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 a direct 'Use when' condition and clarifies that content blocks are out of scope, which implicitly steers agents toward update_block or append_blocks for content edits. However, it does not explicitly name those alternatives or state when not to use this tool beyond the content-block exclusion.

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