Arbo

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. Beyond the word 'Create', it says nothing about atomicity (does a partial failure roll back?), permissions required, the 500-node ceiling, or response shape for a large mutation.

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

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

Two tight sentences with the core action front-loaded and the use case second. Every clause earns its place; no restating of the tool name or filler.

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

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

This is a bulk mutation tool with no annotations and no output schema, so the description is the only place behavioral guarantees can live — and it omits partial-failure semantics, ordering/validation of temp_id references, and what the caller gets back. Adequate for identifying the tool, insufficient for calling it safely.

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

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

Schema description coverage is 100%, and the deeply nested node schema documents temp_id/parent_temp_id, seo, zoning_blocks and entry_points thoroughly. The description adds no format or constraint detail beyond echoing those field names, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create multiple pages at once') and adds the mechanism ('from a tree structure'), which clearly separates it from the singular sibling create_node. It stops short of naming that sibling explicitly, so an agent must infer the bulk-vs-single distinction from the name.

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?

'Ideal for generating a full sitemap' gives a concrete usage scenario, implying this is the right choice for whole-site generation rather than incremental edits. However, it names no alternatives and states no when-not-to-use condition (e.g. use create_node for a single page).

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. It discloses that the tool supports rich data structures (zoning blocks, entry points, CTAs, tags), which is useful context beyond the bare 'add a page'. However, it does not mention mutation side effects, idempotency, required authentication, or what happens to related resources, though these are less critical for a straightforward create operation.

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 zero filler: the first states the core action and the hierarchy parameter, the second enumerates the advanced data capabilities. The most important scoping information is 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?

Despite the tool's complexity (14 params, nested objects, no output schema), the description covers the essential purpose and highlights the non-obvious rich-data capabilities. The schema handles detailed parameter semantics, and the description does not need to explain return values for a create operation. It is slightly incomplete regarding edge cases (e.g., what 'Add' implies for existing pages), but it provides enough for an agent to decide to invoke 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?

Schema description coverage is 100%, so the baseline is 3. The description adds conceptual grouping by calling out zoning_blocks, entry_points, cta, and tags as 'rich data', but it does not add format, syntax, or optionality details beyond what the schema already documents. It provides mild extra meaning but does not compensate for any gaps since none exist.

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-resource pair ('Add a page to a project's sitemap'), immediately distinguishing it from siblings like create_project, update_node, and delete_node. It also names the key hierarchy mechanism (parent_id) and the rich-data capabilities, making the tool's purpose unmistakable even without opening the schema.

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

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

The description gives one explicit usage instruction ('Use parent_id to create hierarchy') and implies single-page creation, but it never states when to prefer create_node over bulk_create_nodes or update_node. No alternatives or exclusion criteria are provided, leaving the agent to infer the boundary between single and bulk creation.

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 behavioral burden. It discloses the return value ('Returns the project ID') and implies a side effect (creating a resource), but does not address permissions, idempotency, duplicate-name handling, or failure behavior. The return-value disclosure adds genuine context beyond the name, though the safety profile remains underexplained 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?

Three short sentences deliver the purpose, the return value, and the next workflow step with zero wasted words. Each sentence earns its place and the core action is front-loaded.

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

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

For a 3-parameter creation tool with full schema coverage and no output schema, the description covers the essentials: what it does, what it returns (project ID, which output schema would otherwise convey), and the logical next step. Minor gaps exist around error conditions and prerequisites, but nothing an agent needs to invoke it successfully 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%, with all three parameters (name, accent, client) already documented in the input schema. The description adds no parameter-level detail beyond what the schema provides, which matches the baseline of 3 for 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 uses a specific verb ('Create') with a clear resource ('a new project'), and it differentiates from sibling tools by explicitly naming create_node as the follow-up step for adding nodes. The workflow relationship to bulk_create_nodes and create_node is evident, so an agent can tell this tool apart without opening schemas.

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

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

The description implies usage by stating 'Add nodes with create_node after,' which signals the correct sequencing (create project first, then nodes). However, it never explicitly states when to choose this tool over alternatives, nor excludes cases like bulk project creation or when get_project/list_projects would 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?

With no annotations, the description must carry the behavioral burden. It does disclose a key side effect: the delete is soft and reversible via version history. However, it does not describe the effect on child nodes, potential permissions, or what response the caller should 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?

The description is one tightly worded sentence that front-loads the action before the qualifier. There is no redundant phrasing or filler.

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

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

The schema covers parameters and the default cascade behavior, and the description adds the soft-delete/restore context. Still, because there is no output schema and no annotations, an agent gets no information about return values, error conditions, or permissions, so the description is only minimally complete for a mutation tool.

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

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

Schema description coverage is 100%, so the parameters (project_id, node_id, cascade) are already fully documented in the schema. The description adds no parameter-level meaning beyond the schema, which is acceptable but not value-adding.

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 ('Remove') and resource ('a page from the sitemap'), and the parenthetical clarifies the operation is a soft delete. This makes it immediately clear what the tool does and how it differs from siblings like create_node and update_node.

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 statement of when to use this tool versus alternatives, no prerequisites, and no mention of when to set the cascade option. The intended use is only implied by the name and the verb 'Remove'.

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 present, so the description must carry behavioral disclosure. It reveals the side effect (saved to zoningHtml), the prerequisite, and the cost. It does not mention overwrite behavior or error handling, but core transparency is good.

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, followed by the side effect, prerequisite, cost, and return value in logical order. Every clause earns its place.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential contract: what it generates, where it saves, the prerequisite, cost, and return value. It could additionally explain failure behavior or how zoning blocks are obtained, 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 coverage is 100%, so the baseline is 3. The description adds meaningful context by tying node_id to the requirement that zoning blocks exist and clarifying that output is stored in zoningHtml, going beyond the plain schema descriptions.

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

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

States a specific verb ('generate') and resource ('lo-fi wireframe HTML') plus the target storage field (zoningHtml). This clearly distinguishes it from sibling node management tools like create_node or update_node.

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 explicit context: a prerequisite (zoning blocks must be defined) and a cost condition (1 AI credit or BYOK). However, it does not name alternative tools or explicitly state when not to use it, so it falls just 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?

With no annotations, the description carries the full burden and does a good job on the operational traits: it discloses the AI credit cost (3 credits, quality model), who pays (token account or project owner), and the auth requirement (write access). It stops short of explaining the effect of a write-gated 'get' call or how the list is persisted/returned.

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

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

Three compact sentences with no filler: content first, cost second, access third. Front-loading the content over the cost/access notes is the right ordering, though the first sentence is dense with comma-separated clauses.

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 annotations and no output schema, the description supplies the missing operational context (cost, payer, access level) and characterizes the returned content, so an agent knows what to expect. It is slightly incomplete on whether the call is pure read or has side effects, given the 'get_' name paired with a write-access requirement.

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 project_id, step, and node_id, and the enum for step is self-explanatory. The description adds no parameter syntax, defaults, or filtering semantics beyond what the schema provides, which is the baseline-3 case.

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 the resource (a change list derived from open review comments) and enumerates its content categories: deduplicated/classed comments, out-of-scope requests, and contradictions with decided points. This is specific enough to separate it from list_review_comments and get_review, though the differentiation is by implication rather than an explicit statement.

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

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

There is no when-to-use or when-not-to-use guidance, and no sibling is named as an alternative despite get_review and list_review_comments being obvious neighbors. The 'Requires write access' note is a prerequisite, not usage selection 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that it 'gets' a project, which implies a read operation, but does not explicitly mention that it is read-only, what happens if the project_id is invalid, or any authentication requirements. The phrase 'full sitemap tree' indicates the return content, but other behavioral traits are omitted.

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, focused sentence that states the core action and the key output detail. There is zero wasted wording, and it is appropriately front-loaded with the verb and resource. It is concise without being under-specified.

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 getter with one parameter and no output schema, the description tells the agent what it returns (the project with its full sitemap tree), which is the essential information needed to call it. It does not describe error conditions or response formatting, but given the simplicity and that the return content is stated, it is largely complete. A slight gap is the lack of explicit read-only assurance, but that is minor.

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

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

The schema already documents project_id with a minimal description ('The project ID'), and the schema coverage is 100%. The tool description adds no additional meaning about the parameter format, type constraints, or how it is used. Since the schema covers the parameter, the baseline is 3, and the description does not enhance it.

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 'Get' and the resource 'project', with the specific detail 'full sitemap tree' that distinguishes it from list_projects (which likely lists summaries) and create_project (which creates). This is unambiguous and specific enough for an agent to know exactly what it 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 provides no guidance on when to use this tool versus alternatives. It does not mention that this is the right choice when you need the complete sitemap tree, nor does it contrast with list_projects or create_node. The usage context is entirely implied by the name and description.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose the shape of the returned data (per-page status/version per step, Figma links per breakpoint), which is genuinely useful, and the 'get_' prefix implies a read. But it says nothing about permissions, side effects, or error conditions for a query that reaches across a whole project.

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

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

A single dense sentence with no filler; the most important content (per-page status and version) is front-loaded before the secondary Figma-link detail. Slightly compressed phrasing ('per page, the status and version of each step') costs it a point but nothing is wasted.

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

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

With no output schema, the description must convey the return value, and it does so reasonably well by enumerating pages, step statuses/versions, and per-breakpoint Figma links. Only the absence of any usage context or behavioral caveats keeps it from being fully complete.

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

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

Schema description coverage is 100% for the single required project_id parameter, and the description adds no additional meaning about that parameter. Per the rubric, full schema coverage sets the baseline at 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 names the resource (a project's review) and specifies exactly what it contains: per-page status and version for each design step plus the latest Figma link per breakpoint. That is far more specific than a tautology, though it never explicitly contrasts itself with siblings like get_project or get_change_list, so the agent must infer the boundary.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no reference to any alternative such as get_project or list_review_comments. The agent is left to guess how this differs from the other read tools in the family.

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 must carry the full burden. It states that the operation is read-only in effect ('List') and implies no side effects, which is important behavior. It also adds the token-scoping constraint, indicating it operates within the token's permissions. However, it doesn't detail output format or pagination, which could be relevant, but for a simple list operation the core behavior is clear.

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, concise sentence with no wasted words. It front-loads the verb and resource, and clearly communicates the tool's purpose and scope 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 the tool's simplicity (zero parameters, no output schema), the description is complete enough for an agent to call it correctly. It clearly states what it does and the scope. Minor gaps, such as details about the return format or pagination, are not critical for a simple list operation.

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

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

The tool has zero parameters, and the schema is empty. The description doesn't need to explain any parameters. The score of 4 aligns with the baseline for zero parameters, as no compensation is required.

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 ('List') and resource ('projects') and clarifies the scope ('accessible with this token'). It is clear and distinguishes from sibling tools like create_project or get_project. However, it doesn't explicitly contrast with the sibling get_project, which also deals with projects, though the purpose is 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 implies usage: use this to list projects, but it does not explicitly state when to use it versus alternatives. It doesn't mention when not to use it or point to siblings like get_project for a single project. There's no guidance on scenarios like filtering or pagination.

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

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

With no annotations, the description carries the full behavioral burden. It conveys that comments are scoped to a version and breakpoint, but says nothing about ordering, pagination, empty-result behavior, or permissions, so an agent cannot predict the response shape or 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?

Two short sentences, front-loaded with the resource definition and followed by the most useful flag. The parenthetical '(wireframe or mockup)' is slightly redundant with the schema enum but costs little.

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

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

For a read-only list tool with 100% schema coverage and no output schema or annotations, the description covers what the tool returns conceptually but omits return-field details, ordering, and pagination. Adequate but with 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 all four parameters are already documented in the schema, including open_only. The description restates open_only's behavior without adding format, defaults, or interaction detail, so the baseline 3 applies.

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

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

The description identifies the resource (review comments on a wireframe/mockup, pinned to a version and breakpoint) which lets an agent distinguish it from sibling tools like get_review or set_comment_resolved. It reads as a noun phrase describing the collection rather than an explicit 'list X' verb, but the resource and scope are clear.

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 only guidance is 'Set open_only true to get only the unresolved ones,' which is parameter semantics rather than when-to-use advice. It never says when to call this instead of get_review or how it relates to set_comment_resolved, leaving the agent to infer the retrieval workflow.

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 at all, the description carries the full behavioral burden. It does disclose a real behavioral trait beyond the schema: the required authorization scope (write:nodes, owner or editor) and the fact that the change is reversible (resolved can be reopened). It does not state idempotency, error behavior for an already-resolved comment, or side effects, leaving meaningful gaps 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 short sentences, zero waste, and the core action is front-loaded before the permission note. Nothing is repeated or padded.

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 three-parameter state toggle with no output schema, the description covers the action, the reversibility, and the authorization requirement, which is what an agent needs to call it safely. It stops short of describing failure modes (e.g., resolving a comment that is already resolved) or the response, but those gaps are minor for this tool's complexity.

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%: resolved, comment_id, and project_id each carry their own schema descriptions, including the boolean semantics and where the comment ID comes from. The description only restates the resolved/open duality already documented in the schema, adding no new parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (mark) and resource (review comment) plus the two possible target states (resolved or open again). An agent can distinguish this state-toggle from the read-side sibling list_review_comments and from the generic node/project writers without opening any schema.

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

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

The description implies the tool is used to close out or reopen a review comment, but it names no alternative or condition for choosing it (e.g., use list_review_comments to find the ID first, or get_review to inspect the thread). The only guidance given is a permission prerequisite rather than when-to-use 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose that description supports real newlines and no length limit, and that zoning_html replaces the current wireframe. However, it does not state that update is a mutation (though implied), nor does it mention merge behavior for the SEO block, which is only in the schema. More behavioral detail (e.g., what happens to previous content) would be helpful.

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 relatively concise and front-loaded: it starts with the core purpose and then highlights key specialized fields. It is three sentences, no fluff, and each sentence adds value (newline handling, rich content, zoning_html, annotations). Minor deduction for not being ultra-structural, but it's efficient.

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 (12 parameters, nested objects, no output schema), the description is not fully complete. It explains the most nuanced parameters (description, zoning_html, annotations) but leaves out important details like merge semantics for SEO, how parent_id moves work, and what exactly 'New page type' means. It covers the essentials but gaps remain for an agent to call it correctly in all scenarios.

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

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

Schema description coverage is 75%, and the description adds meaning primarily for the 'description' and 'zoning_html' parameters, emphasizing real newlines and wireframe replacement. However, the description does not elaborate on many other parameters like 'annotations', 'notes', 'rationale', or 'parent_id' beyond what the schema already describes. It adds some value, but not fully compensating for the 25% gap, so 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 that the tool updates a page's properties, a specific verb-resource pairing. It highlights key fields and content capabilities (description, zoning_html, annotations), which helps distinguish it from creation tools like create_node. However, it does not explicitly differentiate itself from other update-related tools in the sibling list (there are none), so a small deduction.

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 does not explicitly state when to use this tool versus create_node or bulk_create_nodes. It is implied that updates are for existing nodes, but there is no direct guidance such as 'use for modifying existing pages, not creating new ones'. The rich content mention suggests use cases, but clear context for when not to use is missing.

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