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 discloses that the block id is auto-generated, explains the layout/content behavior, and describes the blockWarnings outcome on invalid content. This goes beyond the schema and gives the agent a realistic expectation of side effects and validation results.

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 focused paragraph that front-loads the core action, then provides conditional logic, and ends with a warning. Every sentence contributes value, and it avoids redundancy with the schema. It is appropriately sized for a tool with nested objects.

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

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

For a complex tool with nested block objects and multiple parameters, the description covers the key usage aspects: id generation, layout vs. content selection, position behavior, and validation warnings. No output schema is present, but the description could still benefit from a brief note on the return value, though it is not critical for a 'add' 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 schema already describes all four parameters with 75% coverage, but the description adds meaning: it explains the distinction between layoutRegion and content blocks, clarifies that position is content-only, and interprets blockWarnings. This supplements the schema with context that helps the agent pick the right parameter values.

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

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

The description clearly states the action ('Add a block to a page'), names the resource (page), and includes a key detail (auto-generates the block id). It also distinguishes between layout and content blocks via layoutRegion, which separates it from related block-editing 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 provides a clear trigger ('Only call after the user confirms') and specifies when to pass layoutRegion versus omit it, but it does not compare this tool to alternatives like update_page_blocks or update_block_content, nor does it state when to use this tool instead of those. This leaves the agent without sibling-differentiating 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 must disclose behavior itself. It does convey permanence and the need for user confirmation, which are critical for a destructive operation. But it does not explain how 'selected' records are determined (ids vs filter vs allMatching), whether deletion is transactional, or what happens to dependent data like orders or media 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?

Two short, direct sentences. The primary action is front-loaded, and the critical confirmation requirement follows immediately. No wasted words.

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 destructive bulk operation with a nested selection object, no output schema, and no annotations, this description is too sparse. It omits important context about how the selection parameters map to deletion behavior, what happens when both ids and filter are provided, and what the tool returns or whether it can be partially applied.

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 only 50%, and the description adds no parameter-specific meaning. It does not explain the role of modelId or the selection object, and the nested filter sub-parameters (search, status, price range, stockState, hasVariants) are undocumented in both the schema and description. The 'allMatching' flag is described in the schema but not in the description.

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

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

The description clearly states a specific verb ('Bulk-delete'), a resource ('product records'), and a key qualifier ('permanently'). This distinguishes it from singular operations like delete_record and from bulk_update_products, which updates rather than deletes.

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 explicit instruction 'Only call after the user explicitly confirms' provides a strong, safety-critical usage condition. However, it does not differentiate from the single-record delete_record sibling or mention when bulk vs single deletion is appropriate, leaving some routing implicit.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It usefully reveals that a single patch is applied to every selected record, clarifies units (stock in units, price in minor units), and warns that user confirmation is required. However, it does not mention irreversibility, side effects, or what happens if conflicts arise.

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 short sentences with no filler. It front-loads the core action, adds the unit clarification, and ends with the safety condition. 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?

This is a complex tool with nested selection semantics, yet the description omits how selection works (ids vs filter vs allMatching) and what happens when no selection is provided. There are no annotations and no output schema, so the description needs to cover more ground to be complete. The confirmation note is good, but major operational gaps remain.

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 67%, so the description must add some meaning. It does clarify patch behavior and units beyond the schema, but the selection parameter—central to this tool—is not explained at all. Nested filter fields like priceMin, stockState, and hasVariants are left entirely to the schema, which lacks descriptions for them.

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 ('Bulk-update'), a clear resource ('selected product records'), and the exact fields affected (status, stock, price). This distinguishes it from siblings like bulk_delete_products and update_record without needing to open 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 phrase 'selected product records' and 'single patch' clearly imply a bulk operation, contrasting with single-record updates. The explicit instruction 'Only call after the user confirms' provides a firm precondition, though no alternative tools are named or exclusion cases stated.

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

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

With no annotations, the description carries the full burden of disclosure. It indicates cancellation is a consequential action via the confirmation requirement, but it does not state whether cancellation is irreversible, what effects it has, or how it differs from refunding an order.

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 convey the purpose and the critical safety constraint with no filler. The action is front-loaded and 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 state-changing order operation, the description does not disclose side effects, reversibility, or prerequisites beyond user confirmation. The simple schema and lack of output schema increase the need for the description to explain cancellation behavior.

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

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

The description does not explain the orderId parameter, and schema description coverage is 0%, so the parameter name must carry the meaning. 'orderId' is self-explanatory in context, making the tool minimally usable, but the description adds no parameter-specific detail.

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

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

The description uses a specific verb and resource ('Cancel an order') and is immediately clear about the operation. It does not explicitly distinguish this from sibling order tools like refund_order or update_order_details, but the core action 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?

'Only call after the user confirms' is an explicit precondition that tells the agent when it is safe to invoke the tool. It does not discuss when to use an alternative, but for a cancellation action this is a clear, actionable guideline.

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 discloses the destructive scope, the refusal on orders/carts, and the effect of force, while adding a safety confirmation requirement. It stops short of stating irreversibility explicitly or listing exactly which settings are removed, but the core behavior is well covered.

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 purpose-driven sentences structure the description: what it does, when it may be called, and how to handle the blocked case. Every sentence adds information without repetition or fluff.

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

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

For a destructive config-clearing tool with no annotations and no output schema, the description covers purpose, safety, error behavior, and alternatives. The main residual gap is the lack of a success-response description and a slightly broad reference to 'commerce settings' relative to the tool's cart-config name.

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 is 100% documented in the input schema, including the refusal condition and the fact that force overrides it. The description reinforces that with retry guidance, but does not add substantial new parameter semantics beyond the schema's own description.

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

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

The description names a clear verb ('Remove') and resource ('workspace's commerce settings'), with a concrete end state ('back to never-configured'). It also distinguishes itself from the sibling update_cart_config by stating that tool handles individual settings changes.

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 to call only after explicit user confirmation, and provides a concrete retry path for the refused case ('retry with force: true only once they confirm'). It also names the alternative for partial changes, leaving no ambiguity about when to choose this tool.

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 must carry the full burden of behavioral disclosure. It explains input constraints (e.g., currency required for fixed type) but does not mention expected side effects, potential errors (e.g., duplicate code), permission requirements, or idempotency. The warning about user agreement hints at sensitivity but does not describe what happens when the tool is called without consent. This is a significant gap for a mutation tool.

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

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

The description is two sentences, front-loading the purpose and then delivering critical parameter semantics and a usage condition. Every sentence earns its place; there is no fluff. The structure guides the agent from intent to constraints to prerequisite.

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 inputs and the key usage condition, but it omits mention of the 'enabled' parameter (default true) and does not address potential failure modes like code collisions. For a tool with 9 parameters and no output schema, it is adequate but not exhaustive. The absence of an output schema reduces the need to describe return values, yet the description could be more complete by noting that creation is immediate and irreversible.

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 description adds meaningful semantic detail beyond the schema, particularly for the 'type' parameter: it explains the value ranges for percentage, fixed, and free_shipping, and specifies when currency is required or omitted. It also lists optional limits (minSubtotal, maxUses, startsAt, endsAt), reinforcing their purpose. Since schema coverage is 78%, the description's extra guidance elevates it above the baseline.

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: 'Create a discount code.' It explains the three valid types with specific value constraints, which distinguishes it from other create_* tools. The verb and resource are precise, leaving no ambiguity about the operation.

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

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

The description provides a strong usage condition: 'Only call AFTER the user explicitly agreed to the code you described.' This tells the agent when it is appropriate to invoke the tool. However, it does not explicitly contrast with sibling tools like update_discount, set_discount_enabled, or list_discounts, though the name and context make the distinction 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does indicate a mutating create operation and a consent prerequisite, but it omits what the tool returns, permission/auth requirements, error behavior such as duplicate-slug conflicts, and potential side effects of settings like webhooks or notifications. For a write tool with no annotations, this is a significant gap.

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 short sentences with no filler. The main action and core inputs are front-loaded, optional complexity is summarized, and the consent guard is a compact final instruction. Every sentence adds value.

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

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

Given a complex nested schema and no output schema or annotations, the description should provide more operational context. It does not explain the return value, failure semantics, uniqueness constraints on slug, or side effects triggered by settings. The consent note and the deferred-fields hint help, but this is still incomplete for a mutation tool of this 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 high (80%), so the baseline is 3 and the description does not need to restate every parameter. It usefully marks name and slug as core and identifies fields/settings as optional, but it implies name and slug are required while the schema lists zero required parameters. It also does not clarify the top-level description parameter, which lacks a schema description.

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

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

The description opens with a specific verb and resource: 'Create a new form.' It then names the core inputs (name, slug) and the optional payload areas (field definitions and settings), making the tool's function unmistakable. This clearly differentiates create_form from sibling tools like list_forms, get_form, update_form, and delete_form.

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 clear context: the tool should only be called after the user explicitly agrees, and fields can be deferred to the Forms editor later, so a minimal name-and-slug call is acceptable. It stops short of explicitly naming alternative tools or stating when not to call this tool, but the usage context is still 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?

With no annotations provided, the description carries the full burden. It discloses that the order is manual/admin-entered and the item structure (recordId vs ad-hoc line), and adds the confirmation requirement. However, it does not mention side effects such as payment processing, email notifications, or that it creates a persistent record, though that is implicit from 'create'. Some behavioral context is missing.

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 with no filler. It front-loads the purpose, then provides item details, then the usage condition. 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?

Given the tool's complexity (array of items with multiple fields) and no output schema, the description covers the essential aspects: purpose, item structure, and when to call. The only notable omission is explanation of customer fields, but the schema marks them as optional, so it's acceptable. Overall, an agent can correctly invoke this tool based on the description.

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 only 33%, so the description must compensate. It adds value by explaining the two item types (references a product recordId or ad-hoc name+price), which clarifies the relationship between fields. But it does not explain customerId or customerEmail, which are undocumented in the schema, leaving a gap for those 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 clearly states a specific verb 'Create' and resource 'manual (admin-entered) order', distinguishing it from the many order-related siblings (list_orders, edit_order, etc.) by emphasizing the manual/admin nature. It also clarifies the two item types, making the tool's function 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?

It gives an explicit condition: 'Only call after the user confirms', which is a clear when-to-use guideline. It also implies the tool is for admin-entered orders, contrasting with customer-facing flows. However, it does not explicitly name alternative tools or state when not to use it, though the purpose is distinct enough from 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?

With no annotations, the description carries the transparency burden. It clearly states the tool creates a folder, returns it, and that the id can be used downstream, which is actionable. However, it omits failure modes, permission requirements, or idempotency specifics, leaving some behavioral gaps.

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. The action is front-loaded, the return value is mentioned briefly, and the precondition is the final sentence. Perfectly sized for the tool.

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

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

For a simple creation tool with no output schema, the description covers the purpose, return value, and a usage precondition. It integrates with sibling workflows. The only minor gap is not clarifying whether 'name' is effectively required, but the schema covers parameter details and the description provides sufficient operational context.

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

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

Schema description coverage is 100%, so both 'name' and 'parentId' are already well documented. The description's mention of the return value doesn't add new meaning to the parameters themselves, so it stays at the baseline score.

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

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

States a specific verb and resource ('Create a media folder') and explains its downstream role by mentioning that the returned id can be passed to upload_media or move_media. This clearly differentiates it from sibling tools like list_media_folders, update_media_folder, and delete_media_folder.

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

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

Provides an explicit precondition ('Only call after the user agreed to the folder you described') and hints at the typical workflow by naming upload_media and move_media as consumers of the folder id. It doesn't explicitly say when not to use it versus alternatives, but the context is clear.

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

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

With no annotations provided, the description carries the full disclosure burden and does disclose real behavioral traits: deliveryAccess defaults to 'none' (admin only) and must be set to 'public' for delivery API reads; creation requires explicit prior user consent; and uniqueFields semantics tie to import_records updates by key. It does not cover failure modes (duplicate slug/name) or response contents, but the essential persistent-write side effects are disclosed.

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

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

The purpose clause is front-loaded and the rest is dense but non-redundant: field-type rules, config options, defaults, and the safety gate each carry information. The main structural weakness is that the critical consent requirement is buried at the end of a long enumeration, where an agent skimming for mechanics could miss it.

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 12-parameter, deeply nested tool with no annotations and no output schema, the description covers the invocation-critical semantics: exotic field types, model-level options, the deliveryAccess default, and the approval gate. Gaps remain—it never states what the call returns, does not flag that name and fields are effectively required despite the schema listing zero required parameters, and omits conflict/error behavior—but the missing pieces are secondary to 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?

At 58% schema coverage, the description compensates for the gap by explaining non-obvious semantics the schema properties cannot: select/multiselect require `options`, relation fields need relationTo set to a target model slug plus relationType, object/list use nested fields/itemFields, and uniqueFields enables import_records to update by that key. It adds cross-parameter and cross-tool relationships, though name, color, and defaultSort gain no added meaning.

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

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

The opening clause 'Create a data model in the workspace' pairs a specific verb with a specific resource and scope. The phrase 'data model' cleanly separates this from sibling tools like create_record, create_page, and create_form, and from update_model/delete_model, so an agent knows what object this materializes 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 a hard, explicit precondition: 'Only call AFTER the user has explicitly agreed... Never create without that explicit go-ahead.' That is clear when/when-not invocation guidance. However, it never names alternatives or exclusion conditions relative to update_model (modify an existing model) or create_record (add records), so it stops 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?

No annotations are provided, so the description carries the full burden. It discloses that the page is created as a draft, that no content is included, and that explicit user agreement is required. It does not cover permissions or failure modes, but the primary side effect is plainly stated.

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

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

Two concise sentences with no filler. The core purpose comes first, optional parameters are summarized next, and the important user-consent constraint is placed last. 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?

Given no annotations and no output schema, the description gives enough for safe invocation: draft state, no content, optional fields, and a consent guard. It does not describe return values or default behavior, but these are minor for a straightforward create 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?

Schema coverage is high at 89%, and the description adds meaningful grouping: name and slug are presented as required in practice, and all optional parameter families are listed. Minor gap: the 'description' parameter is neither described in the schema nor mentioned in the tool description.

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 action and resource: creates a new draft page with name and slug, and explicitly notes content/blocks are added later. This clearly distinguishes it from sibling tools like list_pages, get_page, publish_page, and update_page_settings.

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 a clear condition for calling: 'Only call AFTER the user explicitly agreed.' Also implies this tool is not for content editing by saying content/blocks are added later. It does not explicitly name alternative tools, but the use 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?

With no annotations, the description carries the full burden. It discloses the creation effect and the relationship between the page type and its fields, plus a user-confirmation gate. It does not mention side effects, immutability constraints, or what happens after creation, but the core behavior is reasonably transparent.

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

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

Two short sentences, no filler, and the essential confirmation rule is placed at the end as a direct instruction. 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 schema is rich and mostly self-documenting, and the description covers the key prerequisite context. It is not fully exhaustive about edge cases or return behavior, but for a creation tool with this schema detail, it is reasonably complete.

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

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

Schema coverage is 71%, so most parameters are already documented. The description adds meaning by framing the 'fields' parameter as the custom-field schema carried by pages of this type, but it does not elaborate on the remaining schema-covered parameters. This is adequate without being especially additive.

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: creating a page type (template) with a custom-field schema. It also clarifies that pages of this type carry those custom fields, which distinguishes this creation tool from generic page-creation or page-type-read 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 provides one clear precondition: only call after the user confirms. However, it does not explicitly contrast this tool with alternatives like update_page_type, get_page_type, or delete_page_type, nor does it say in which situations creation is preferred.

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

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

No annotations are provided, so the description carries the full burden. It states the primary side effect (adding a record) and an important consent guardrail, but it does not disclose permissions, reversibility, response format, or error behavior. This is more than the bare minimum but still leaves gaps.

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 concise sentences with no filler. Each sentence contributes: what the tool does, how to pass inputs, and when it is safe to call it.

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 already documents both parameters and the translatable-field format in detail)SkipDate. The description completes the context with the user-consent precondition and clarifies that modelIdOrSlug and data are both needed. It does not mention return values or errors, but that is a minor gap for a create 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?

Schema description coverage is 100%, so the baseline is 3. The description rephrases the parameter roles and adds a helpful 'use get_model first if unsure' hint, but it does not significantly extend the schema's own parameter documentation.

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 action: 'Add a record (entry) to a data model.' This specific verb-resource pairing naturally distinguishes it from sibling tools like update_record, delete_record, and list_records.

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

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

The description gives explicit call conditions: use it only after the user has agreed, never create without that go-ahead, and consult get_model first if field keys are uncertain. It does not explicitly contrast with alternatives like update_record, but the create-only scenario is clear.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: 'Returns the endpoint AND its signing secret (shown only once)' is a critical disclosure — an agent must capture the secret on creation because it won't be shown again. The description also discloses the https endpoint constraint and the user-confirmation requirement. It does not cover auth permissions, idempotency, or duplicate-creation behavior, but for a create tool the one-time-secret warning is the most important trait and it is clearly stated.

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

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

Four short sentences, each carrying distinct load: the action, the URL constraint, the critical return-value behavior, and the call precondition. The description is front-loaded with the action sentence. The only minor cost is that the https constraint partially repeats the schema's url description, but for a security-critical constraint this redundancy 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 3-parameter tool with no output schema and no annotations, the description covers what an agent needs to call correctly: what it creates, the URL requirement, the shape of the return (endpoint + one-time secret), and the consent precondition. Remaining gaps are minor — the optional 'description' parameter is undocumented in both schema and description, and the events parameter's format is delegated to a sibling tool via the schema rather than the description.

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 67% (url and events are documented in the schema; description is not). The description adds little beyond the schema: 'public https endpoint' restates the url schema description, and 'one or more events' restates the minItems:1 constraint. It does not clarify the undocumented 'description' parameter, so it neither fully compensates for the coverage gap nor meaningfully extends the schema semantics. 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 opens with a specific verb+resource: 'Create a webhook endpoint subscribed to one or more events.' This clearly distinguishes it from siblings like update_webhook, delete_webhook, list_webhooks, and rotate_webhook_secret by naming the create action and the resource. The additional constraints (public https URL, one-time signing secret) sharpen the purpose further.

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 precondition — 'Only call after the user confirms' — which is genuine usage guidance. However, it does not name alternatives or exclusions, such as directing the agent to update_webhook for modifying an existing webhook or to list_webhook_event_types for valid event names (that pointer lives only in the schema, not the description). Usage context is implied rather than explicit.

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 the operation is permanent ('Permanently delete') and that it cascades to submissions ('and all its submissions'), which are key destructive behaviors. It does not mention authentication, rate limits, or other side effects, but for a simple delete operation, this is adequate.

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

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

The description is two sentences with no redundant wording. The first sentence conveys the core action and scope; the second adds a critical usage condition. Every word earns its place, and the critical caution 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 simple tool with one parameter, no output schema, and no annotations, the description covers all essential information: what is deleted, the permanence, the scope, and the required confirmation step. An agent can call this tool correctly with no additional context. No critical gaps are evident.

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 parameter 'idOrSlug' is documented with 'The form's id or slug to delete'. The description does not add any additional meaning beyond the schema, so it meets the baseline for fully covered parameters. It neither enhances nor detracts from the schema's explanation.

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'), the resource ('form'), and the scope ('and all its submissions'). It is unambiguous and clearly distinguishes from sibling tools like delete_form_submission, which targets a single submission. The purpose is immediately 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 description provides an explicit condition for when to call: 'Only call after the user explicitly confirms.' This is a clear usage guideline that addresses the critical prerequisite. However, it does not explicitly mention when NOT to use it or point to alternative tools, but the clarity of purpose largely compensates for that.

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 explicitly states the operation is permanent (irreversible) and requires explicit user confirmation, which are the most critical behavioral facts for a destructive action. It does not mention permissions or side effects, but it covers the core risks.

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 action is stated first, followed by the crucial confirmation warning. Every word earns its place, and the most important information 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 single-parameter destructive tool with no output schema and no annotations, the description conveys the essential action, permanence, and precondition. It could mention error behavior or idempotency, but the description is sufficient 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?

The schema already fully describes the only parameter (submissionId: 'The submission's id to delete'), and schema coverage is 100%. The tool description adds no extra parameter-level meaning, so the baseline of 3 applies.

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

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

The description states a specific verb ('delete') and resource ('form submission') with the qualifier 'permanently', clearly distinguishing it from sibling delete tools like delete_form, delete_model, and delete_webhook. It 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 gives an explicit usage condition: 'Only call after the user explicitly confirms.' This tells the agent when it is appropriate to invoke the tool. It does not name alternatives, but the tool name and resource specificity make the intended scope clear among the many delete_* 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?

With no annotations provided, the description carries the full burden of disclosing destructive behavior. It explains the empty-folder default, the deleteContents escalation, the force override protecting assets in use, and the requirement for explicit user confirmation. This is strong transparency for a destructive 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 tightly written sentences state the core behavior, the option flags, and the key safety condition. No filler or redundant phrasing; the critical confirmation condition comes last for emphasis.

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 destructive tool with no annotations and no output schema, the description covers default behavior, escalation flags, the protection refusal, and the user-confirmation prerequisite. An agent has enough context to decide when and how to invoke 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%, so the baseline is 3. The description paraphrases the schema's parameter meanings but does not add substantive detail beyond what the input schema already provides.

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

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

The description has a specific verb ('Delete') and resource ('media folder'), and immediately clarifies the default behavior (only empty folders removed). This distinguishes it from sibling tools like delete_model and delete_webhook without needing to inspect 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 gives a clear, explicit condition: 'Only call after the user explicitly confirmed the deletion.' It also explains when deleteContents and force apply. It does not name alternatives, but the conditional usage is strong and actionable.

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

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

With no annotations provided, the description fully discloses the critical behavioral aspects: it cascades to delete all records and causes permanent deletion. It also explicitly states the requirement for user confirmation. This is a strong disclosure of side effects and safety requirements, exceeding what is typically expected.

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 followed by a warning. The warning is front-loaded, making the destructive nature immediately apparent. Every word earns its place; there is no unnecessary fluff or repetition.

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

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

For a simple delete operation with one parameter and no output schema, the description covers all essential context: the action, the cascading effect, the permanence, and the need for user confirmation. An agent has enough information to invoke the tool safely and appropriately.

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 describes the only parameter (idOrSlug) with 'The model's id or slug to delete.' Since schema description coverage is 100%, the description adds no additional meaning beyond what the schema provides. The baseline of 3 applies because the schema carries the full documentation burden.

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

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

The description clearly states the action: 'Delete a data model.' This is a specific verb plus resource, and it distinguishes itself from sibling tools like delete_record and delete_page by naming the resource type. It is not a tautology and provides immediate understanding of 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 provides clear context for when the tool should be used: only after explicit user confirmation. It warns about the cascading destructive effect, which implies it should not be used casually. However, it does not explicitly mention alternatives or when not to use it, such as when only a record should be deleted instead of the whole model.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly communicates that the action is destructive and irreversible ('Permanently delete'), cascading ('all its descendants'), and gated on user confirmation. It could additionally mention permission requirements or effects on related content, but the core safety-critical behavior is well disclosed.

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

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

The description is three short sentences with no filler. The primary action is front-loaded, followed by essential scope and safety constraints. Every sentence adds necessary information for correct and safe invocation.

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

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

For a one-parameter destructive tool with no output schema, the description covers the essential invocation constraints: permanence, descendant scope, homepage restriction, and mandatory user confirmation. It does not describe error cases or return values, but those are less critical given the simplicity of the operation and the safety emphasis already present.

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

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

Schema description coverage is 100%, and the single parameter 'pageId' is already described as 'Page id to delete.' The tool description adds no further meaning about the parameter, such as format, requiredness, or valid page types. Baseline 3 is appropriate since the schema carries the parameter documentation.

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 ('Permanently delete'), a clear resource ('a page'), and an important scope boundary ('all its descendants'). It also differentiates itself from sibling deletion tools like delete_model, delete_record, and delete_page_type by focusing on the page resource and adding the homepage restriction.

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

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

The description gives an explicit when-to-use condition: 'Only call after the user explicitly confirms.' It also provides a clear when-not-to-use constraint: 'Cannot delete the homepage.' This is strong practical guidance for an agent deciding whether invocation is 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 provided, the description carries the full burden of behavioral disclosure. It does well by revealing that the operation will be refused for system types and in-use types, and by requiring explicit user confirmation. This provides important safety context beyond the schema, though it does not mention permission requirements or describe the response/error format.

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

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

The description is two sentences with no filler. The core action is stated first, followed by necessary constraints and a confirmation requirement. Every sentence adds operational value.

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

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

For a simple one-parameter destructive operation with no output schema, the description covers the critical context: refusal conditions, prerequisite page cleanup, and user confirmation. It could be slightly more complete by noting auth requirements or the absence of a return value, but as written it gives an agent enough to invoke the tool correctly and 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%: the only parameter, pageTypeId, already has a clear description ('Page type id to delete'). The tool description does not add extra parameter-level meaning, but it does not need to because the schema fully covers 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 uses a specific verb-resource pair ('Delete a page type') and clearly distinguishes this from sibling tools like delete_page, delete_form, and delete_model. The resource is unambiguous and the 'page type' namespace is clarified by sibling names such as list_page_types and update_page_type.

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 call the tool ('Only call after the user explicitly confirms') and explains exclusions: system types and types currently used by pages. It also tells the user to move or delete pages first. It does not name an alternative tool explicitly, but the conditions are clear enough for an agent to decide when deletion is 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?

No annotations are provided, so the description carries the disclosure burden. It discloses permanence, refusal for referenced records, the need for user confirmation, and the consequence of force: true (references may go stale). This goes beyond the schema's parameter descriptions.

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, front-loaded with the core action, then required confirmation and edge-case behavior. Every sentence earns its place with no redundant words.

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

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

For a two-parameter mutation tool with no output schema or annotations, the description covers the destructive nature, the refusal case, and the force retry workflow. Nothing an agent needs to invoke safely or correctly is missing.

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

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

Both parameters have full schema descriptions, setting a baseline of 3. The description adds operational nuance for force (retry only after user confirms stale references) and confirms recordId is the deletion key.

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 ('permanently delete'), resource ('one record (entry)'), and key parameter ('by its id'). Distinguishes clearly from sibling delete_model/delete_page and get_record by making the destructive scope explicit.

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

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

Gives explicit when-to-call instructions: only after explicit user confirmation, and only with force: true after the user confirms the reference may go stale. Does not name alternative tools, but the call conditions are unambiguous.

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

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

With no annotations, the description carries the behavioral burden. It clearly discloses that deletion is permanent and irreversible, and that it requires explicit user confirmation before calling. It could add auth requirements or downstream effects, but the core destructive behavior is transparent.

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

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

Two short sentences, each earning its place: the first states the action and irreversibility, the second states the critical precondition. 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 is adequate for a simple destructive one-parameter tool, covering action and confirmation, but it leaves the id parameter's meaning and requiredness to inference. With no annotations or output schema, this is a noticeable gap, though not a fatal one.

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 only has an undocumented 'id' string with 0% description coverage, and the tool description never explains that id is the webhook endpoint identifier or that it is required. The word 'webhook endpoint' gives a weak inference, but the description does not compensate for the missing schema documentation.

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 ('Delete'), names the resource ('webhook endpoint'), and adds 'permanently,' which clearly differentiates it from sibling mutation tools like update_webhook and rotate_webhook_secret. There is no ambiguity about what action the tool performs.

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 constrains when the tool should be invoked: 'Only call after the user explicitly confirms.' This is clear usage context, although it does not mention alternatives such as listing webhooks or rotating a secret, so it stops 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?

With no annotations, the description carries the full burden. It discloses that it fully replaces the items array (destructive), recomputes totals, and is gated on user confirmation, implying irreversibility. It does not mention permissions or other side effects, but covers the key behavioral traits.

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 primary action is front-loaded, and the usage condition is a concise second sentence. 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?

The description covers the core behavior (full replace, totals recalculation) and the confirmation gate, but lacks details on prerequisites (e.g., order existence), potential side effects on discounts or status, or return values (no output schema). Given it is a mutation with no annotations, more context could be provided, but the schema does specify item structure and minItems.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'items' is the new line items array and that totals will be recalculated, but it does not explicitly describe 'orderId' or the exact structure of items beyond the schema's own per-property descriptions. Some meaning is added, but not fully compensates for the coverage gap.

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

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

The description clearly states the action: 'Replace an order's line items (full replace of the items array)' with a specific resource (order) and behavior (full replacement). It distinguishes itself from sibling tools like update_order_details by emphasizing the full replace semantics and total recalculation.

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 a clear usage condition: 'Only call after the user confirms.' This sets expectations for when it is appropriate to invoke. However, it does not explicitly mention alternatives or when not to use it, which slightly reduces the score.

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 burden. It says 'Get' which implies a read-only operation, but it does not explicitly state that it does not modify data or mention any permissions, rate limits, or side effects. It lists the returned fields, which is useful, but it does not disclose any behavioral constraints beyond that. For a simple read, a 3 is appropriate.

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

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

A single, front-loaded sentence with zero wasted words. It states the action, the resource, the details returned, and the lookup method, all in one concise line.

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 simplicity (one parameter, no output schema, no annotations), the description adequately explains what the tool returns (type, value, usage limits, validity window). It does not mention error cases or response format, but for a basic get-by-id tool, the information is sufficient. The note that the id/code comes from list_discounts in the schema adds context, though the description itself could mention that the identifier is required (since schema marks it as not required).

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 coverage is 100% and already documents the parameter as 'id or code (from list_discounts)'. The description repeats 'by id or code' but does not add new semantic meaning beyond the schema. The description does clarify that it returns full details, but that relates to output, not the parameter. Baseline 3 is appropriate because the schema handles parameter documentation.

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 ('Get'), names the resource ('one discount's full details'), and enumerates the exact fields returned (type, value, usage limits, validity window). It clearly distinguishes from sibling tools like list_discounts (which lists) and update_discount (which modifies) without ambiguity.

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 clearly implies this tool is for retrieving a single discount's details, which differentiates it from list_discounts and mutation tools. However, it does not explicitly say when NOT to use it or mention alternatives, though the schema parameter hint ('from list_discounts') reinforces usage for individual lookup. It is adequate but lacks explicit exclusions.

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

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

No annotations are provided, so the description must carry the behavior burden. It conveys a read operation and lists the return contents, but it does not mention error behavior, permissions, or side-effect guarantees beyond the 'Get' verb.

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 front-loaded sentence with no filler. Each element—'full details', the parenthetical content, and 'by id or slug'—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 one-parameter read tool with no output schema, the description supplies the retrieval target and the returned content categories, while the schema supplies the parameter source. It omits only secondary context like auth or error details, which are not required to call it correctly.

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

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

Schema coverage is 100%: the one parameter idOrSlug already has a description mentioning id/slug and list_forms. The description's 'by id or slug' duplicates that information without adding format constraints or additional semantic detail.

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 ('Get'), names the resource ('one form'), and enumerates the payload ('fields, settings, submission count'). It also specifies the lookup method ('by id or slug'), which clearly distinguishes it from list_forms and get_form_submission.

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 exclusionary guidance naming alternatives. The phrasing 'one form's full details' implies the use case of retrieving a single form rather than listing forms or fetching submissions, but does not state it directly.

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 disclose behavior. It only states that it gets full details, implying a read operation, but it doesn't explicitly confirm read-only behavior, nor does it mention prerequisites, rate limits, or what happens if the submissionId is invalid. For a fetch operation, this is thin on behavioral context.

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 sentence with zero redundancy. It front-loads the action and object, and the 'by its id' qualifier at the end is essential. No wasted words.

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 get-by-id operation with one parameter, no output schema, and no annotations, the description is largely sufficient. It tells the agent exactly what it does. Some might argue it could mention response format or error cases, but for this level of simplicity, it's adequate.

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 has 100% coverage with its own description ('The submission's id'). The description adds no additional meaning beyond the schema, merely restating that it uses an id. Since schema coverage is high, 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 verb (Get), the resource (form submission), and the scope (one specific submission by its id). It also distinguishes from list_form_submissions, which returns multiple submissions, and get_form, which returns the form definition. No ambiguity.

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

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

The purpose is clear: use this when you have a submissionId and need the full details of that specific submission. It implicitly differentiates from sibling tools like list_form_submissions, but it doesn't explicitly state when not to use it or mention alternatives. Still, the context is clear enough for an agent to route correctly.

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

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

With no annotations, the description carries the burden of disclosing behavior. It clearly details the content returned, implying a read-only operation via the verb 'Get', but it does not explicitly mention error behavior, absence of side effects, authentication requirements, or rate limits. This is adequate but not rich.

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

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

Two compact sentences: the first front-loads the action and precise payload contents, the second gives a direct usage directive. Every sentence earns its place, and there is no redundancy.

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

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

For a simple read operation with a single parameter, the description is largely complete: it explains what will be returned, how the model is identified, and when to invoke the tool. Minor gaps such as explicit error behavior and the response envelope are not critical for this get tool, so it is nearly 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%, with the parameter 'idOrSlug' already documented as 'The model's id or slug (from list_models)'. The description's 'by id or slug' simply reflects the schema and adds no new semantics about format, examples, or required status, so the 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 ('Get') and resource ('one data model'), and enumerates the exact contents returned: field definitions and the product capability config. It clearly distinguishes this tool from siblings like list_models (which lists models) by focusing on a single model's full details.

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 'Use before update_model and when the user asks about a model's structure,' providing a concrete trigger condition and naming an alternative tool. It does not explicitly state 'when not to use' or mention list_models as the alternative for listing, but the singular 'one data model' makes the boundary reasonably clear.

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

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

With no annotations, the description carries the disclosure burden. The verb 'Get' signals a non-mutating read and the description clearly states what is returned, but it does not mention auth requirements, behavior for invalid or missing ids, or explicit side-effect guarantees.

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 with the main action front-loaded, followed by a compact comma-separated list of returned fields. It is slightly long but every clause adds specific 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 read-by-id tool with one documented parameter and no output schema, the description gives a thorough inventory of return content and identifies the source of the id. It lacks a pointer to get_order_pipeline for pipeline-specific details, but the core information needed to call it correctly is present.

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

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

Schema description coverage is 100%, and the single parameter is already documented as the order id from list_orders with minLength 1. The tool description adds only 'by its id,' which does not materially extend the schema's parameter documentation.

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 leads with a specific verb and resource ('Get one order's full details by its id') and enumerates the exact fields returned, including items, money column, discount code, PO number, address, and statuses. It is clearly distinct from list_orders, though it does not explicitly differentiate itself from the sibling get_order_pipeline.

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 alternative-routing guidance. The parameter description 'The order's id (from list_orders)' implies this tool is used after listing orders, which provides minimal context, but no exclusions or comparison to the related get_order_pipeline sibling are given.

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

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

No annotations are provided, so the description carries the full burden. The verb 'Get' implies a read-only operation, but the description does not explicitly state that it has no side effects, requires no special permissions, or does not modify any data. For a simple getter with no parameters, this is acceptable but minimal.

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

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

The description is a single, front-loaded sentence that says exactly what the tool does and clarifies the meaning of the pipeline. It contains no fluff or redundant information, and every phrase 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 getter with no parameters and no output schema, the description adequately explains the tool's purpose by defining the pipeline. It could be slightly more descriptive about the return format (e.g., whether it returns a list of stages with names and order), but given the simplicity and the clear naming, it is sufficient for an agent 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?

The tool has zero parameters, and the schema coverage is 100% (trivially). The description does not need to add parameter information. According to the baseline for 0-parameter tools, a score of 4 is appropriate since there is nothing to explain beyond what the schema already communicates.

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 exactly what the tool does: it gets the workspace order pipeline, and clarifies that this is the configurable stages orders move through. This distinguishes it clearly from sibling tools like get_order (which returns a single order) and list_orders (which lists orders), and aligns with set_order_pipeline_stage which modifies the pipeline.

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 that this tool retrieves the pipeline configuration, which is implicitly when you need to inspect or understand order stages. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough that an agent can infer its usage without confusion.

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

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

No annotations are provided, so the description carries the behavioral burden. It clearly describes the returned data scope and the idOrSlug lookup, and 'Get' implies a read-only operation. It does not mention error behavior, permissions, or the draft/devDraft nuance itself, but the input schema covers the target behavior and the description still gives a solid behavioral contract.

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

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

The description is two sentences with no filler. The return contract is front-loaded and the usage guidance is cleanly separated in the second sentence. The parenthetical list of returned fields is long but each item earns its place.

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

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

With no output schema, the description's enumeration of returned fields is the main return contract, and it is sufficiently detailed. The schema supplies the target and idOrSlug details. It would be slightly better if the description itself noted that the default result is the shared draft, but the enum description already handles 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?

The input schema already fully documents both parameters, including the target enum's default and devDraft behavior and where idOrSlug comes from. The description only adds 'id or slug', which is already in the schema, so it does not meaningfully extend parameter understanding. Baseline 3 applies due to 100% schema description 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 opens with a specific verb and resource: 'Get one page's full details', then enumerates exactly what is returned (blocks, layout, page type, custom fields, SEO fields per language). It also names the lookup mechanism (id or slug), which clearly distinguishes it from listing or page-type-related sibling tools.

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

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

The description explicitly says to use it 'when the user asks about a specific page's content, structure or SEO', giving a clear trigger condition. It does not name alternatives or explicit when-not-to-use cases, but the stated usage scope is enough to route an agent to this tool correctly.

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

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

No annotations are provided, so the description must carry the behavioral disclosure burden. It describes what data is returned (custom-field schema) and mentions relation fields, but does not state whether the operation is read-only (though 'get' implies it), what happens on invalid IDs, or any error behavior. This is a moderate gap given no annotation support.

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, both information-dense. The purpose is front-loaded, and the usage guidance is concise and actionable. No wasted words.

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 get-by-id tool, the description covers the return content in detail and gives usage context. It lacks an explicit statement about output format or error handling, but the absence of an output schema makes the description's detail adequate. Since there are no annotations, a slightly richer description would be ideal, but it remains largely 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?

The schema already documents the parameter with a description ('Page type id (from list_page_types)') and 100% coverage, so the baseline is 3. The tool description adds no extra parameter-specific semantics beyond the usage context, so it neither improves nor harms the understanding.

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 retrieves a single page type with its full custom-field schema, specifying exactly what fields are included (keys, types, options, relation fields). It also explicitly contrasts with list_page_types, making it distinct.

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 instructs to use this tool before writing customFields on a page, because list_page_types does not return the fields. Also references list_page_types as the source for the pageTypeId, providing clear routing.

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

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

With no annotations, the description carries the burden. It adds useful detail about what is returned ('all its field values and status') but does not cover error behavior (e.g., missing record), permissions, or confirm it is read-only. The 'Get' verb implies non-mutating 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?

A single efficient sentence that states the action, scope, and returned content. 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?

For a simple single-parameter read tool, the description plus schema are nearly sufficient. Missing error/not-found behavior is minor, and no output schema exists, but the description adequately conveys the retrieval scope and result.

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 parameter description already explains recordId comes from list_records. The main description adds 'by its id' but no additional meaning beyond the schema, 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 ('Get'), a specific resource ('one record of a data model'), and the retrieval key ('by its id'). This clearly distinguishes it from list_records (plural) and other get_* siblings.

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

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

The description implies usage for fetching a single record when an ID is known, and the schema parameter description says the ID comes from list_records. However, it does not explicitly contrast it with list_records or mention when not to use 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?

With no annotations, the description carries the burden of conveying behavior. The verb 'Get' implies a read-only, non-destructive operation and the listed fields indicate what will be returned, but it does not explicitly state that nothing is modified, whether special permissions are required, or how failures surface. This is adequate for a simple getter but leaves the behavioral contract implicit.

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

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

One tightly scoped sentence front-loads the operation and resource, then uses a colon to enumerate the returned settings efficiently. Every phrase contributes value; there is no repetition 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?

For a zero-parameter getter with no output schema, the description does a good job of explaining what the return value will contain. It is less complete in that it does not flag the relationship to get_workspace_info or any response-shape caveats, but nothing about invocation is left unclear.

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 input schema fully documents that with empty properties. The description therefore has no parameter meanings to add; the baseline for a zero-parameter tool is solid.

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 specifies the resource ('site configuration') and enumerates its contents: languages, site name, enabled features, and cart/commerce settings. It is unambiguous about the operation (Get), but it never mentions sibling get_workspace_info, so differentiation from that overlap is left to the name and item list rather than explicit routing.

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 guidance about when to call this tool versus alternatives such as get_workspace_info, nor any statement about prerequisites or context. The only implied usage is 'when you need site configuration,' which is essentially a restatement of the purpose.

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. 'Get' implies a read-only operation, and listing the return fields (name, slug, plan, limits) makes the behavioral outcome concrete. It doesn't mention auth requirements or error behavior, but for a parameterless info getter this is a minor gap, not a serious one.

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

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

A single, front-loaded sentence states the action, target, and return contents with no filler or redundancy. Every phrase earns its place.

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

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

For a zero-parameter read-only info tool with no output schema, the description fully covers what an agent needs: what the tool does and what data it will receive in response. Nothing essential 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?

The tool has zero parameters and the schema is empty, so the baseline is 4. The description accurately reinforces the no-input nature by stating what information is retrieved without referencing any arguments.

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 ('Get') and identifies a precise resource ('current workspace's info'), then enumerates the exact fields returned: name, slug, plan, and limits. This distinguishes it clearly from all sibling tools, none of which target workspace metadata.

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

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

The phrase 'current workspace's info' establishes the clear context: use this when you need workspace identity, subscription plan, or quota/limit details. It doesn't explicitly exclude alternatives or state when-not-to-use, but there are no closely related workspace-info siblings to route around, so the guidance is adequate.

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

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

With no annotations provided, the description carries the full burden, and it does so thoroughly. It discloses the create/update side effects, upsert merge semantics, rejection of workspace-disabled languages, and the exact return payload including importedCount, updatedCount, per-row errors, and per-row statuses. This is rich behavioral disclosure beyond any structured 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 dense but every sentence earns its place: one sentence for the core operation and limit, one for upsert semantics, one for translatable-field handling and return values. The most important information is front-loaded, and the content is organized logically from behavior to output.

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 bulk mutation tool with no output schema, the description is complete: it covers input limits, create vs update behavior, duplicate avoidance, field-level language requirements, and the full return structure. An agent has enough information to invoke the tool and interpret its results 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%, and the schema descriptions already explain rows, upsertKey, and modelIdOrSlug in detail, including the language map example and merge behavior. The tool description reinforces these points and adds return-value context, but does not substantially go beyond what the schema already provides. 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 opens with a specific verb and resource: 'Bulk-import records into a data model'. It also specifies the 1000-row limit and distinguishes the tool's bulk upsert behavior from single-record siblings like create_record and update_record. This makes the tool's purpose unambiguous and differentiates it from related operations.

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

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

The description clearly explains when to use upsertKey versus not, and the repeated-sync scenario that motivates bulk import. It does not explicitly name alternative tools such as create_record or update_record, but the bulk vs single-record distinction is strongly implied. This is clear usage guidance with only a minor gap in explicit exclusions.

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

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

With no annotations, the description carries the burden of behavioral disclosure. It discloses the content structure (language-keyed, relation fields) and the significance of layoutRegions, which is essential for interpreting results. It does not explicitly state the operation is read-only, but that is implied by 'list' and no side effects are mentioned. The description is informative but could have explicitly noted read-only status.

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 dense with purpose. The first sentence states the core function, the second explains how to use the output with related operations, and the third clarifies the layout block distinction. Every sentence earns its place, and the most important information (purpose) is front-loaded.

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

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

Since there is no output schema, the description must explain what the tool returns. It details that each block type includes a content field schema, default values, and the meaning of layoutRegions. It also explains how content is structured (language-keyed, relation fields), giving an agent everything needed to use the output correctly. For a zero-parameter list tool, this is 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?

The input schema has zero parameters, so there is nothing to document. Per the rubric, the baseline for 0 params is 4. The description does not add parameter information because none exists, which 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 'List' and the resource 'block types available on the workspace's site', and specifies the output includes content field schema and default values. This distinguishes it from sibling tools like list_page_types or list_media, and it even names the exact operations (add_block_to_page, update_block_content, patch_block_content) that consume its output.

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 instructs when to use the tool's output: 'Use a block type's schema to shape content for add_block_to_page / update_block_content / patch_block_content'. It also contrasts layout blocks managed via update_page_layout with page body blocks, providing clear routing between alternatives. This is explicit guidance on when and how to use the tool.

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

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

With no annotations provided, the description carries full behavioral disclosure. It explains the output semantics (per-surface counts, pages, `registered`, `orphanTypes`, `unusedTypes`) and clarifies how `includeHistory` extends counting to page version history including deleted pages. It does not mention permissions, performance, or lack of side effects, but for a read/list operation this is reasonably transparent.

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

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

The description is dense and packs multiple lists and definitions into the first sentence, but every clause contributes meaning and the usage guidance follows immediately. The structure could be slightly clearer with more separation between output semantics and usage advice, but it remains focused and free of 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?

Given the tool's complexity, no annotations, and no output schema, the description does a strong job of covering what the tool returnseb each surface, counts, affected pages, and the meaning of `registered`/`orphanTypes`/`unusedTypes`. It also gives the migration workflow context. Minor gaps remain around response shape or potential pagination, but the essential information for correct invocation is present.

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

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

Schema description coverage is 100%, so both parameters are already described in the schema. The tool description mostly restates what the schema says about `types` and `includeHistory`, adding only minor context such as 'including versions of deleted pages' for `includeHistory`. This meets the baseline but does not substantially go 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 opens with a specific verb and resource ('Show where each block type is stored across the workspace') and enumerates the exact surfaces tracked, including draft/published page blocks, layout regions, and developer drafts. It also defines the key output concepts (`registered`, `orphanTypes`, `unusedTypes`), making it clearly distinct from sibling tools like `list_block_types`.

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: 'Use it before renaming or removing a block type in code,' and even names follow-up tools (`update_block_content` / `remove_block_from_page`). It does not explicitly state when not to use it or contrast it with an alternative like `list_block_types`, so it falls short of a full 5.

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

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

No annotations are provided, so the description carries the full burden. It adds useful behavioral context: 'admin view' hints at permission requirements, 'pagination' and 'optional status filter' describe request controls, and 'totalValue is in minor units' clarifies a response field. However, it doesn't explicitly state that this is a read-only operation, nor does it describe error handling, rate limits, or response structure beyond that single field.

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 that front-loads the purpose ('List shopping carts') and packs in essential details (admin view, status filter, pagination, totalValue units). Every word adds value with no redundancy.

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

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

For a simple list tool with three optional parameters and no output schema, the description covers the core aspects: what it does, who can use it, filtering, pagination, and a key field unit. However, it lacks any detail about the response format (e.g., array of carts, fields included) and doesn't mention authentication beyond 'admin view'. Given the absence of an output schema, this is a noticeable gap.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'optional status filter' and 'pagination' which map to the status, skip, and limit parameters, but it doesn't explain the semantics of skip/limit (e.g., defaults, range) or the meaning of the status enum values. The description gives only a high-level hint, leaving agents to infer specifics from 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 'List shopping carts (admin view)' with a specific verb and resource. It distinguishes from sibling tools like list_orders by explicitly naming the resource (carts) and adds scope (admin view), so an agent can tell it apart without ambiguity.

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 by noting 'admin view' and mentions optional status filter and pagination, which implies usage for listing carts with filtering. However, it doesn't explicitly state when to use this tool over alternatives (e.g., no mention of when to use list_orders instead) or any exclusions. The context is sufficient for a simple list 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?

With no annotations, the description carries the transparency burden. It discloses the list semantics, available filters, and pagination. It does not mention permissions, rate limits, response shape, or ordering, but for a straightforward list operation these omissions are not critical.

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 concise, front-loaded statement that avoids redundancy. It names the resource, workspace scope, filters, and pagination in a compact form, though 'code search' could be slightly clearer.

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 five optional parameters and no output schema or annotations. The description covers filters and pagination but omits what fields are returned, default limit/offset semantics, and any ordering or visibility caveats, leaving some operational ambiguity for an 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 only 20% (only search is documented), so the description must compensate. It groups parameters semantically ('enabled, type, or a code search; paginated'), which helps, but it does not flesh out limit/offset behavior or the type enum beyond what the schema already provides.

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

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

The description names a specific verb ('List') and resource ('discount codes') and scopes it to the workspace. This clearly distinguishes it from singular retrieval tools like get_discount and mutation tools like create_discount or update_discount.

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 conveys a clear read/query use case: list workspace discounts with optional filtering and pagination. However, it never explicitly routes the agent to get_discount for a single discount or states when listing would be inappropriate, so the guidance is implied rather than explicit.

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?

There are no annotations, so the description must carry the behavioral disclosure burden. It does disclose two key behaviors: status filtering and pagination. However, it does not explain defaults, ordering, whether all forms are returned regardless of user permissions, what the response shape is, or how pagination results should be traversed.

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 front-loaded with the core purpose. Both sentences earn their place, though the second sentence is telegraphic. It is concise without being wasteful, but could use slightly more explanatory structure.

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 list operation with three optional parameters and no nested objects, the description is minimally adequate. It covers scope, filtering, and pagination, but lacks details about pagination defaults, ordering, and what the returned list contains. Without an output schema, a bit more context about the response 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?

The schema description coverage is 0%, but the description partially compensates by indicating that status is used for filtering and that skip/limit relate to pagination. It does not elaborate on the semantics of skip, limit, or what happens when status is omitted, but the parameter names and enum values are reasonably self-explanatory.

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

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

The description clearly states a specific verb and resource: 'List the forms in the workspace.' It also distinguishes this from siblings like get_form (single form) and list_form_submissions (submissions, not forms) by explicitly scoping to forms and mentioning status filtering and pagination.

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 given about when to use this tool versus related alternatives, such as get_form, list_form_submissions, or create_form. There are no exclusions, prerequisites, or conditions stated. The usage context is only 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?

With no annotations, the description carries the behavioral disclosure burden. It discloses that the operation is paginated and returns submission rows with data and status, which is useful. However, it does not address permissions, ordering, pagination mechanics, or any side-effect guarantees beyond the implied read-only nature of 'List'.

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

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

The description is two sentences with no filler. The primary action and key modifiers (filtered, paginated, returns rows) are front-loaded, and every phrase adds value.

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

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

Given four optional parameters, no annotations, and no output schema, the description gives enough to select and invoke the tool: it names the filters, pagination, and return content. It could be more explicit about the response shape or pagination parameters, but it is adequate for a straightforward 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?

Schema coverage is 50%: status and formIdOrSlug have descriptions, while skip and limit do not. The description mentions 'filtered by form and status; paginated,' partially compensating for the undocumented parameters, but it does not explain skip/limit semantics beyond the word 'paginated.'

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

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

The description clearly states a specific verb and resource ('List form submissions') and adds filtering and pagination context. It is distinguishable from the singular get_form_submission by its plural scope and 'rows' return language, though it does not explicitly name any sibling tool.

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

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

The description implies when to use it—when listing submissions with optional form/status filters—but gives no explicit guidance about when not to use it or which alternative might be more appropriate. There is no mention of get_form_submission or other related 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?

With no annotations, the description must carry the behavioral disclosure burden. It does state the operation is a listing (read-only) and that results are paginated, and it scopes to the workspace. However, it does not mention return format, ordering, side effects, or any restrictions. It is adequate but not rich.

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 core action and resource, with no redundant words. It is appropriately concise for a simple list operation.

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 list tool, the description covers the basics but omits details that would help an agent fully understand behavior: what fields are returned, whether there is an ordering, and how pagination bounds work. There is no output schema to compensate. It is minimally viable but leaves 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 0%, so the description must compensate. It only hints at pagination via the word 'paginated' but does not explain the limit and offset parameters, their relationship, or expected values. The parameter names are somewhat self-explanatory, but the description adds minimal semantic value 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 uses a specific verb ('List') and a clear resource ('media files (images and files)') with workspace scope, and distinguishes itself from sibling tools like upload_media, move_media, and list_media_folders. Even without naming siblings, the resource and action are 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?

No guidance is given about when to use this tool versus alternatives. With siblings like list_media_folders and upload_media in the same workspace-media domain, the description does not help an agent decide between them. The context is implicit, not explicit.

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 present, the description carries the burden of signaling behavior. The word 'List' implies a read-only operation, and the parent folder scoping is disclosed. However, it does not mention whether results are paginated, sorted, or only include direct children when parentId is provided, and no output schema exists to fill that gap.

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 front-loaded. The first sentence states the action and scope, and the second sentence provides the practical use case. Every word contributes value with no redundancy.

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

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

For a simple listing tool with one optional parameter and no output schema, this description is nearly complete. It explains the main use case and the key scoping option. A brief note on return shape or pagination would improve completeness, but an agent can likely invoke this tool correctly without it.

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

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

The schema already covers the single parameter fully, including the meaning of parentId and the instruction to omit it for top-level folders. The description essentially restates this same information, so it adds no meaning beyond the schema; the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'List media folders in the workspace.' It also clarifies the optional scope ('under a parent folder') and distinguishes the tool's purpose by connecting it to discovering a folderId before uploads or moves. This clearly separates it from sibling tools like list_media or create_media_folder.

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 clear context for when to use the tool ('to discover a folderId before uploading or moving assets') and explains the optional parentId behavior. It does not explicitly name alternatives or state when not to use it, but the intended workflow is evident from the text.

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

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

No annotations are provided, so the description carries the full burden. It explicitly discloses that the operation is read-only, that results are paginated, and that statuses include active, suspended, and pending invitations. It does not mention ordering or response metadata, but the core behavioral profile is transparent.

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

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

One tight sentence that front-loads the core purpose, then adds read-only safety, filter options, and pagination. Every clause earns its place and there is no redundancy.

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

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

For a simple list tool with no output schema, the description covers the essential context: what is listed, what fields are returned, filtering, pagination, and read-only safety. It could be more complete by describing response shape or ordering, but nothing critical is missing for basic invocation.

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

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

Schema coverage is 50%: search and status have descriptions, while skip and limit are undocumented. The description adds a conceptual link between 'search string' and the search parameter and mentions pagination, but it does not explain skip/limit semantics in any operational detail beyond that.

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 ('List') with a clear resource ('the people in this workspace') and specifies what is returned ('role and status'). It also names the three statuses, making the tool's scope unambiguous and distinguishable from sibling tools like list_roles or list_forms.

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

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

The description clearly implies when to use this tool: when you need the people in a workspace along with their roles and statuses. It states filtering and pagination options but does not explicitly name alternatives or exclude cases, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden. It clearly implies a read-only operation via 'List' and scopes it to the current workspace, but it does not disclose return format, pagination, or whether full model definitions are returned. It is adequate but not richly transparent.

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

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

Two sentences, front-loaded with the core action and immediately followed by concrete use cases. Every clause adds value and there is no redundancy.

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

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

For a parameterless list tool, the description covers what is returned (data models in the workspace) and why to use it. It is slightly light on return-value detail, but the low complexity makes the omission acceptable.

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, so the schema is already fully descriptive. There is nothing for the description to add about parameters. Baseline 4 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 states a clear verb ('List') and resource ('data models (content types)') and specifies the workspace scope. It also gives concrete example questions the tool answers, making it easy to distinguish from siblings like list_records or list_pages without checking schemas.

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

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

The description explicitly frames when to use the tool: to answer whether models exist or to inspect existing data structures. It does not mention exclusions or name alternatives, but the use-case guidance is clear and actionable.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the call is paginated and filterable, and 'list' implies a read operation. However, it does not describe sort order, result shape, whether filters are combined with AND/OR, or any authentication/rate-limit 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?

The description is a single front-loaded sentence that covers the verb, resource, scope, filtering options, and pagination behavior with no filler or redundant schema information. 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?

The description is adequate for a simple list call because all parameters are optional and the workspace scope plus filters are stated. However, with no output schema and no annotations, it omits the return shape, default/sort behavior, and any permission prerequisites, leaving the agent with reasonable but incomplete context.

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 only 22%, but the description compensates by naming the filter categories: payment/fulfillment status, customer, pipeline stage, search string, and date range, plus pagination. This maps clearly to most parameters, though skip/limit semantics and exact identifier formats are still left to inference.

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

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

The description begins with a specific verb and resource, 'List orders in the workspace,' and clearly enumerates the filtering dimensions, making the tool's purpose evident. It is easy to distinguish from order-mutation tools like create_manual_order or cancel_order, though it does not explicitly differentiate itself from generic list tools such as list_records.

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 filter list implies when the tool is useful for listing or searching orders, but the description never states when to prefer a sibling like get_order for a single order or when not to use this tool. The workspace scope provides context, but no alternatives or exclusions are mentioned.

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

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

With no annotations, the description carries the full burden. It does disclose the operation is a read-only list, the scope, returned fields, and optional filtering. However, it omits common list-tool behavioral details like pagination, ordering, result limits, or whether unpublished pages are included.

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

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

A single compact sentence front-loads the action and resource, lists return fields, and mentions the optional filter. There is no redundancy 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?

For a simple read-only list with one optional parameter, the description is adequate: it defines scope, return fields, and filtering. It could mention pagination or result limiting, but those are not essential for correctly making the call.

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 describes the only parameter fully ('Optional text to filter pages by name or slug'). The description's mention of a 'search string' adds no meaningful additional semantics beyond the schema, 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 states a specific verb ('List'), the resource ('the workspace's pages'), the fields returned (id, name, slug, published), and an optional filter. It clearly differentiates this collection-level tool from single-page operations like get_page and mutating tools like create_page or delete_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 implies use when a listing of workspace pages is needed, but it does not explicitly distinguish this from siblings such as get_page or list_page_types. There is no guidance on when not to use it or which alternative to choose for a single page or page types.

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

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

With no annotations, the description carries the behavioral burden. It states that the operation is a 'List' (read-only by implication) and specifies the returned attributes, but it does not mention ordering, pagination, potential empty results, or whether only unpublished/draft types are included. Adequate but not fully transparent.

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

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

The description is a single efficiently structured sentence. It front-loads the action and resource, then adds the most useful detail about return fields. No redundant words 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?

For a zero-parameter list operation with no output schema, the description is nearly complete: it states the resource, the operation, and the fields returned. Minor omissions like pagination behavior prevent a 5, but overall the definition supplies enough for an agent to invoke 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?

The input schema has zero parameters, so there are no parameter semantics to clarify. The description adds value by naming the exact output fields, and the 0-parameter baseline of 4 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 uses a specific verb, 'List', names the exact resource ('workspace's page types (templates)'), and enumerates the returned fields: id, name, slug, and url prefix. This clearly differentiates it from siblings like list_pages, list_block_types, or list_media.

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 makes the tool's context clear: it lists workspace-level page types/templates. It does not explicitly mention when not to use it or name alternatives, but for a simple zero-parameter listing tool, the context alone is enough for an agent to select it appropriately.

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

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

With no annotations, the description carries the burden of indicating behavior, and it does confirm this is a read operation and reveals the output shape. However, it does not mention pagination behavior, whether modelId is effectively required despite the schema listing no required fields, or how filters affect results.

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 efficient sentence that front-loads the action and resource, then adds the key distinguishing details in a parenthetical. There is no filler or repetition of schema content.

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

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

For a tool with no annotations, no output schema, and a nested filter object, this description is incomplete. It omits usage boundaries, required-versus-optional parameter behavior, and filter semantics, leaving significant room for an agent to call it incorrectly.

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 only 40%, and the description does not compensate enough. It implies modelId through 'a product model's catalog' but says nothing about sort, limit, offset, or the filter object fields, leaving most parameter meaning to be inferred from names alone.

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

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

The description names a specific verb and resource: 'List a product model's catalog' with stock and variant info. It also specifies the distinguishing output details (onHand/reserved/available per record and variant), which clearly separates it from siblings like list_records and list_models.

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 clear context for when to use the tool: when you need a product model's catalog with stock and variant information. It does not explicitly name alternatives or exclusions, so it stops short of full routing guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that all records for a model are returned, that filtering supports specific operators, and that full record data is included so records can be found by field value. This is substantial behavioral transparency for a read/list tool, though it does not cover defaults or error cases.

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

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

Two sentences with no filler. The core action and model identifier are front-loaded, then capabilities are listed compactly, and the practical use case closes the description 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?

For a list tool with seven parameters and no output schema, the description covers the essential lambda: what it lists, how it identifies the model, filtering operators, sort, pagination, and return richness. It is not exhaustive about defaults or edge cases, but the schema fills in several of those 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 71%, and the schema already documents the main parameters such as filter, locale, sort, and modelIdOrSlug. The description adds high-level meaning like 'by model id or slug' and 'full data,' but it does not go beyond the schema for individual parameters. 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 opens with a specific verb and resource: 'List the records (entries) of a data model, by the model's id or slug.' It clearly distinguishes from get_record by emphasizing plural listing plus filter/sort/pagination, and it adds the useful behavior that records include full data.

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 clear context for when to use the tool: to list records of a model, filter them, sort them, paginate, and locate a record by field value without extra lookups. It does not explicitly name an alternative or state when not to use it, but the usage context is clear enough to route an agent correctly.

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

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

With no annotations provided, the description carries the full burden. It explicitly states 'Read-only,' which is a key behavioral trait, and describes the output as roles with their permissions. It lacks details on pagination or authorization scope, but for a simple zero-parameter read-only list, this is sufficient.

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

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

The description is two sentences with no wasted words. The core purpose is front-loaded, followed by the behavioral note and usage context. 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?

Given there is no output schema, the description adequately conveys what the tool returns (roles and permissions) and its scope (workspace). For a zero-parameter read-only tool, this is complete—nothing essential 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?

The tool has zero parameters, so the schema covers all parameters (100% coverage). The description does not need to add parameter semantics; the baseline of 4 applies as per the rubric.

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 'List' and the resource 'roles defined in this workspace,' and also specifies that it returns the permissions each role grants. It distinguishes itself from sibling tools like list_members or list_pages by its focus on roles and permissions.

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

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

The phrase 'Useful for understanding who can do what' provides clear contextual guidance on when to use this tool. However, it does not explicitly mention alternatives or when not to use it, though no direct sibling exists for listing roles.

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 disclosure burden. It clearly indicates a read-only listing operation and the statuses returned, but it does not mention pagination, ordering, time range, or whether delivery payloads are included. 'Recent' is vague.

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

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

A single, front-loaded sentence conveys the action, resource, relevant statuses, and purpose. There is no wasted wording or redundant schema repetition.

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

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

For a low-complexity read-only list tool with one optional parameter and no output schema, the description is largely complete. It states what is listed and why, though it could add a note about what 'recent' means or how limit interacts with results.

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

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

Schema description coverage is 0%, and the description does not mention the 'limit' parameter at all. While 'limit' is a fairly self-explanatory name, the description provides no added meaning about how it affects results or whether it applies to statuses or time range.

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

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

The description names a specific verb ('List') and resource ('webhook delivery attempts'), and clarifies the statuses included. This clearly distinguishes it from sibling tools like list_webhooks, which list configured webhooks rather than delivery attempts.

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

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

The phrase 'for debugging' gives some context for when to use the tool, but it does not explicitly mention alternatives or when not to use it. There is no guidance distinguishing it from list_webhooks or list_webhook_event_types.

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

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

No annotations are provided, so the description carries the full burden. It states the operation is a list and that it returns the authoritative allowlist, implying a read-only, definitive response. However, it does not disclose details like pagination, ordering, or error behavior. For a zero-parameter list, this is adequate but minimal.

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

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

The description is a single sentence, front-loaded with the core action, and contains zero filler. The parenthetical clarification about being authoritative adds value without unnecessary length.

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

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

For a zero-parameter list with no output schema, the description fully covers what the tool does and its authoritative nature. No additional context is needed for an agent 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?

There are zero parameters, and schema coverage is 100% (empty object). The description adds no parameter details because none exist, matching the baseline of 4 for zero-parameter tools.

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

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

The description clearly states a specific verb (list) and resource (event types for webhook subscriptions). It distinguishes itself from sibling webhook tools like list_webhooks (which lists webhooks) and list_webhook_deliveries (deliveries) by focusing on the subscribable event types. The phrase 'authoritative allowlist' adds precision.

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 when configuring webhook subscriptions, but it does not explicitly contrast with alternatives or state when not to use it. The context is clear, but exclusions are left to inference.

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

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

With no annotations, the description takes on the disclosure burden; it adds one useful behavioral guarantee: signing secrets are never returned. It does not disclose pagination, ordering, or output shape, so it covers only part of the behavior an agent might need to anticipate.

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 sentence leads with the action and object, then adds a relevant caveat in parentheses. Every word earns its place; nothing is redundant or missing for a tool this simple.

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 zero-parameter list operation, the description conveys the primary purpose and a key security-relevant caveat without an output schema. It could mention pagination or response fields, but the tool's low complexity makes the current description reasonably 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?

The tool has zero parameters, so the schema already fully defines the input surface; the description adds no parameter-specific details, and the baseline for a no-parameter tool is 4. Nothing further is required here.

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 action ("List") and a precise resource ("the workspace's webhook endpoints"), and the parenthetical about signing secrets distinguishes this endpoint-listing tool from sibling tools like list_webhook_deliveries or list_webhook_event_types.

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 clear context of listing webhook endpoints implies the primary use case, and the resource qualifier distinguishes it from related lists of deliveries or event types. It does not explicitly state when not to use it or name alternatives, but the context is unambiguous for a zero-parameter list 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?

With no annotations available, the description must carry the disclosure burden. It reveals a key non-obvious behavior: 'does NOT verify with a payment provider', which is critical for a payment-recording tool. It also notes that this is a manual reconciliation step. However, it stops short of describing side effects, idempotency, reversibility, or return behavior, so it earns a 4 rather than a 5.

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

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

Three short, purposeful clauses. The main purpose is front-loaded, the critical caveat (no provider verification) is placed immediately, and the usage condition is given at the end. No filler or repeated schema content is present.

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

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

For a 4-parameter mutation tool with no output schema and no annotations, the description is adequate for basic invocation but leaves gaps. It does not state what effect marking the order paid has on order status, whether it can be reversed, or how it differs from the sibling record_order_payment. An agent would need to infer these from context, so completeness is only moderate.

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%, so the schema already documents amount, provider, and reference. The description restates that 'amount is in minor units', which duplicates the schema, and adds only the context that the payment is 'full'. It does not clarify orderId or reference beyond the schema, so no significant additional meaning is supplied.

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 a specific verb and resource: 'Record a full payment for an order.' It adds behavioral differentiation with 'manual reconciliation - does NOT verify with a payment provider', which clearly sets it apart from any provider-verifying payment tool and suggests it is distinct from the sibling record_order_payment. The term 'full payment' further narrows scope.

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

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

Gives an explicit trigger condition: 'Only call after the user confirms.' It also implies the tool is for manual reconciliation rather than automatic verification, giving an agent a clear sense of when it applies. It does not explicitly name alternatives like record_order_payment or state when not to use it, 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?

No annotations are provided, so the description carries the burden. It discloses the key behavior of moving to root with folderId: null, which is useful. However, it does not mention whether the operation is destructive (e.g., removes from original location), whether it requires permissions, or what happens to the assets' previous folder associations. The core behavior is clear but not deeply transparent.

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

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

Two sentences, no filler. The core action and the special case (folderId: null) are front-loaded, and the pointer to list_media_folders is a single useful addition. 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?

For a simple two-parameter move operation with no output schema, the description is nearly complete. It covers the action, the destination semantics, and how to find the destination ID. The only minor gap is lack of behavioral details like whether the move is reversible or if it affects any derived data, but these are not critical for a basic move 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 schema already documents both parameters. The description adds the semantic detail that folderId: null means 'move to root', which is valuable and not fully explicit in the schema's 'or null to move the assets back to the media root' (actually the schema does say this). The description's mention of 'one or more media assets' clarifies the ids parameter's plural nature, but overall the schema already covers the meaning.

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'), a resource ('media assets'), and a destination ('into a folder or to the root with folderId: null'). It clearly distinguishes this from sibling tools like upload_media, list_media, and list_media_folders by focusing on moving existing assets.

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 tells the agent to use list_media_folders to find the destination folderId, which is a clear usage pointer. It does not explicitly state when not to use this tool or name alternatives, but the context is sufficient for a straightforward move 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?

No annotations, so the description carries the burden. It discloses marker uniqueness, the meaning of blockWarnings, and corrective action, and implies a write/save operation. It doesn't cover permissions, reversibility, or version-conflict behavior, but provides more behavioral context than typical.

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: purpose, constraint, post-condition. Front-loaded with the core function and operation types.

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?

Complex tool with six parameters and three op types, but the schema fully documents parameters and the description supplies the key operational caveats. It lacks explicit success/error response details beyond blockWarnings and doesn't mention concurrency failures, but is reasonably complete given schema richness.

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 covers all parameters at 100%, so baseline is 3. The description mentions marker matching and block warnings, but these are also in the schema; it adds no new parameter-specific meaning.

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 states a specific verb ('Apply surgical HTML edits') and resource ('block's localized content string'), lists the three operations, and contrasts with re-sending full content, which distinguishes it from the sibling update_block_content. This is exactly what an agent needs to identify the tool.

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

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

Gives an explicit gate: 'Only call after the user confirms' – clear when to invoke. It implies surgical edits vs full resend as the use case, but doesn't name alternatives like update_block_content or state when not to use it.

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

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

No annotations are present, so the description carries the full transparency burden. It discloses the mutation ('replaces the shared draft blocks'), ownership ('belongs to the token's user'), failure mode, and post-result warning semantics ('blockWarnings... violates the workspace block manifest'). This is unusually rich behavioral disclosure for a one-parameter 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 front-loads the primary action and packs prerequisites, failure, warning, and confirmation into five purposeful sentences. There is little redundancy; each sentence adds operational or safety-relevant information.

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

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

For a one-parameter mutation with no output schema and no annotations, the description covers the core call path, failure behavior, and result interpretation. It could additionally specify required parameters or return payload details, but these are largely covered by the schema and the blockWarnings note.

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 only parameter, pageId, is already fully described in the input schema ('Page id'), so schema coverage is 100%; the description adds no further type, format, or constraint details about the parameter. The baseline of 3 applies because the description mostly references 'the page' without expanding pageId semantics.

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

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

The description uses a specific verb ('Promote') and a concrete resource ('your per-user dev draft overlay onto the page's shared draft'), and clarifies what the operation does ('replaces the shared draft blocks'). This distinguishes it from siblings like update_page_blocks or publish_page because it targets the draft-promotion workflow rather than editing or publishing.

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

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

It gives a temporal precondition ('Do this after the block code for the composed types is deployed to the site'), a failure condition ('Fails when you have no dev draft for the page'), and an explicit user-confirmation gate ('Only call after the user confirms'). It does not name alternative sibling tools or state when not to call, but the context is sufficient for the primary decision.

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