remnus

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

The description clearly discloses that added comments cannot be edited or deleted afterwardhistorically, an important behavioral caveat not in the schema. It also clarifies that the comment lives in a separate thread from the markdown body. The annotation makes clear this is a write mutation, so no contradiction.

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 pack the essential constraints: thread separation, comment purpose, immutability, length limit, and the alternative tool for revisions. 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?

The description covers the behavior, the main restriction, and the appropriate alternative tool. Combined with the 100% schema description coverage and annotations, an agent has 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 description coverage is 100%, so the schema already defines body, kind, pageId, and contextRunId. The description adds useful context that page content should not be placed in the comment, but leaves parameter semantics mostly to the schema.

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

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

The description states that the action adds a comment to a page or database row, clarifying that it creates a thread separate from the markdown body. It also indicates the intended use cases: running notes and closure/complete notes. This leaves no ambiguity about the tool's purpose.

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 identifies when to use an alternative tool: "use update_page for content you need to revise." It also frames the tool as appropriate for running notes or closure notes, making the decision boundary clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable behavioral context beyond the annotations: the confirm-gated execution model, the preview behavior when confirm is false, concurrent execution, and per-entry ok/error reporting. It does not contradict the annotations.

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

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

Three sentences, each earning its place: the first states scope and limit, the second explains the confirm gate, the third explains concurrency and error isolation. The most important operational detail (confirm) is front-loaded, and the sibling comparison is placed at the end where it adds differentiation without distracting.

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 the core usage, safety gate, concurrency behavior, and error handling. The output schema exists, so return values need not be described. The only minor gap is that it doesn't mention the contextRunId parameter or Strict context requirements, but the schema covers that parameter fully, so the description is complete enough for an agent to call 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?

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds context for confirm (preview vs execute) and pageIds (workspace items or database rows), but these are also partially covered in the schema. The description does not add significant new meaning beyond the schema, so a 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 ('Delete'), a specific resource ('multiple workspace pages, databases, or database rows'), and a key constraint ('max 100'). It also distinguishes itself from the sibling bulk_update_pages by noting the per-entry error behavior, so an agent can tell them apart.

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 explains when to use the tool (to delete multiple items in one call) and how to use it safely: confirm: true executes, omitting or false previews. It also names the alternative bulk_update_pages and explains why this tool is preferable for deletions where one bad id should not fail the whole batch.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral details: the max 100 item limit, the strict refusal (no partial moves) when target columns don't match, and the never-silently-drops-properties guarantee. It also clarifies that newParentId=null means workspace root. These go beyond the structured annotations without contradicting them.

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

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

The description is a single dense paragraph that front-loads the core purpose and limit, then clearly separates the two modes with semicolons and conditional clauses. Every sentence adds necessary information—no filler, no redundancy. The structure makes the mutual exclusivity and refusal behavior 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?

Given the tool's complexity (two modes, a max limit, a strict refusal condition, and an output schema that is present), the description is remarkably complete. It covers all operational aspects an agent needs to call it correctly: the modes, the constraint, the failure behavior, and the root-parent semantics. Annotations already handle safety, so nothing critical is missing.

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

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

Schema description coverage is 100%, so all four parameters are documented. The description adds meaningful semantic context: it links newParentId and targetDatabaseId to the two mutually exclusive modes, explains that exactly one must be given, and clarifies that newParentId can be null for workspace root. This supplements the schema's per-field descriptions with cross-parameter relationships and usage constraints.

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 (move), resource (items), and scope (multiple, max 100). It clearly differentiates from the sibling move_item by being the batched version, and distinguishes the two modes (sidebar reparenting vs cross-database). The purpose is unambiguous and directly tells an agent what this tool does.

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 explains the two modes and the exact constraint that exactly one of newParentId or targetDatabaseId must be given. It references move_item as the single-item counterpart, implying single-item moves should use move_item. It also describes the refusal behavior for incompatible cross-database moves. It doesn't explicitly list when-not-to-use alternatives beyond that, but the context is clear enough.

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

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

The description discloses critical behavioral traits beyond annotations: concurrent execution, non-atomicity, partial success on failure, and the fact that the error doesn't indicate which entries failed. This is exactly the kind of context an agent needs to handle failures correctly. Annotations already indicate idempotentHint=true and destructiveHint=false, and the description does not contradict them.

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 and information-dense. It front-loads the core function, then explains semantics, then provides actionable warnings. Every sentence earns its place, and the structure flows logically from what → how → caution.

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

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

Given the tool's complexity (bulk operation with concurrency and partial failure), the description covers the essential behavioral aspects, parameter semantics, and failure handling. The output schema exists, so return values don't need to be described. The only minor gap is not explicitly stating when to use this vs. update_page, but the name and description make that obvious.

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 context about merge semantics (partial patch, properties merged, title synced) which enriches the meaning of the 'updates' parameter, but it doesn't add syntax-level details beyond the schema. 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 states the tool's function: updating multiple pages or database rows in one call, with explicit reference to the same merge semantics as update_page. It distinguishes itself from siblings like update_page (single vs. bulk) and bulk_delete_pages (update vs. delete).

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 explicit guidance: validate ids first for large batches, re-read before retrying after a failure, and warns about non-atomic behavior. It also references update_page for semantics, giving the agent a clear comparison point. It doesn't explicitly name alternatives, but the sibling list and the reference to update_page make the usage context 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?

The annotations already communicate that this is a mutating operation (readOnlyHint=false). The description adds a non-obvious behavioral detail beyond that: a 'Title' text column is always prepended if not provided. This is exactly the kind of side effect an agent needs to know before constructing a schema.

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

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

Two short sentences with no filler. The core purpose is front-loaded in the first sentence, and the second sentence adds the one caveat worth surfacing. Everything present 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 mutating tool with nested parameters, the rich input schema and output schema carry much of the detail an agent needs. The description supplies the most surprising runtime behavior (Title prepending), though it leaves selection guidance against create_database_view and update_database_schema to the agent.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description adds value only for the schema parameter via the Title-prepending behavior; it does not enrich the semantics of name, parentId, knowledge, or contextRunId. 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 action ('Create') and resource ('a new database'), and further clarifies that it supports a custom schema. This clearly separates it from siblings like create_database_view and update_database_schema, which concern different operations and resources.

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 explicit when-to-use or when-not-to-use guidance, and no alternative tools are named. The phrase 'Create a new database' implies this is for initial creation rather than updating a schema or creating a view, but the agent must infer that distinction from the tool name and siblings.

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

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

The description aligns with annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false) by presenting a mutation. It adds some behavioral context, such as auto-picking a select/status column for kanban and a date/datetime column for calendar, but much of this repeats the schema's own property descriptions. It does not disclose failure modes or side effects beyond the annotations already conveying the safety profile.

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

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

The description is three sentences with no filler. The core action is front-loaded, and the kanban/calendar nuances and prerequisite are packed into the following two sentences without 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?

Given that the schema carries detailed parameter documentation and an output schema is present, the description covers what an agent needs most: the prerequisite schema lookup and the ambiguous auto-pick behavior. It could be slightly more complete with an explicit 'create vs update' routing note, but the sibling names largely cover that.

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

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

Schema coverage is 100% and the property descriptions already document groupByCol, dateCol, and type in detail. The description nevertheless adds practical meaning by connecting parameter choice to view behavior and by telling the agent to call get_database_schema to resolve valid column ids/names, which directly helps fill databaseId and the column parameters.

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

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

The description opens with a precise operation: 'Add a new saved view (table, kanban, or calendar) to a database.' It names the resource, the action, and the supported variants, making it immediately distinguishable from siblings like create_database, create_page, and update_database_view.

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 clear, actionable precondition: 'Use get_database_schema first to see column ids/names.' It also explains when the optional kanban/calendar columns are needed and how auto-picking behaves. However, it does not explicitly contrast create with update_database_view or state when not to use this tool, so it falls short of a 5.

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

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

The description discloses useful behaviors beyond the annotations: properties keys can be column names or ids and are matched case-insensitively, and title is always mirrored into the row's own title property. It adds meaningful behavioral nuance without contradicting the annotations.

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

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

Two tightly written sentences with no filler. The core distinction between page and row creation is front-loaded, and the additional row-specific behavior is introduced in a compact second sentence.

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 eight parameters and nested objects, but the input schema covers every parameter and an output schema is present. The description adds the key conceptual distinction between pages and rows. It does not mention recurrence or contextRunId, but both are well-documented in the schema.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds cross-parameter semantics by explaining the relationship between parentId/databaseId modes and the properties key-matching behavior. This goes beyond individual parameter descriptions and helps agents construct valid calls.

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') and resource ('standalone page' or 'database row') and immediately clarifies the two distinct creation modes via parentId and databaseId. This clearly differentiates the tool from create_database and update_page, which operate on different resources.

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

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

It gives clear context for when to use this tool: creating a new page or database row, with explicit direction on how to choose between parentId and databaseId. It does not explicitly name alternatives or state when not to use it, but the creation-focused guidance is solid.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds two valuable behaviors: the confirm flag requirement and the invariant that a database must always have at least one view. This goes beyond the annotations and helps the agent understand preconditions and consequences.

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 highly concise with two sentences that convey all essential information without filler. Critical constraints (confirm flag and keep-one-view rule) are front-loaded, and every word 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 the presence of a complete output schema, annotations declaring destructive behavior, and a well-documented parameter list, the description addresses the key operational constraints (confirm flag, view invariant). It does not describe error conditions or side effects beyond the invariant, but this is reasonable for a destructive operation with clear annotation coverage.

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

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

The input schema provides 100% description coverage for all four parameters, including their meanings and sources. The description does not add any parameter-specific details beyond the schema, but since the schema is thorough, a 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?

The description clearly states the verb ('Delete') and the resource ('a saved view from a database'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools like create_database_view and update_database_view by focusing only on deletion.

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 instructs that 'confirm: true' is required, which is critical for usage. It also implies that the tool should not be used if the database would be left with zero views, providing a situational constraint. It doesn't explicitly name alternatives, but the distinction is implied by the operation.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds a crucial behavioral layer: the confirm flag converts the operation into a preview without it. This goes beyond the annotations and explains the two-step deletion flow. It does not cover reversibility or permissions, but the preview mechanism is a significant addition.

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

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

The description is a single, well-structured sentence that front-loads the action and immediately explains the confirm requirement. It is concise with zero fluff, and the preview behavior is stated early, making it easy for an agent to grasp the core semantics quickly.

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 the essential behavioral requirement (confirm flag) and the tool's scope, and an output schema exists to detail return values. It does not mention the contextRunId requirement for strict contexts or contrast with bulk_delete_pages, but given the schema covers those and the output schema exists, the description is adequately complete for safe usage.

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 provides 100% coverage with clear descriptions for pageId, confirm, and contextRunId. The description reiterates the confirm behavior but does not add new parameter-level insights beyond what the schema states. The mention of database row ID is already in the schema, so the description adds minimal extra value.

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 verb 'Delete' and the resource types: workspace page, database, or database row. It also highlights the critical confirm/preview behavior, making it distinct from sibling tools like bulk_delete_pages and delete_database_view. The specificity leaves no ambiguity about what the tool operates on.

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

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

The description implies usage for single deletions and mentions the preview mechanism, but it does not explicitly contrast with sibling tools like bulk_delete_pages for multiple items or delete_database_view for views. No when-not-to-use guidance is provided, leaving some routing to the agent to infer from the sibling names.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by detailing what the tool returns (pages/databases edited, database rows edited, items deleted) and explaining cursor behavior. It provides sufficient behavioral context beyond the annotations.

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

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

The description is concise and front-loaded with the core purpose. Two sentences efficiently convey the tool's functionality and usage pattern, with no 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?

Given the tool has an output schema (not shown) and is relatively simple with only three optional parameters, the description is complete. It covers the primary use case, parameter relationships, and initialization flow, meeting the agent's needs for correct invocation.

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

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

The schema provides full descriptions for all three parameters, but the description adds critical semantic context: the priority of cursor over since, the effect of omitting both for a full crawl, and the mention of return fields (nextCursor, updatedAt). This significantly enhances the agent's understanding 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 the tool's purpose: retrieving a compact list of workspace changes since a given time or cursor. It specifies the resource (workspace changes) and action (get), and differentiates from siblings by emphasizing incremental syncing, which is unique among the listed 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?

The description explicitly states it is built for recurring agents to sync incrementally and explains when to use the `since` vs `cursor` parameters, including bootstrapping a full crawl. However, it does not explicitly mention when not to use the tool, such as for ad-hoc queries where other tools like query_database or search_workspace might be more appropriate.

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

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

Description adds specific behavioral context beyond annotations (readOnlyHint=true): 'without fetching any rows' and details on what is inspected. No contradictions. Minor room for further details on constraints.

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 efficient sentences: first states function, second gives use cases. Front-loaded, 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?

Given low complexity, single parameter, and output schema exists, the description fully covers purpose, usage, and behavioral aspects.

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?

Single parameter 'databaseId' is fully described in schema (100% coverage). Description does not add further semantics beyond the tool's purpose, which is acceptable.

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?

Clearly states it retrieves column schema and saved views, explicitly noting it does not fetch rows. Distinguishes from querying databases and from view manipulation 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?

Explicitly states when to use: before querying to inspect columns, and before calling view-related tools to get ids/configs. Mentions sibling tools contextually.

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?

Beyond readonly annotation, it discloses auto-detection of page vs row, and the token-cheap skim behavior of outline mode. It does not document edge cases or failure behavior, but covers the key runtime 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?

Efficient, front-loaded purpose, then behavioral guidance. Every sentence adds information.

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

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

Given a complete output schema and 100% parameter coverage, the description fills the remaining gap by explaining auto-detection and when to use outline mode. No missing context for correct invocation.

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

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

The schema covers all parameters with descriptions throughout, so the main description adds little parameter meaning. The outline-vs-full guidance is repeated from schema, but the schema itself is descriptive enough. Slight redundancy to schema, hence not 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 states a specific verb and resource: 'Get content of a workspace page or database row by its ID'. It also notes auto-detection, which differentiates it from siblings like get_pages (plural) and search_workspace.

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 clear guidance on when to use the 'outline' mode ('before deciding whether to fetch the full content') vs full mode dependencies. Does not compare against sibling tools like get_pages or search_workspace, but the purpose is self-contained enough for an agent to select 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?

The description discloses partial-failure behavior: one missing/inaccessible ID does not fail the batch, and the consumer should check each entry's 'ok' field. This adds substantial value beyond the readOnlyHint annotation, because it tells the agent how to interpret results and handle errors when using the 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 three sentences, each with a distinct purpose: what the tool does, error behavior, and routing to an alternative. There is no fluff, it is front-loaded, and the alternative guidance is placed after the core behavior but remains 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?

Given that annotations declare read-only and open-world hints, and an output schema exists (so return format is documented elsewhere), the description still supplies the remaining critical knowledge: ID list nature, batch failure handling, and when to route to query_database. An agent has enough information to decide when to call and how to code the result handling.

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 covers the parameters with 100% description coverage, describing both pageIds and mode. The description adds the nuance that the ID list can be mixed pages and database rows, but this is largely already present in the schema via 'Page/row IDs'. Thus the description provides minor extra context but not critical semantic clarification.

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 clear verb and resource: 'Get multiple workspace pages or database rows by ID in one call'. It also specifies the target scenario (for a specific, already-known list of IDs), and names exact sources (search_workspace, get_related_pages, get_changes_since), which distinguishes it from siblings like get_page and 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 explicitly states when to use this tool (for a specific, already-known list of IDs) and when not to (for many rows sharing one database, prefer query_database with filters/fields). This gives the agent clear decision criteria, including the rationale that query_database is 'one query, not N lookups'.

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

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

Annotations already declare readOnlyHint=true, so the description adds value by stating it costs a fraction of re-reading pages and returns only titles and IDs. It also covers database row behavior. No contradictions.

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 wasted words, front-loaded with the core purpose. Every sentence adds essential 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 tool returning multiple relationship types, the description covers the main components. The output schema handles return values. Minor omission: no mention of pagination or limits, but the description is sufficiently complete for typical 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?

The single parameter pageId is fully described in the schema with 100% coverage. The description adds context that it accepts the same IDs as get_page (standalone page, database, or database row), enhancing understanding 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 the tool gets a page's knowledge-graph neighborhood in one call, listing specific components (parent, child pages, outgoing links, backlinks, sibling rows). It distinguishes from sibling tools like get_page by noting it returns only titles and IDs, not bodies.

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 advises using this tool for efficient exploration and suggests following up with get_page for details, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=false. Description adds 'roles and join dates' but this is likely covered by the output schema. It does not disclose additional behavioral traits like pagination or size limits.

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

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

Single sentence, front-loaded with action and key details. Every word is useful.

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 parameters and presence of output schema, description adequately covers purpose and output content. It is complete for a simple list 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?

No parameters exist, and schema description coverage is 100% (empty). Baseline 3 applies as description adds no parameter information.

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?

Description uses specific verb 'List' and resource 'members', clearly indicating output includes roles and join dates. This distinguishes it from sibling tools like list_workspace.

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

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

No explicit guidance on when to use this tool versus alternatives. However, there are no directly competing siblings for listing members, so the need is lower. Still, it lacks any usage context.

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

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

Annotations provide readOnlyHint=true, indicating safe read. Description adds pagination behavior and optional parent filter, which are not in annotations. No contradictions; adds useful context beyond structured fields.

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

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

Two concise sentences, front-loaded with purpose and key features (pagination, optional filter). Every sentence 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?

Given output schema exists (no need to describe return format) and all parameters are documented, the description covers what tool does, its filtering, and pagination. Sibling tools are many but description is self-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?

Schema coverage is 100% with clear descriptions for each parameter. Description adds minimal value: 'optionally filter by parent' reinforces parentId, and 'Supports cursor-based pagination' provides context. 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?

Description clearly states 'List workspace items (pages and databases)', with a specific verb and resource. It distinguishes from sibling tools like get_page or search_workspace by scope (all items vs single/search).

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?

Implied usage: use to list workspace items. No explicit when-not-to-use or alternative tools mentioned, though sibling names provide context. Lacks guidance on differentiating from query_database or search_workspace.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=true, covering mutation and idempotency. The description adds the null behavior but does not disclose potential side effects like child item handling or permission requirements. No contradiction with annotations.

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

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

Two concise sentences with the primary action front-loaded. The null behavior is stated clearly, and there is no extraneous 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 simple single-item move operation with an output schema, the description covers the key usage (null root) and annotations cover the safety profile. It does not mention contextRunId, but the schema handles that, so nothing critical is missing.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description repeats the null guidance already present in the newParentId schema, adding no new semantic meaning beyond what is structurally available.

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 verb 'move' with a specific resource (sidebar item) and destination (new parent), and distinguishes it from bulk_move_items by implying single-item scope. It also explains the null-to-root behavior, leaving no ambiguity about what the tool does.

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 usage note for passing null to move to root, but does not mention when to use this tool versus bulk_move_items or any preconditions. The intended use for single items is implied but not explicitly contrasted with alternatives.

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

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

Annotations provide readOnlyHint=true and openWorldHint=false, but the description adds valuable behavioral context: it ranks lexical matches, prefers human-reviewed OKF knowledge, penalizes stale/deprecated concepts, and adds link-graph neighbors. This goes beyond the annotations without contradicting them.

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 main action is front-loaded ('Build one task-specific, token-budgeted context pack'), followed by concise behavioral details and a usage directive. Every sentence earns its place.

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

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

The tool is complex with 5 parameters and an output schema. The description explains the core behavior (ranking, preference, link-graph) and usage context, which is sufficient for an agent to decide when to call it. Output structure is left to the schema, which is acceptable. Minor gap: doesn't describe the exact format of the returned context pack, but that's covered by the output schema.

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

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

Schema description coverage is 80% (4 of 5 params described), so baseline is 3. The description mentions 'prefers human-reviewed OKF knowledge' which hints at trustPolicy, but it doesn't elaborate on parameter syntax or usage beyond what the schema already specifies. No significant additional meaning is added.

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 'Build' with a resource 'task-specific, token-budgeted context pack from relevant workspace pages' and details the ranking/preference behavior. It clearly distinguishes itself from siblings like search_workspace or get_pages by focusing on aggregating context rather than returning raw pages.

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 'Use this before multi-page product or coding work instead of many search/get_page calls', giving a clear when-to-use and naming the alternative pattern it replaces. Lacks an explicit when-not-to-use but the 'instead of many' implies it's not for single-page lookups.

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

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

Annotations already declare readOnlyHint=true, indicating a safe read operation. The description adds that it supports filtering but does not disclose further behavioral traits such as pagination, rate limits, or what happens when no results are found. With annotations covering the safety profile, the description provides moderate additional value.

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

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

The description is a single sentence that is front-loaded with the core action and immediately lists filter capabilities. Every word adds value; 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?

An output schema exists, so return value explanation is not required. However, the description omits details like log retention period, ordering defaults, or maximum date range. For a tool with 5 optional parameters and no required fields, additional context would improve completeness.

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%, with all 5 parameters already described in the input schema. The description adds a summary of filter categories (tool name, status, date range) but does not provide meaning beyond what the schema already offers. Baseline 3 is appropriate given high coverage.

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

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

The description clearly states it queries the MCP agent activity audit log for this workspace, specifying filtering by tool name, status, and date range. This is a specific verb+resource combination that distinguishes it from sibling tools like query_database or search_workspace.

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

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

No guidance is provided on when to use this tool versus alternatives. Sibling tools include get_changes_since and query_database, which could be confused without explicit differentiation. The description does not mention when not to use it or list alternative tools.

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

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds valuable behavioral context: row markdown bodies are omitted by default, fields projection affects cost, and pagination is cursor-based. It doesn't describe the exact response format, but the output schema exists and covers that. The description adds meaningful behavioral detail beyond the annotations.

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

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

The description is three sentences with no wasted words. It front-loads the core purpose, then immediately covers the most important behavioral caveat (bodies not included), then provides optimization guidance and pagination info. Every sentence earns its place.

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

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

For a read-only query tool with a rich output schema and 100% parameter coverage, the description is complete. It covers the key caveat (bodies omitted), the optimization strategy (fields projection), the pagination mechanism, and the alternative for single rows. An agent has everything it needs to call this 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?

Schema description coverage is 100%, so the schema already documents all parameters. The description adds some context about the 'fields' parameter (add 'content' for bodies, cheaper on wide tables) and mentions cursor-based pagination, but it doesn't add significant new meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Get schema and rows of a database.' It distinguishes itself from siblings by explicitly noting that row markdown bodies are not included by default and pointing to get_page for a single row. This makes it easy for an agent to understand what this tool does and how it differs from related tools like get_database_schema or get_page.

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

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

The description provides explicit guidance on when to use this tool and when to use alternatives: 'add "content" to fields when you need them, or get_page a single row.' It also explains the benefit of projecting with fields ('much cheaper on wide tables') and mentions cursor-based pagination. This is clear, actionable usage guidance.

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

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

Annotations declare readOnlyHint=true, so no contradiction. Description adds value by detailing search scope (standalone pages, databases, rows) and matching behavior (title/content, case-insensitive substring), which is beyond annotations.

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

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

Two sentences that convey purpose, scope, and usage without unnecessary words. Highly concise and front-loaded with key information.

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

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

Given annotations and output schema, the description covers core behavior and usage. Could mention pagination or result fields, but output schema fills that 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 coverage is 100% with clear descriptions. The description does not add new details about parameters beyond what the schema provides, meeting baseline expectations.

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 searches workspace by title and content, specifies matching targets (pages, databases, rows), and gives a use case. This distinguishes it from siblings like list_workspace 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?

It provides explicit context: 'Use it to locate an item before reading or updating it.' However, it does not specify when not to use it or name alternative tools explicitly.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral details beyond annotations: the requirement for confirm: true during removal, the data-loss warning, and the title column restriction. This helps the agent understand side effects and necessary confirmations.

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 concise: two sentences that front-load the purpose and immediately cover the critical destructive behavior and constraints. No wasted words; every sentence earns its place.

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

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

For a schema-modification tool, the description covers the essential aspects: purpose, destructive nature, confirm requirement, and a specific restriction. The output schema is present, so return values are presumably documented there. It could mention idempotency or the need for a contextRunId in strict mode, but those are secondary.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters. The description adds minimal extra semantics—it restates the add/remove purpose and mentions the confirm requirement, but doesn't provide syntax or format details beyond the schema. 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 states the tool's function: 'Add or remove columns from a database schema.' This is specific, uses a clear verb and resource, and distinguishes it from sibling tools like create_database or update_database_view. The destructive nature is also highlighted.

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 on when to use the tool (adding/removing columns) and includes important constraints like 'requires confirm: true' for removal and 'The title column cannot be removed.' However, it does not explicitly mention alternatives or when not to use this tool, though the specific scope makes it fairly clear.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context: config fields are merged into the existing config (not replaced), and the view type is immutable. This goes beyond what annotations provide, though it doesn't detail side effects like whether renaming affects references.

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 sentences with no filler. The core action and merge behavior are front-loaded, the immutability constraint is stated clearly, and the pointer to get_database_schema is a useful final note. Every sentence earns its place.

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

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

The description is complete for a mutation tool with an output schema and full parameter documentation. It covers the key behavioral nuance (merge vs replace), the immutability constraint, and how to find required IDs. It doesn't mention potential errors or permission requirements, but given the annotations and schema coverage, this is a minor 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%, so the schema already documents all parameters. The description adds meaning by explaining the merge semantics for config and explicitly listing example fields (filters, sorts, groupByCol, dateCol, cardProperties). It also clarifies that icon can be an emoji, lucide:Name, or image URL, which is useful beyond the raw 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 states a specific verb ('Rename', 'change', 'patch') and resource ('database view'), and explicitly distinguishes itself from creating a new view when the type needs to change. It also names the sibling tool get_database_schema for finding view IDs, which helps an agent understand exactly what this tool operates on.

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 this tool (rename, change icon, patch config fields) and when not to use it (cannot change view type; create a new view instead). It also points to get_database_schema for finding view IDs and current config shape, which is clear guidance for the correct invocation context.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds valuable behavioral context beyond annotations: partial update semantics ('only fields you pass are changed'), merge behavior for properties, and the side effect that title also updates the row's title property. It also discloses that recurrence creates real rows and that contextRunId is required for mutations in Strict context. This is strong behavioral disclosure that goes beyond the structured fields.

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

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

The description is two sentences, front-loaded with the core purpose and the most important behavioral rule (partial updates). The second sentence adds essential merge semantics. It is concise and every sentence earns its place. Slightly more could be said about when not to use it, but the structure is efficient and readable.

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

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

Given the tool's complexity (8 params, nested objects, output schema present), the description covers the critical behavioral aspects: partial updates, merge semantics, title side effect, recurrence row creation, and Strict context requirement. The output schema exists so return values need not be described. The only gap is not explicitly routing to bulk_update_pages for batch scenarios, but the description is complete enough for an agent to call this tool 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%, so the schema already documents all parameters. The description adds meaning beyond the schema by explaining the merge semantics for properties and the title side effect, which are not evident from the schema alone. It also clarifies the recurrence behavior ('Occurrences are created as real rows') and the contextRunId requirement. This exceeds the baseline 3 for full 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 clearly states the tool updates a page or database row, and explicitly distinguishes the two target types. It also names the sibling tool it is not (create_page) implicitly by focusing on update semantics, and the title 'Update page' aligns with the description. The verb 'update' plus resource 'page or database row' is specific and unambiguous.

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

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

The description explains when to use this tool (to update a page or database row) and provides key usage context: partial updates, merge semantics for rows, and title behavior. It does not explicitly name alternatives like bulk_update_pages or create_page, but the context signals and sibling list make the distinction inferable. The description could be stronger by explicitly saying 'for bulk updates use bulk_update_pages' but the core usage guidance is clear.

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