Foldsquare

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

Annotations only declare the safety profile (readOnly=false, destructive=false, idempotent=false); the description adds the failure modes the agent cannot see elsewhere — a call without a template creates nothing and returns requiresTemplateChoice, a wholesale document without a discount returns requiresWholesaleDiscount, and validation failures come back as valid: false with actionable issues. It also explains the post-creation link semantics, which no annotation covers.

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?

Front-loaded with the purpose and generally dense with information, but delivered as one long semicolon-linked paragraph with some restatement ('The template is the merchant's choice' / 'it is the merchant's figure'). Structuring the two hard requirements as separate sentences or bullets would improve scanability.

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

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

An output schema exists, yet the description still adds the non-obvious fact that `viewerUrl` is null until publishing and `editorUrl` is the only working link — behavioral, not structural, information. Combined with the grammar pointer, the required-field conditions and the error-answer shape, an agent has everything needed to call this 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% and the `document` object is free-form, so the description's explanation of its internals (template, usage: "wholesale", wholesaleDiscountPercent, product selection by collection/id/search) is the only real specification available, plus the grammar URI. It stops short of covering `idempotencyKey` and the `withoutTemplate` escape hatch, which live only in the schema text.

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 ('Build a catalog from a DSL document') and immediately enumerates what the document produces (pages, product grids, per-product fields). An agent can distinguish this from edit_catalog/update_catalog/duplicate_catalog by the name plus the 'build from document' framing.

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 clear conditional prerequisites (a `template` is required; wholesale documents additionally require `wholesaleDiscountPercent`) and routes sub-lookups to list_templates, list_collections and search_products. It does not state when to prefer this over edit_catalog or duplicate_catalog, which is the one remaining routing gap.

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

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

Annotations already flag destructiveHint and idempotentHint, but the description goes further: it discloses effects (public link stops working, tools lose access, plan slot freed), the confirmation gate, and the authorization constraint. This is exactly the consequence-level detail an agent needs before an irreversible call.

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?

Front-loaded with the action, and every clause carries real information. The long compound sentence about the catalog's disappearance is slightly awkward ("these tools cannot reach it afterwards") but earns its place through consequence detail.

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 two-param tool, everything an agent needs is present: effect list, confirmation workflow, and ownership restriction. An output schema exists, so the absence of return-value documentation is not a gap.

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

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

Schema coverage is 100%, so the schema already documents both params. The description nonetheless adds workflow meaning to confirm — it is the second leg of a dry-run approval cycle, with the pre-confirm output surfaced as requiresConfirmation — which the schema description alone only hints at.

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?

Opens with a specific verb and resource ("Delete one of the merchant's catalogs"), which cleanly separates it from siblings like delete_products and edit_catalog. An agent knows immediately this permanently removes a catalog object.

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

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

Explicitly states the two-phase protocol: it only runs with confirm: true, and without it nothing is deleted and the response lists candidates under requiresConfirmation. It also names the exclusion — shared catalogs are refused, only the owner can delete — so the agent knows when not to call 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?

Annotations already declare destructiveHint=true, but the description adds the crucial two-phase contract: without confirm nothing is deleted and the response enumerates targets under requiresConfirmation. It also discloses blast-radius limits (store products untouched, catalogs keep their own tile copies), which is exactly the context annotations cannot carry.

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 load-bearing: scope, side-effect boundary, then the confirmation protocol. The safety-critical constraint is front-loaded in sentence three before any invocation risk.

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

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

An output schema exists so return values needn't be fully described, yet the description still explains the one response branch that governs agent behavior (the requiresConfirmation preview). For a two-parameter destructive tool, nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description earns above baseline by explaining confirm as the approval gate tied to the requiresConfirmation list rather than just a boolean flag. productIds semantics beyond 'ids as search_products reports them, or skus' are left to the schema.

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

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

States a specific verb (remove) and a precisely scoped resource (products held in Foldsquare), and immediately bounds it against what is not affected: store products and catalog copies of tiles. An agent can distinguish this from delete_catalog or update_product without opening a 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?

Gives a clear operational rule: it only proceeds on a call with confirm: true, and without it the answer is a would-delete preview for merchant approval. It does not name sibling alternatives (e.g. delete_catalog) for contrast, so it stops short of explicit when-to-use vs which-tool 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?

Adds real behavior beyond the annotations: the default title pattern, the critical rule that the copy is always unpublished regardless of the original's state, and that it returns the copy's summary with an editorUrl. The 'always draft / unpublished' caveat is the kind of state consequence an agent can't infer from readOnlyHint=false and destructiveHint=false.

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 what gets copied, then the naming rule, then the state caveat and return value. No 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?

A creation tool with an output schema already covering returns; the description still supplies the two things an agent most needs — what is duplicated and the unpublished state of the result. 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?

Schema coverage is 100%, so baseline is 3, and the description goes further by explaining the optional title's effect (overrides the '<title> (Copy)' default). catalogId is left to the schema, which is fine since it already points at list_catalogs.

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?

Specific verb (copy) plus resource (catalog) and an enumeration of what is carried over (pages, products, design, block library). It's clearly distinct from create_catalog, which would make an empty catalog, and from update_catalog/edit_catalog.

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?

States the intended scenarios ('for a new season or a variant'), which implies when this beats create_catalog from scratch. It does not explicitly name an alternative or say when not to use it, so not 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?

Annotations only give readOnly=false, destructive=true, idempotent=false; the description goes far beyond by naming what is destroyed (setGrid on a blank/cover page removes what was on it), that destructive ops require confirm:true and otherwise return requiresConfirmation, that an open editor tab overwrites the edit on its next autosave, and that only named fields are touched while catalog-scoped edits survive later syncs. It also discloses the first-edit-only `livePreviewUrl` return behavior, which annotations cannot convey.

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 op list is appropriately front-loaded, but what follows is a single dense block of prose mixing the store-vs-catalog boundary, dynamic fields, block ids, grid rules, confirmation, and preview URLs with no internal structure. Nearly every sentence carries real information, yet the all-caps emphasis scattered mid-paragraph and the sheer length make it harder to scan than it needs to be.

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 multi-op patch tool, the definition covers the gaps an agent would otherwise hit: page index vs. displayed page number ('page 6 (index 5)'), grid bounds (10 x 50), collection-linked runs and removeProduct by collectionId, header/footer scoping, and confirmation semantics. With an output schema present, it correctly stops short of explaining return shapes beyond the one non-obvious field (livePreviewUrl).

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 ops schema already carries heavy prose, so the baseline is 3; the description still adds meaning the schema does not duplicate cleanly, such as `productId` limiting a design edit to one tile that 'then stops following the catalog design', `at.area`/`at.relativeToBlock`/`at.box` being percentages of the tile, and `inProductCells: true` adding a block to every tile. It also points to foldsquare://schemas/catalog-edit-ops.json for per-op field lists rather than restating them, which is a useful pointer but leaves per-op argument semantics delegated.

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?

Opens with a specific verb and resource ('Apply targeted changes to an existing catalog') and then enumerates the full op vocabulary (addProducts, setGrid, editBlock, etc.), so an agent knows exactly what surface this tool covers. It also draws a sharp boundary that no sibling covers: 'EVERY edit here is scoped to THIS CATALOG, never to the merchant's store,' which distinguishes it from update_product and update_catalog.

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-use routing: which fields a tile shows changes through editBlock with `lines` and '`setFields` is retired and always refused'; a custom grid is always `setGrid` and 'never refuse a grid because of the kind of page it is asked for'; a new grid page is addPage followed by addProducts. It also states the prerequisite for ids ('Page indexes come from get_catalog's `pages` ... block ids from `blocks` and `productCell`') and the confirm:true gate for re-layout/deletion.

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

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

Annotations only say readOnlyHint=false and openWorldHint=true; the description goes much further by disclosing the write gating on confirm, the dry-run listing returned under requiresConfirmation, the confirmWith pass-through arguments, the draft refusal, and the owner-only permission requirement. It discloses what changes and what does not on each call.

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?

Front-loaded with the purpose, then modes, then confirmation flow, then defaults and constraints. Sentences are dense with em-dash asides; every clause carries substance, though the single long middle sentence could be split for readability.

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

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

Despite an output schema existing, the description explains the key return shapes (page listing, requiresConfirmation, confirmWith), which the agent needs to drive the confirmation loop. Combined with the mutation gating and permission notes, nothing essential is missing for a 6-parameter write 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?

Even with 100% schema coverage, the description adds meaning the schema lacks: width/height defaults (100% and 800), that pageId must come from the listing, that newPageTitle creates a page, and the exact semantics of confirm plus the returned confirmWith. This is real added value beyond field descriptions.

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

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

States a specific verb and resource ('Put a published catalog on a page of the merchant's own Shopify or WooCommerce store') and anchors it to a known surface ('as the Publish dialog's store tab does'). It is clearly distinguishable from siblings like publish_catalog and open_publish_settings, which do not touch store pages.

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

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

Explicitly defines the three mode branches: catalogId alone lists pages, pageId or newPageTitle performs an embed, and confirm: true is required to actually mutate the store. It also states exclusions ('A draft is refused') and the owner-only restriction, leaving nothing 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds substantial context beyond them: which metrics are only available account-wide, that the heatmap and top products depend on plan tier, and that `live` returns the last five minutes. It also discloses the failure behavior when the plan lacks analytics — exactly the kind of thing an agent needs before calling.

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?

Dense but well front-loaded: the metric set comes first, then the branch on `catalogId`, then the plan prerequisite. Every sentence carries information, though the run-on em-dash construction of the middle sentences makes it slightly harder to scan than a bulleted branch would be.

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 an output schema present, return values need not be spelled out, yet the description still sketches the response shape for both modes. Combined with the plan gating, account-wide-only caveat and `live` semantics, an agent has everything needed to pick parameters and interpret the 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%, so baseline is 3; the description earns an extra point by explaining the consequence of `catalogId` (overview vs. catalog detail, heatmap, top products, live) rather than just naming the field. It adds only light context for `period`/`from`/`to` beyond the schema's own enum and date-format documentation, which already handles those.

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 concrete verb and resource — analytics (views, unique visitors, product clicks, time series) over a period — so the agent knows exactly what data comes back. However, it never distinguishes itself from the near-identically named sibling `show_analytics`, leaving the agent to guess which one to call.

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 conditional guidance tied to `catalogId`: omit it for the account-wide overview with top catalogs/referrers/countries/devices/browsers, supply it for per-catalog detail, heatmap, top products and `live`. It also flags the prerequisite (a plan with analytics, with a graceful in-band failure message). The one gap is that it offers no guidance versus the `show_analytics` sibling.

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

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

Annotations already declare a safe read-only, non-destructive, closed-world operation, and the description adds substantial behavioral detail beyond that: the distinction between `pages` indexes and `document.pages` positions, the folding behavior for multi-page collections, and that unsupported DSL content is listed under `unsupported` rather than omitted.

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

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

The description is front-loaded with the core return value and every major clause carries useful information about the response shape. It is dense and somewhat run-on, but the density is largely justified by the complexity of the returned catalog 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?

Given a read-only tool with full annotation coverage, a fully described one-parameter schema, and an output schema, the description is complete enough to call it correctly. It covers the key return components, the crucial page-index caveat, ID provenance, and unsupported content handling.

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

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

Schema coverage is 100%, so the single catalogId parameter is already documented. The description adds useful provenance by stating that the catalog id comes from list_catalogs, though it adds no further format or constraint details 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 and resource: it returns an existing catalog as a DSL document and enumerates the pages, blocks, chrome, and productCell data included. It clearly distinguishes this read operation from edit_catalog by explaining that its page indexes and ids are the source for edit_catalog 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?

It gives clear usage context by saying the catalog id comes from list_catalogs and that this tool supplies the indexes and ids used by edit_catalog. It does not explicitly exclude alternatives such as preview_catalog or get_catalog_pdf, but the primary when-to-use guidance is strong.

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?

Goes well beyond the annotations by disclosing the caching rule (stored PDF returned when newer than last change), the ~20 second sync threshold, the full four-value `state` machine with what accompanies each state, and the explicit warning that "rendering" is not a failure and large catalogs take minutes. This is exactly the behavioral context the annotations (readOnly=false, destructive=false) leave unstated.

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?

Front-loads the outcome (a download link) before the mechanics, and every sentence carries information an agent would otherwise get wrong. The dense em-dash stacking makes it slightly harder to parse at a glance, keeping it off a 5.

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

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

For a three-parameter tool with an output schema, the description covers everything an agent needs: trigger semantics, default format, async polling, and the non-failure "rendering" state. No material gap remains.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `pdfFormat` is compressed by default and "print" is for press quality, and `jobId` is tied to polling a prior "rendering" response. Only `catalogId` is left to the schema.

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

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

States a specific verb (download/get link) and resource (catalog rendered as PDF), plus the scope of draft vs published catalogs. It does not name or distinguish itself from adjacent siblings such as preview_catalog or preview_page_image, so an agent must infer which of the rendering tools to pick.

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 clear operational guidance: it explains that a cached PDF returns immediately, that a render otherwise starts, and that a follow-up call with `jobId` retrieves the link when the render finishes. It stops short of naming alternatives or stating when-not to use it, so it is context-rich but not fully 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?

Annotations already declare readOnly and non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: the found:false / exhaustive:false combination does not mean the product is absent, and SKU lookups may resolve to a variant rather than a product — semantics an agent could easily misread from the output schema alone.

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 doing work: the operation, the parameter hierarchy, and the failure-mode caveat. Front-loaded and free of filler, with only minor overlap between the SKU/handle sentence and the schema descriptions.

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 an output schema and read-only annotations already present, the description supplies what structured fields cannot: the exclusivity rule and the interpretation of the ambiguous found/exhaustive result pair. The one gap is that the 'source' parameter is delegated entirely to search_products rather than described here.

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

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

Schema coverage is 100%, so all five parameters are already documented, including the source enum and includeVariants default. The description's one real addition is the implicit 'exactly one of' exclusivity constraint, which the schema does not encode (no oneOf), but the rest restates schema content.

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?

Opens with a specific verb and resource ('Look up a single product in full') and immediately constrains the scope to exactly one of three lookup keys. It is clearly distinct from search_products, which it references as the underlying mechanism for SKU/handle resolution.

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 actionable selection guidance among the three lookup parameters, explicitly recommending productId as the reliable path and flagging SKU/handle as slower, possibly many-to-one lookups. It stops short of stating when to prefer search_products first or when this tool should not be used.

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

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

Annotations already mark it read-only and non-destructive, but the description adds meaningful context: it never returns the password itself, and `locked` explains plan/store restrictions with reasons. The closing 'Reads the catalog and changes nothing' reinforces the safety profile without contradicting 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 opening clause is front-loaded and the sentence is dense but purposeful, enumerating the fields the agent will receive. It is slightly laundry-list-like, but the length is justified by the breadth of the returned settings.

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

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

An output schema exists, so the description need not define return shape, yet it still summarizes the substantive fields and explains the special `locked` list. Combined with the usage guidance and read-only assurance, an agent has everything needed to call this 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 is only one parameter, and the schema fully documents catalogId as coming from list_catalogs. The description adds no further syntax or format details about the identifier, so baseline 3 applies when schema coverage is 100%.

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 read operation and enumerates exactly what it returns: publish state, custom URL, click behavior, auto-sync, lead form, password status, SEO visibility, viewer styling, share link, embed code, and editor/live-preview links. This is far more specific than the title and clearly distinguishes it from set_publish_options and open_publish_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?

It explicitly says to use this before set_publish_options and for questions about sharing or whether the catalog is live, which gives the agent a concrete trigger. It does not explicitly exclude alternatives such as get_catalog or open_publish_settings, so the routing guidance is clear but not exhaustive.

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

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

The description adds useful behavioral detail beyond the annotations: products that cannot be stored are reported individually while the rest still land, existing products with the same id or sku are updated rather than duplicated, and idempotencyKey prevents duplicate imports on retry. It does not explicitly warn that updating existing products may overwrite fields, though the destructive annotation already signals mutation risk.

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

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

The description is front-loaded with the core purpose and then efficiently covers input shape, required fields, partial failures, duplicate handling, visibility, and idempotency. Every sentence contributes operational information without repetition.

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

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

Given the tool's complexity, annotations, and output schema, the description is complete enough for correct invocation. It explains the import contract, required product identity, partial-success semantics, update versus skip behavior, and how imported products are found afterward.

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%, but the description still adds meaningful semantics: title is the only required product field, id or sku is the identity key, and products must conform to foldsquare://schemas/product-import.json. It also clarifies how onExisting and idempotencyKey affect import behavior.

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: storing products in Foldsquare so they can be put in a catalog. It also distinguishes this from a generic import by explaining the standard import shape and the absence of a server-side parser. An agent can tell what this tool is for 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 clear usage context: products must already be in the standard shape, only title is required, and id or sku determines identity. It also explains default update behavior and the onExisting skip option, though it does not explicitly contrast this tool with update_product for single-product edits.

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

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

Annotations already declare read-only, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: results are newest-first, summaries omit page contents, and archived/deleted catalogs are absent from every result and inaccessible through these tools.

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, front-loaded with the core action and ordering, followed by search guidance, return scope, and archived-catalog caveat. Every sentence adds actionable 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?

An output schema exists, so return values need not be fully explained, but the description still clarifies that summaries contain ids, titles, and counts. Annotations cover safety, and the description covers ordering, search usage, and archived exclusions—everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful usage semantics for `search`—finding a catalog by title when the user refers to one by name, with an example—going beyond the schema's terse 'case-insensitive match against the catalog title'.

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 ('List the merchant's catalogs') and adds scope details: newest-first ordering, summaries only rather than page contents, and archived exclusion. This clearly distinguishes it from get_catalog and preview tools.

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

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

Explicitly tells the agent to use the `search` argument when the user refers to a catalog by name, with a concrete example. It also implicitly steers away from this tool for page contents and archived catalogs, though it does not name an alternative sibling tool explicitly.

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

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

Annotations already establish readOnly=true, destructive=false, and closed-world, so the safety profile is covered. The description adds a meaningful behavioral constraint ("Owner only") and clarifies that pending invitations are included, though it does not discuss pagination or failure 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 dense sentence plus the "Owner only" restriction, with no filler; the returned fields are front-loaded. Structure is fragment-like but efficient.

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

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

For a one-parameter, read-only tool with rich annotations and an output schema, the description supplies the important missing context: the access scope and output composition. An agent has enough information to call it correctly without further prose.

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 required parameter catalogId is fully described in the schema, including how to obtain it from list_catalogs. The description adds no parameter-level detail beyond the schema, so the high coverage 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 names the resource (catalog shares) and enumerates exactly what is returned: owner plus shared users with email, name, role, and active/pending status. It does not explicitly say "list" or point to a sibling, so it is clear but not fully self-differentiating.

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 adds the authorization condition "Owner only," which is useful context for whether the agent may call it. It does not state when to choose this over siblings such as get_catalog or update_catalog, nor does it describe preconditions beyond ownership, so usage is only implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds useful context beyond that: points are newest-first, expire after thirty days, carry an id, timestamp, and the tool that was about to run, and reason values have distinct semantics.

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

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

The description is front-loaded with the resource and ordering, then explains reason semantics and expiry in three dense sentences. Every sentence carries useful information, though the middle sentence about assistant/restore points is slightly convoluted.

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 annotations covering safety and an output schema covering return shape, the description supplies the behavioral context an agent needs: ordering, expiry, and what each snapshot represents. It could be more explicit about when to call it, but the essential context 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?

There is only one parameter, and the schema already gives it 100% description coverage ('Catalog id, as returned by list_catalogs'). The description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific resource (a catalog's restore points) and an ordering (newest first). It also explains the meaning of the reason values, which distinguishes this listing from generic catalog reads and makes the tool's role 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?

Usage is implied rather than stated explicitly: the description explains that the newest 'assistant' point is the pre-change state and that a 'restore' point undoes a restore, but it never says when to call list_catalog_snapshots versus restore_catalog_snapshot or other catalog tools. The agent can infer the workflow but has to do the work.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuine non-obvious behavior: parentId is often null because only some platforms report hierarchy, and a flat list is not evidence of no hierarchy. That is real context an agent would otherwise misread as a data quality signal.

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, intended workflow, and a caveat about parentId. Front-loaded with the core purpose and no 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?

Output schema exists so return values need not be explained, and annotations cover safety. Remaining gap is minor routing detail versus sibling list tools (list_catalogs, list_product_facets) and how the resolved id should be handed to search_products, but nothing blocks 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?

Schema coverage is 100% and each parameter (limit, search, source, parentId, topLevelOnly) is fully documented in the schema, including the parentId/topLevelOnly interaction. The description adds only the conceptual note about parentId nullness, not new syntax or defaults. 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?

States a specific verb+resource ('List the merchant's product collections/categories') and goes further to explain its role: resolving a merchant-named collection to the id that search_products takes. Distinguishes it from list_catalogs and get_catalog by naming its downstream consumer explicitly.

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 'resolves a collection the merchant names ... to the id search_products takes' clause is a clear use case that routes an agent from a natural-language request to this tool then to search_products. It does not, however, contrast against list_product_facets, get_catalog, or list_catalogs, so alternative routing is partly inferred.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context—newest-first ordering, inclusion of uploads and the brand logo, and returned placement URLs—but does not discuss pagination behavior or limits beyond the schema.

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

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

A single compact sentence front-loads the resource, its contents, ordering, and returned URLs with no wasted wording. The search capability is appended efficiently.

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

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

An output schema exists, annotations cover safety, and the description explains the library contents and ordering. It is nearly complete for a two-parameter read-only list tool, though it omits explicit when-to-use guidance against upload_image.

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 limit and search fully. The description reinforces that search is by image name, but adds no syntax, defaults, or constraints beyond the structured fields.

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

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

The description clearly identifies the resource as the merchant's image library, including uploads and the brand logo, and notes ordering and usable URLs. It does not explicitly differentiate from the sibling upload_image tool, keeping it below a 5.

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 mentions searching by name but gives no guidance on when to use this tool versus alternatives such as upload_image, nor any exclusions or prerequisites. The usage context is only implied through the content 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?

Adds meaningful context beyond the readOnly/openWorld/destructive annotations: owner-only access, newest-first ordering, and a special response when the form is off. It does not cover rate limits or permission details, but the annotation bar is lower and the added behavior is useful.

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?

Compact at three sentences with no redundant information. The first sentence is dense and phrased awkwardly as a noun phrase, but the content is front-loaded enough for an agent to parse quickly.

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

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

Output schema, annotations, and full schema coverage mean the description need not explain return values or parameter syntax. It still includes owner restriction and form-off behavior, making it complete for this low-complexity read 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 coverage is 100%, so page, limit, and catalogId are already documented in the input schema. The description adds no parameter-level meaning beyond the schema, which is baseline when the schema does the work.

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?

Identifies the resource clearly: visitors who submitted a catalog's lead form, along with the returned fields. It is phrased as a noun phrase rather than a verb and does not explicitly contrast with any sibling tool, but an agent can still tell it lists leads.

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 notes the owner-only restriction and the empty-form state, but gives no explicit when-to-use guidance or alternative tool routing. Usage is implied from the resource description rather than 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral context: values are exact-match keys, not merchant paraphrases; `complete: false` signals no published list; and empty values are not evidence of absence. That is substantive beyond the annotations, though auth, rate limits and ordering behavior are left to the schema.

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

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

Three tight sentences, front-loaded with the core content ('the values the store actually uses') before the search_products relationship and the caveat. The opening noun fragment is slightly clipped but costs nothing.

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 an output schema present the description needn't explain return shape, and with full schema coverage it needn't repeat parameter docs; what remains — why the values matter and how to read `complete: false` — is covered. Nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so all four parameters are already documented, and the description adds no per-parameter detail for `limit`, `fields`, `source` or `collectionId`. It does explain the semantics of the `scoped`/`complete` flags at a conceptual level, but the baseline of 3 is the correct ceiling 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 states exactly what is returned — the vendor, productType and tags values the store actually uses — and ties that directly to search_products' exact-match filters, which distinguishes it from the sibling that consumes these values. It never states an explicit verb (the 'List' framing only appears in the title), so it falls just short of a textbook verb+resource statement.

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

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

It implicitly but clearly positions the tool as the prerequisite to search_products: 'these are the values its filters take' tells the agent to come here before filtering. It also gives a when-not-to-trust rule via the `complete: false` caveat. No explicit 'do not use this for X' exclusion is offered.

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

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

Annotations already mark it read-only/non-destructive, and the description adds context annotations cannot: the MCP Apps picker panel, that the merchant's pick arrives as their next message, and that thumbnailUrl drives that panel's imagery. That is real interaction behavior beyond the safety hints.

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?

Front-loaded with what a template is and when to call, then the picker behavior. Six sentences is long for a list tool, but nearly all of it carries load; the MCP Apps picker sentence is defensible because it changes how the agent should read the follow-up message.

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

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

An output schema exists, so return values needn't be explained, yet the description still tells the agent what each entry contains and how the id feeds create_catalog. Prerequisites, failure mode of the alternative, and UI behavior are all covered — nothing needed to call it 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?

Schema coverage is 100% and the single `search` parameter is fully documented in the schema; the description never mentions it. It does add meaning about the returned entries (id, title, products-per-page, thumbnailUrl) and links the id to create_catalog's `template` argument, but input-side semantics are left entirely to the schema.

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

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

States a specific verb and resource (list the templates a catalog can be built from) and immediately defines what a template supplies — covers, fonts, colours, product-cell layout. This separates it cleanly from siblings like list_images or list_collections, which are also 'list' tools over catalog 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?

Explicit sequencing: 'Use it before create_catalog', plus the consequence of skipping it ('create_catalog without one refuses and returns these same choices') and the irreversibility ('cannot be swapped afterwards without rebuilding'). An agent knows exactly when and why to call this versus going straight to create_catalog.

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

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

Annotations cover the safety profile (readOnly, non-destructive, closed-world), and the description adds non-obvious behavior: plan-disallowed options render locked, the password is typed into the panel and never transits the chat, and the saved result is reported back afterwards. These are things an agent could not infer from annotations or schema.

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

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

The verb and resource are front-loaded and every later clause carries actionable information (exclusion case, host caveat, password handling). The settings enumeration is a long run-on list, but it is doing real work rather than padding.

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 UI-opening tool with an output schema, the description covers the interaction model, what happens on save, the fallback when MCP Apps is unavailable, and the alternative tool. Nothing an agent needs to call it 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?

The single catalogId parameter is fully documented in the schema (100% coverage, including that ids come from list_catalogs), and the description adds nothing about it. With the schema carrying the full burden, 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?

Opens with a concrete verb and resource ("Open the Publish dialog beside the chat") and enumerates exactly what the panel contains, so an agent knows this is an interactive settings UI rather than a data fetch. It also names the sibling it is not (set_publish_options) for the single-change case.

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?

Explicit selection criteria: use it "when they want to review or change several of these at once, or to set a password," and use set_publish_options instead for "a single change they have already named." The host prerequisite (needs MCP Apps, otherwise text fallback) is also stated, which prevents a failed invocation.

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

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

Annotations already declare readOnlyHint/destructiveHint false, so the bar is lower, and the description still adds real context: an interactive UI is opened, `purpose` becomes the picker heading and is echoed back, the selection arrives as ids in context plus a merchant message, and a host must support MCP Apps. It does not mention the sibling pick_products_search or what happens on a non-MCP-Apps host, which keeps it from a 5.

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

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

Front-loaded with the core action, then return shape, then the routing rule — a sensible order with no filler. It is denser than it needs to be in places (the filter enumeration partly duplicates the schema) but every sentence carries 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 an interactive tool with 8 optional params and an output schema, it covers the essentials: what the merchant does, what comes back, the environment prerequisite, and where the result plugs in. The main gap is behavior on hosts without MCP Apps support and its relationship to pick_products_search.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by explaining that `purpose` is rendered as the picker's heading and repeated back with the selection, and by framing the filters as in-picker facets. Remaining parameters get no added semantics because the schema already covers them well.

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 — opens a product picker beside the chat — and describes the interaction (search, filter, tick from a picture grid) and the return (product ids plus a merchant message). It explicitly contrasts with search_products, so an agent can route without opening a 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?

Gives an explicit when-to-use condition ("Call it when a selection is theirs to make by looking", a hand-picked page) and an explicit when-not with the alternative named ("products described well enough to search for are search_products"). It also names the downstream consumers, create_catalog and edit_catalog addProducts.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world). The description adds that the result is a page of products shaped as picker tiles, which is useful framing, but says nothing about pagination behavior even though a cursor parameter exists. An output schema exists, so return-value detail is not required.

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

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

Two compact sentences with no filler, and the picker context is front-loaded. The second sentence is a slightly abrupt redirect but earns its place by naming the alternative.

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 a full schema, complete parameter docs, and an output schema, most of the burden is carried by structured fields. The description nevertheless leaves an agent unsure whether this is an agent-facing tool at all, since it reads as documentation of a UI's internal 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?

Schema description coverage is 100%, so all eight parameters are already documented, including cross-references to search_products, list_product_facets, and list_collections. The description adds no parameter-level meaning beyond what the schema provides; 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 the resource (a page of products, as picker tiles) and its calling context (the product picker, invoked as the merchant searches and filters). It also distinguishes itself from search_products by naming that sibling as the general finding tool. The verb is only implied ('calls it as the merchant searches and filters'), keeping it short of a fully specific verb+resource statement.

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

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

'search_products is the tool for finding products' explicitly points to the alternative, which is the strongest guidance here. The trigger context ('as the merchant searches and filters') implies when this tool is relevant, but it never states whether an agent should call it directly or only the picker UI should.

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

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

Beyond annotations, it explains that `livePreviewUrl` is a read-only page showing the catalog exactly as it renders, reloading automatically when the catalog changes while keeping the viewer on the same page. It also clarifies that nothing opens beside the chat and that the tool reads the catalog without changing anything.

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

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

The description is front-loaded with the core result and the `livePreviewUrl` return value, then adds usage cues and sibling differentiation. Despite being information-dense, every clause contributes to selecting or understanding 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?

The tool has an output schema and rich annotations, and the description still adds the important live-reload behavior and in-chat presentation boundary. An agent has enough information to choose this tool and understand what it returns.

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 `catalogId` parameter is already documented as coming from `list_catalogs`. The description does not add further parameter meaning beyond what the schema provides.

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

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

The description states a specific resource and output: the catalog as a whole, returning the page list and `livePreviewUrl`. It also clearly differentiates itself from `preview_page`, which shows one page or a few as pictures beside the chat.

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 explicit use cases: "show me", "what does it look like", or following edits as they land. It also gives a clear exclusion by directing single-page image previews to `preview_page` instead.

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

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

Annotations already declare readOnlyHint/destructiveHint=false, and the description clarifies the apparent tension by stating outright "Reads the catalog and changes nothing" while disclosing that panel-side merchant actions happen outside the call and shift page indexes afterwards (recoverable via get_catalog). It also documents the host-dependent rendering, the panel controls, and the text-result fallback for hosts without a panel — well beyond what annotations provide.

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 opener ("One page, or a few, as pictures") is the vaguest sentence and comes before the load-bearing routing and indexing rules, so front-loading is weak. The zero-based convention is effectively stated twice, and the panel-mechanics paragraph is dense prose for a two-parameter read 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?

With an output schema present, return values needn't be described, yet the definition still notes the text result lists pages plus the editor link. Combined with the panel behavior, index-shift consequence, and sibling routing, an agent has everything needed to call it and anticipate the 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 description's zero-based explanation ("the merchant's 'page 1' is index 0") largely restates the schema's own description of `pages`. It adds the conversational mapping from merchant phrasing to index, but says nothing about catalogId beyond what the schema states, and omits the 1–50 item bounds.

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 definition states a concrete verb and resource — render selected catalog pages as pictures, optionally in an MCP Apps side panel — and explicitly routes whole-catalog viewing to preview_catalog. It does not distinguish itself from the sibling preview_page_image, which plausibly overlaps, so the scope boundary is not fully closed.

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 the exact selection condition ("For a specific page ('show me page 2', 'let me see the cover')") and names the alternative for the opposite case ("The catalog as a whole is preview_catalog"). It further explains the merchant-facing index convention and the downstream edit path (Point & edit → ids edit_catalog takes), leaving no routing decision 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?

Annotations already cover safety (readOnly, non-destructive, closed-world), and the description adds the return shape (rendered image URL) plus the high-frequency scroll invocation pattern, which matters for batching or rate considerations. It stops short of any explicit cost or throttle guidance given that per-scroll calling pattern.

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

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

Two short sentences, front-loaded with the caller context before the return value. The opening clause about the preview panel is slightly wordier than needed but earns its place by explaining the invocation cadence.

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

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

An output schema exists and both parameters are fully documented in the schema, so the description needn't explain returns or inputs. The only residual gap is the fuzzy overlap with preview_page, but nothing required to call it 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?

Schema description coverage is 100% and both parameters already document their provenance (index from preview_page, catalogId from list_catalogs). The description adds nothing about either parameter, 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 concrete verb+resource: returns one catalog page as a rendered image URL. It also names the sibling preview_page and positions this as the panel-driven image variant, though the distinction ('preview_page is the tool that shows pages to the merchant') is a bit circular for an agent that only knows it wants a 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?

It discloses the intended caller ('the preview panel, which calls it for each page as it scrolls into view') and points at preview_page as the merchant-facing alternative. The routing condition is implied rather than stated as an explicit 'use X when / use this when', so an agent has context without a crisp rule.

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?

Adds substantial context beyond the annotations: exact render.state values and their meanings, the ~20 second async threshold, that a 'rendering' result is not a failure, and the full confirmation flow including requiresConfirmation/confirmWith payload structure. With annotations covering the safety profile, this is unusually rich disclosure.

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?

Front-loads the core action in sentence one, then layers async behavior, state values, and the confirmation gate in a logical order. It is dense but every sentence carries information; minor length is justified by the async/confirmation complexity.

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 an output schema, async job semantics, and a confirmation gate, the description covers everything an agent needs: what happens immediately vs. asynchronously, how to retrieve the PDF later, and how to handle the untrusted draft case. No material 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 coverage is 100%, so the baseline is 3. The description goes further by explaining the actual behavioral meaning of confirm (draft goes live only with it; otherwise a read-only preview of what would go live is returned) and the render parameter's timing implications, which the schema's one-liners don't convey.

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?

Opens with a specific verb+resource ('Make a catalog live and start rendering its PDF'), which distinguishes it from preview_catalog, get_catalog_pdf, and set_publish_options. An agent can identify the operation 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?

Gives clear conditions: drafts need confirm: true, already-live catalogs re-render without confirmation, and render: false skips the PDF. It routes to get_catalog_pdf for async retrieval. It does not explicitly name sibling tools like get_publish_options or preview_catalog as alternatives, so a 4 rather than a 5.

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

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

The description transparently explains destructive effects, undo behavior, confirm handling, and what is preserved, but it explicitly says the operation is destructive while annotations declare destructiveHint=false. That is a direct contradiction in a safety-relevant 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 dense but front-loaded: effects, exclusions, undoability, confirmation behavior, and snapshot source each appear in a purposeful sentence with no 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?

Given that an output schema exists and the schema fully documents parameters, the description covers the remaining agent-critical context: restoration scope, preserved state, undo behavior, confirmation handling, and snapshot selection.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful meaning: confirm enables the dry-run/approval workflow when absent, and snapshotId is sourced from list_catalog_snapshots, with a specific rule for finding the pre-assistant state.

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: putting a catalog back to a restore point from list_catalog_snapshots. It also names exactly which catalog aspects are restored (pages, products, design, settings), making it distinguishable from edit_catalog and update_catalog.

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?

Clearly directs the agent to obtain snapshotId from list_catalog_snapshots and explains that the newest reason="assistant" point is the state before the last assistant change. It also specifies the confirm: true approval flow, though it does not explicitly compare when to use restore versus selective edit_catalog actions.

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

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

Annotations already cover the read-only, non-destructive, closed-world profile, and the description adds real value beyond them: live vs stored reads, that some stores cannot apply every filter, and that filtered searches can stop early with `partial` and a `note` explaining coverage. It does not discuss rate limits or cost, but the partial-result warning is the important behavioral disclosure.

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 sentences with no filler, front-loading the resource and backend distinction before the output-contract and partial-result caveat. Dense but each sentence carries information an agent needs.

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 13-parameter search tool with an output schema and full schema descriptions, the description supplies the pieces the schema cannot: which backend is read, the id contract with create_catalog, and the meaning of `partial`/`note`. Complete enough to call correctly without opening the schema.

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

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

Schema description coverage is 100%, so the parameters are already fully documented. The description adds only a general caveat that filters may be unsupported per store; it provides no per-parameter guidance beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ("Search the merchant's products") and immediately clarifies the two backends it can hit: a live connected store or Foldsquare-stored products. It does not explicitly distinguish itself from near-name siblings like pick_products_search or get_product, so it stops short of a 5.

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 a concrete usage rule: connected store → live query, otherwise Foldsquare, and notes that import_products additions are only visible via the Foldsquare source. It omits when an agent should prefer a different search/pick tool, so alternatives are only partially addressed.

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

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

Beyond annotations, it discloses partial-update semantics, plan/store permission handling via `applied` and `refused` with reasons, no silent downgrades, password non-return, and the draft-to-live confirmation flow with `requiresConfirmation` and `confirmWith`. These are material behavioral details an agent needs before invoking a destructive, open-world mutation.

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

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

The description is long but mostly earns its length given the many nested options and confirmation behavior. It is front-loaded with purpose and option scope, though the dense single paragraph could be more clearly structured.

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 destructive mutation with nested objects and an output schema, the description covers the key gaps: partial updates, permission refusals, confirmation requirements, password handling, and the distinction from sibling publish tools. Nothing essential for correct invocation appears missing.

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

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

Schema description coverage is 100%, so the schema already documents individual parameters in detail. The description still adds cross-parameter meaning: omitted options remain unchanged, `confirm: true` gates draft publication, and `published: true` has different PDF behavior than publish_catalog.

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: switching the Publish dialog's options on and off, then enumerates the option areas. It also distinguishes this from publish_catalog by noting that `published: true` here does not render a PDF, while publish_catalog does both.

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 routes agents to alternatives: publish_catalog for publishing plus PDF rendering, and open_publish_settings for entering the password via a form rather than through chat. It also states the confirmation requirement when publishing a draft, which is a key conditional before calling.

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

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

Annotations already mark it read-only, non-destructive and closed-world; the description adds useful context: it opens a dashboard beside the chat, the merchant can switch period and open a catalog in the panel, and a plan with analytics is required. It does not describe error behavior or data freshness, but with annotations and an output schema it provides substantial 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?

Front-loaded with the verb and resource, then the content, prerequisite and alternative. It is dense and somewhat long, but each clause (catalog mode, panel interaction, plan requirement, alternative tool) carries useful selection 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?

Complete enough for a read-only dashboard tool: content, scope, prerequisite and alternative are present, and the output schema covers return values. No essential calling detail is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantics for catalogId: it changes the output to that catalog's top products, most viewed pages, live visitors and collected leads, not merely a filter. It also reinforces the period parameter by noting that the merchant can switch periods in the panel.

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?

Opens a specific resource ('analytics as a dashboard') and enumerates the views, visitors, clicks, top catalogs, referrers, countries and devices, so the agent knows exactly what appears. It explicitly separates overview mode from catalog-scoped mode and names get_analytics as the adjacent 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?

States the situation ('when they want to see how things are going') and the alternative for a specific numeric question ('get_analytics'). It also adds the prerequisite ('Needs a plan with analytics'), leaving little ambiguity about when 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?

The description provides crucial operational behavior beyond the annotations, noting the batch limit ('One fetch per product, so up to 200 products per call') and explaining the mechanism of truncation and subsequent calls. It also clarifies that field edits are kept or overwritten based on the `keepEdits` parameter.

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

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

The description is dense and highly efficient, but its length is necessary to cover all its complex operational aspects (sync types, pagination, state preservation). Each part of the text is essential.

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 complexity of the operation—handling different sync scopes, manual user edits, and batch processing—the description is exceptionally complete. It anticipates agent questions regarding data preservation and technical limitations.

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?

While the schema is 100% covered, the description adds significant semantic value for every parameter. For 'what', it explicitly defines 'all', 'prices', and 'images'; for 'productIds', it explains the source of the IDs; and for 'keepEdits', it describes the functional consequences of the boolean value.

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

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

The description clearly identifies the resource (catalog's products) and the action (fetch and update tiles). It differentiates this operation from basic updates (like update_product) by focusing on refreshing data from the 'store'.

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

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

It provides comprehensive usage guidelines by defining how to scope the sync ('what' options: all, prices, images) and which specific items to target (productIds). It also details the critical logic for preserving user input via the keepEdits flag.

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?

Given annotations already flag destructiveHint=true and idempotentHint=true, the description adds the crucial nuance the annotations cannot: partial-update semantics ('Only what is given changes'), per-style merge for typography, and whole-palette replacement for brandColors. That distinguishes merge from overwrite, which is the real risk here. It stops short of stating any permission/auth requirement or confirming that palette replacement is irreversible.

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?

Front-loaded with the resource being changed, then merge semantics, then sibling routing — a sensible order with no filler sentences. It is somewhat dense in one block, and the parenthetical listing of typography attributes (font family, px, weight, line height, colour, case) duplicates schema detail that the agent will read anyway.

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 nested mutation tool with 100% schema coverage, full annotations, and an output schema, nothing needed to call it correctly is missing: scope, merge-vs-replace behavior, read-back source, and sibling boundaries are all covered.

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 schema already carries the heavy lifting — including the per-style merge note and the 'replaces the current one' note for brandColors, plus priceFormat examples. The description's enumeration of typography properties and presets largely restates that, so it adds only marginal parameter meaning beyond the structured fields.

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 resource ('the catalog's own settings') and enumerates the exact surfaces it covers — title, page size presets/custom dimensions, priceFormat, brand palette, and typography for body plus h1–h4. It explicitly separates itself from edit_catalog (page content) and set_publish_options (publishing), so an agent can pick the right tool from siblings without opening schemas.

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

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

It names two sibling alternatives verbatim and the boundary condition that selects each ('Page content is edit_catalog; publishing is set_publish_options'). It also routes the agent to get_catalog to read current values under `design`, giving the read-modify-write pattern explicitly.

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

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

Goes well beyond the annotations: it explains why destructiveHint is true (list fields are replaced whole; `variants: []` removes variants), states that the tool is a partial update so unspecified fields survive, and discloses precondition failure behavior — a store-backed product is rejected and the answer says so. This is exactly the context an agent needs before a destructive write.

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?

Front-loaded with purpose and object, with the critical preconditions in the middle and the id hint last — a logical order. The parenthetical asides and dash clauses pack a lot per sentence and reward a careful second read, so it is dense rather than wasteful.

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 nested objects, destructive semantics, and an existing output schema, the description covers everything an agent needs: which products qualify, what gets overwritten, how to do a partial update, how variants are cleared, and how to supply the id. Return values are correctly left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `productId` accepts either the id that search_products reports or the sku, and `fields` should contain only the delta rather than a full object. It doesn't add cardinality or validation detail beyond the schema, which already documents options/variants replacement.

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 ("Change a product the merchant keeps in Foldsquare") and enumerates exactly which attributes are editable, so the scope is unambiguous. It also names what it is not: store-sourced products edited in the store or via edit_catalog's editProduct, distinguishing it from the two nearest 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?

Explicit when-to-use (merchant-kept products, imported or hand-added), when-not (products originating from the connected store), and the alternatives (the store itself, or edit_catalog's editProduct per catalog). It also gives the partial-update rule, "Give only the fields to change," which is the key calling convention.

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

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

Annotations already cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new behavior: server-side re-hosting with resized variants, supported formats, a 20 MB ceiling, and deduplication ('lands once'). It does not mention auth or rate limits, but that is a minor remaining gap against the annotation coverage.

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 dense sentences, front-loaded with the action and its outcome, followed by input rules and constraints. Every clause carries information; the parenthetical list of edit_catalog call sites is directly actionable rather than 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?

With an output schema covering the return value and full annotation coverage, the description supplies exactly what structured fields cannot: re-hosting behavior, dedupe semantics, format/size limits, input modality choice, and downstream consumption points. Nothing an agent needs to invoke this 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?

Schema coverage is 100%, so the baseline is 3, but the description earns more: it clarifies that 'url' is fetched and copied and must be publicly reachable, that 'base64' pairs with 'contentType', and it states the format and size constraints. It also implies the url/base64 mutual exclusivity that the schema itself does not enforce via oneOf.

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

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

The description opens with a precise verb and resource ('Put an image into the merchant's image library') and immediately adds the material outcome: re-hosting, resized variants, and a returned URL. It also names the downstream tools where the URL is consumed, so it is unmistakable against siblings like list_images.

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 explains the two input paths ('Give either url ... or base64 with its contentType') and where the resulting URL is used (edit_catalog/addBlock, editBlock, editProduct). What's missing is an explicit exclusion or a pointer to list_images when the agent merely wants to see existing images.

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

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

Annotations already declare readOnlyHint, destructiveHint false, and openWorldHint false. The description adds useful behavior beyond that: it is free, writes nothing, returns every problem addressed by JSON path, and produces actionable diagnostics.

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

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

The description is front-loaded and efficient: it leads with the dry-run action and side-effect guarantee, then gives schema references and the create_catalog routing. A phrase or two could be trimmed, but no sentence is wasted.

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

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

Given the single required document parameter, output schema, and annotations, the description is complete enough for an agent to call it correctly. It covers the side-effect profile, output value, diagnostic quality, schema references, cost, and when to use 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds valuable meaning by pointing to foldsquare://schemas/catalog-dsl.json for the grammar and foldsquare://schemas/product-fields.json for field IDs.

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: dry-run a catalog DSL document, compile and lint it, write nothing. It clearly distinguishes validation from mutation and explicitly routes non-trivial work before create_catalog.

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

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

It gives clear usage context: use it for anything non-trivial before create_catalog, because it returns the would-be output plus fixable issues. It doesn't explicitly cover when not to use it, but the intended workflow is clear.

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