Gelato MCP by usefulapi

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds real value beyond that: the production-state precondition, the concrete failure mode (HTTP 409), and explicit irreversibility ("cannot be undone"). It does not describe the response payload, but with annotations carrying the safety semantics this is solid 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 short sentences: action, failure precondition, irreversibility. The most decision-relevant fact (must be before production) is front-loaded and nothing is wasted.

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

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

For a single-parameter mutation with no output schema, the description covers the key decision inputs: timing window, failure behavior, and irreversibility. Only the exhausted-state note (what happens to an already-cancelled order, given idempotentHint) is left unaddressed.

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

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

Schema description coverage is 100% for the single order_id parameter, so the schema already documents the input fully. The description adds no parameter-level detail (no id format, source of the id, or overrides) beyond the endpoint path, so the baseline of 3 applies.

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

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

States a specific verb and resource ("Cancel an order") and adds the scope constraint "before production," which separates it from siblings like gelato_delete_draft_order and gelato_create_order. 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 a clear precondition for use (before production) and the exact condition under which the call fails (HTTP 409 once any item is printed or shipped). It does not explicitly name an alternative tool or say when another sibling should be preferred, so it falls short of a full when/when-not mapping.

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=true, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: the supported stock regions, the full set of possible status values, and that 'out-of-stock-replenishable' comes with a replenishment date. It stops short of describing response shape, ordering, or partial-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?

Two dense, front-loaded sentences with no filler; the status enumeration is the load-bearing content and comes first. Including the raw endpoint path 'POST /v3/stock/region-availability' is the only element of questionable value to an agent, but it is a single clause.

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

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

With no output schema, the description partially carries the return-value burden by enumerating possible statuses and noting the replenishment date, and it names the batching limit range via the schema. It still omits how results map to the input UIDs and what happens on invalid/non-stockable UIDs, but for a single-parameter read tool it is largely complete.

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

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

Schema description coverage is 100% (product_uids: 'Gelato product UID.' with bounds 1-250), so the schema fully documents the sole parameter. The description adds no syntax, format, or UID-source guidance, 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+resource ('Stock status of stockable products per stock region') and enumerates the exact outcome taxonomy (in-stock, out-of-stock-replenishable, out-of-stock, non-stockable, not-supported), so an agent knows precisely what the call returns. No sibling tool touches inventory, so it is trivially distinguishable from the order/product/pricing siblings.

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

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

The description says what the tool reports but never when to call it (e.g., before create_order/quote_order to avoid unfulfillable items) nor what alternatives exist. No prerequisites, no exclusions, no workflow context — the agent must infer the use case entirely.

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

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

The annotations only flag destructiveHint=true and idempotentHint=false; the description converts that into concrete consequences — nothing is produced or charged in draft mode, and production plus an immediate account charge happen when order_type is "order". That is exactly the "what actually happens" context an agent needs before invoking a destructive, non-idempotent 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?

Three tight sentences: purpose first, then the mode/consequence distinction, then the shipment-method rule plus endpoint. No filler, and the most consequential fact (draft-by-default, no charge) is front-loaded.

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

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

For an 8-parameter write tool with nested objects and no output schema, the description covers the behavioral essentials but omits what the call returns — notably how the agent obtains the created order/draft id it needs to feed into gelato_submit_draft_order. Since there is no output schema, that gap is on the description to close.

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 every parameter, including the shipmentMethodUid values/default and the order_type meanings. The description restates those same facts (shipment method resolution, default = cheapest) without adding format or edge-case detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource ("Create an order") and immediately differentiates the two modes it supports: draft (default) versus order_type "order". It also names the sibling tools involved downstream (gelato_submit_draft_order, gelato_quote_order), so an agent can distinguish this from submit_draft_order without opening either 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 context for the main branching decision: default draft produces/charges nothing, while order_type "order" starts production and charges immediately. It also tells the agent where a shipmentMethodUid comes from (gelato_quote_order) and what omission means (cheapest). It stops short of explicit when-not-to-use guidance (e.g., use submit_draft_order for existing drafts, or avoiding duplicate creation).

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

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

Annotations already flag a destructive, non-idempotent, open-world write. The description earns credit by adding behavior annotations do not carry: publishing of variants and mockups happens asynchronously in the background and must be polled via gelato_get_store_product, and the product is hidden from the online store unless visible_in_online_store is true. It does not say what happens to existing store content or whether retries duplicate products.

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: creation semantics first, then the asynchronous side effect with its tracking tool, then the visibility default, then the endpoint. No filler and every clause 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 a 10-parameter async write with no output schema, the description covers what is created, what happens after the call, how to observe progress, and the default visibility state. Nothing an agent needs to invoke 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%, so the schema already documents all ten parameters, including the visible_in_online_store default and placeholder naming. The description restates the placeholder-image mapping and the hidden-by-default behavior, adding only marginal meaning beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb+resource+source: 'Create a product in a connected store from a template, with your own images in the template's placeholders.' It also names the concrete endpoint, letting an agent distinguish it from gelato_create_order and gelato_submit_draft_order 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 clear context: use this when creating a store product from a template and supplying your own images for the template placeholders, and it routes the agent to gelato_get_store_product for tracking. It never explicitly excludes or contrasts with a non-template create path, so it stops short of a full when/when-not statement.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: the deletion is permanent and only applies to draft orders, which is a real behavioral constraint not encoded in the structured fields.

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

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

A single compact sentence front-loads the action and the critical scope limitation, followed by the endpoint reference. Every clause earns its place 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?

For a single-parameter destructive tool with no output schema, the description covers action, scope, and alternative path adequately. It could mention what happens on failure (e.g., order not in draft state), but nothing essential 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 description coverage is 100%, so the order_id parameter is already documented as 'Gelato order id of a draft order.' The description adds only the path placeholder {orderId} and no format or constraint detail beyond the schema, so 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 ('Permanently delete a DRAFT order') with an explicit scope restriction, and adds the raw endpoint for traceability. It clearly separates this from the sibling gelato_cancel_order by stating regular orders cannot be deleted.

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

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

Provides an explicit when-not clause ('regular orders cannot be deleted; cancel them instead'), which routes the agent away from this tool for non-draft orders. It stops short of naming the sibling tool gelato_cancel_order directly, but the alternative action is unambiguous.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this is a GET /v3/catalogs/{catalogUid} call and that the output is an attribute/value map, which is useful context on the response shape, but there is no mention of auth needs, rate limits, or error behavior.

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

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

Two tight sentences: the payload description comes first, the downstream use second, with a compact endpoint reference at the end. Every element earns its place, though the raw REST path is marginally redundant for an agent-level 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 no output schema, the description carries the burden of describing the return value, and it does: a catalog plus its defining attributes and each attribute's possible values. The only gap is that it doesn't say how many attributes or whether the response is a single object, but this is minor for a one-parameter read.

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

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

Schema description coverage is 100% and the single parameter's schema already documents its format and origin ('posters', from gelato_list_catalogs). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

The description states a specific resource (a single catalog and the attributes/values that define its products), which clearly separates it from the plural gelato_list_catalogs sibling. The verb is implicit rather than stated as a leading imperative, but 'One catalog with the attributes...' leaves no ambiguity about what is returned.

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

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

It gives a concrete downstream use: take these attributes and pass them as attribute_filters to gelato_search_products. That is genuine when/how guidance. It does not, however, state when NOT to use it or contrast explicitly with gelato_list_catalogs beyond the singular/plural implication.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful return-side context (millimetre units, which layout areas are produced) but says nothing about failure modes such as an invalid product_uid or a page_count outside validPageCounts.

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

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

A single front-loaded sentence delivers the resource, the unit and the returned areas, followed by the REST path. Nothing is padded, though the endpoint path duplicates information already conveyed by the name and adds marginal value for an MCP caller.

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?

There is no output schema, so the description must carry the return-value burden, and it does so by naming the layout areas and the millimetre unit. Dimensional semantics (e.g. whether bleed is included per side, how wraparound relates to front+spine+back) and error behavior remain unstated, leaving a small gap.

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

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

Schema description coverage is 100%, so both product_uid and page_count are already documented, including the cross-reference to validPageCounts in gelato_get_product. The description adds no per-parameter syntax or unit interpretation beyond the general millimetre note. Baseline 3 applies when the schema does the heavy lifting.

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

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

Names a specific resource (cover dimensions of a multi-page product) and enumerates exactly what is returned: spine, front, back, bleed and wraparound areas, with units. No sibling tool covers cover layout, so an agent can distinguish it immediately 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?

"for designing the cover file" implies the downstream use case and it names multi-page products (photo book, brochure) as the applicable input class, which implicitly excludes single-page/simple products. However there is no explicit when-to-use statement, no prerequisites (e.g. that product_uid must come from gelato_get_product), and no named alternative.

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=true, so the safety profile is fully covered. The description adds the return shape (fields returned), which is useful, but says nothing about rate limits, auth scope, or error behavior for missing orders.

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

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

One dense sentence that front-loads the resource and scope, followed by a short endpoint reference. 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?

No output schema exists, and the description compensates by enumerating the returned fields (type, statuses, items/files, shipment/tracking, address, receipts/totals), which an agent needs to plan parsing. Missing only edge-case behavior (not-found, draft vs order semantics) for a 5.

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

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

Schema description coverage is 100% and the schema documents the order_id pattern, length bounds, and source (gelato_search_orders). The description adds the conceptual 'type (order/draft)' note but that describes the response, not the parameter. Baseline 4 for a 1-param tool with fully documented 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 ('One order by Gelato order id') and enumerates the exact fields returned (type, statuses, items, shipments, address, receipts, totals). The API path GET /v4/orders/{orderId} removes any ambiguity about scope versus siblings like gelato_search_orders.

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 schema description of order_id says '(from gelato_search_orders)', which implicitly routes the agent to search first. It doesn't explicitly say when to prefer this over search_orders, but single-id retrieval vs. search is clear enough from the text.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful payload scope (unsupported countries are returned, page counts only for multi-page products), which is genuine context beyond annotations, but it discloses nothing about lookup misses, caching, or error behavior for an unknown UID.

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

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

A single sentence enumerating payload contents followed by the endpoint route. It is front-loaded with the resource and every clause carries information; nothing is padded.

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

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

For a one-parameter read-only lookup with full schema coverage and no output schema, the description covers what comes back and how to obtain the UID. It is nearly complete; the only gap is how failures (invalid or stale UID) surface, which is minor for a GET.

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

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

Schema description coverage is 100% and the schema already documents product_uid with its pattern and length bounds, plus points back to gelato_search_products. The description does add the framing that the UID identifies a catalog product, but adds no format or sourcing detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (get) and resource (one catalog product by productUid), and enumerates what the payload includes: attributes, weight, supported/unsupported countries, printable/stockable flags, valid page counts. This distinguishes it from gelato_search_products (search) and gelato_get_store_product (store-scoped product), so an agent can route without opening either 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?

Usage is implied: the single required parameter note '(from gelato_search_products)' hints at the discovery-then-fetch flow. But there is no explicit when-to-use versus gelato_get_store_product or gelato_get_product_prices, and no statement that this is a read-only lookup versus a write path.

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 and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful scope context — that figures exclude shipping and cover every quantity tier — but says nothing about pagination, rate limits, or auth. That is adequate but not rich.

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

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

Three short sentences with zero filler; the core purpose and the shipping exclusion are front-loaded, and the path 'GET /v3/products/{productUid}/prices' is appended without crowding. Every sentence contributes.

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

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

With no output schema, the description carries the burden of explaining returns, and 'production prices for every quantity tier' plus the shipping exclusion gives the agent a usable mental model of the response. It does not cover error cases or empty results, so it is not fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a conditional requirement the schema's required list does not capture: page_count is needed only for multi-page products. That meaningfully improves correct invocation of a parameter the schema marks as optional.

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 ('Gelato's production prices of a product'), plus the scope ('for every quantity tier, optionally for one destination country and currency'), so an agent knows exactly what comes back. It also names the sibling it is not — 'Shipping is not included (use gelato_quote_order)' — which cleanly separates it from the quote 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?

Explicitly routes the agent to gelato_quote_order when shipping-inclusive pricing is needed, and flags the conditional prerequisite that page_count is required for multi-page products. It stops short of stating when-not-to-use cases beyond the shipping distinction, so it is strong 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered; the description adds genuine value by disclosing the response surface (variants carrying productUid and external ids, publishing state) in the absence of an output schema. It stops short of auth needs, rate limits, or 404/not-found behavior, but the added context is real rather than redundant.

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

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

Two compact sentences: the payload list comes first, then the REST route. Every clause is informative; the endpoint string is marginally redundant with the title but useful for mapping to the underlying API.

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

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

With no output schema, the field enumeration is what makes this definition adequate for an agent that needs to know what comes back, and annotations plus a fully described two-parameter schema cover the rest. Only error/traversal behavior and explicit sibling routing are 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 carry patterns, length bounds, and a cross-reference to gelato_list_store_products. The description adds no parameter-level meaning (productUid/external ids refer to the response, not the inputs), so the schema does the work and 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+resource (fetch one product of a connected store) and enumerates the returned surface (title, description, status, variants, options, preview, publishing state), which separates it from the sibling gelato_list_store_products and from the catalog-level gelato_get_product. It never names those siblings outright, so differentiation is implied by 'connected store' rather than stated.

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: retrieve a single store product given a store_id/product_id pair, which the schema pins to gelato_list_store_products. There is no explicit when-to-use versus gelato_get_product or when-not guidance, and no mention that both ids are mandatory prerequisites.

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 and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by enumerating the returned structure (title, description, preview, variants, image placeholders) and linking those fields to downstream tool parameters, though it says nothing about failure modes or auth.

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?

It is a single dense sentence with no filler, and the endpoint is front-loaded at the end as a quick anchor. The clause stacking (variants, then placeholders, then a nested cross-tool instruction) makes it slightly harder to parse than it needs to be, but nothing is wasted.

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

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

With no output schema, the description must convey the return shape, and it does so reasonably: template fields, variants with their ids, and image placeholders. A single-id read tool with full schema coverage and annotations is nearly complete, though a note on what happens for an unknown or unauthorized template id 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 the single parameter is documented there (dashboard URL origin, pattern, length bounds), so the schema carries the burden. The description's 'pass the variant id as template_variant_id' concerns a different tool's input, not this tool's template_id, so it adds little parameter meaning 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 identifies the resource (a Gelato dashboard product template) and implicitly the operation via the GET /v1/templates/{templateId} endpoint, and it distinguishes itself from siblings by naming gelato_create_product_from_template as the consumer. It never states a crisp verb like 'retrieve', so the purpose is clear but slightly inferential.

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 useful workflow routing: variant ids are to be passed as template_variant_id and placeholder names filled in via gelato_create_product_from_template. However, it never says when to call this tool versus alternatives like gelato_get_product or gelato_list_store_products, and gives no preconditions beyond the id's origin.

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, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the endpoint URL and the returned identifier fields, but says nothing about pagination, result size, or rate limits. With annotations carrying the safety burden, this is adequate but not rich.

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

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

Two tight sentences with the core action and scope front-loaded, followed by the practical 'start here' guidance and the raw endpoint. Nothing is redundant, though the endpoint URL is marginal value for an agent choosing a tool.

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

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

For a zero-parameter read tool with no output schema, the description covers what it returns (catalogUid, title) and when to use it. The main omission is the shape/size of the result set and whether pagination applies.

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

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

The tool takes zero parameters, which is the baseline-4 case since there is nothing for the description to disambiguate. The mention of catalogUid and title describes outputs rather than inputs, so no additional parameter meaning is needed or missing.

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?

Names a specific verb and resource ('List Gelato's product catalogs'), illustrates the scope with concrete catalog types (posters, cards, t-shirts, mugs, photo books), and states the identifying fields returned (catalogUid, title). It does not explicitly contrast itself with the singular sibling gelato_get_catalog, relying on the list/get naming distinction instead.

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?

'Start here to find products' gives a clear entry-point cue for when to reach for this tool. It stops short of naming alternatives or exclusions, so an agent must infer that gelato_get_catalog or gelato_search_products handle narrower lookups.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the concrete endpoint (GET shipment.gelatoapis.com/v1/shipment-methods) and the shape of each returned record, including the normal/express/pallet type values.

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 core purpose and return-field list are front-loaded in a single clause, with the endpoint appended last. Slightly dense parenthetical packaging, 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?

With no output schema, the definition compensates by enumerating the returned fields and the type enum values, which is enough for an agent to use the result. It stops short of describing pagination or ordering, but for a small read-only lookup that is a minor gap.

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

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

Schema coverage is 100% and the single parameter is fully documented with its ISO pattern, so the baseline is 3. The description restates the country filter's effect ('only those for one destination country') but adds no syntax or format detail 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?

States a specific verb and resource ('Gelato's shipment methods') and enumerates the fields returned (shipmentMethodUid, name, type, tracking, business/private, supported countries), so an agent immediately knows what it gets back. No sibling tool covers shipment methods, so it is trivially distinguishable from the order/product/catalog tools.

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

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

The phrase 'optionally only those for one destination country' implies when to pass the country filter, but there is no explicit when-to-call guidance, no prerequisite statement, and no named alternative. Usage is inferable 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context by enumerating returned fields and the status enum values (created/publishing/publishing_error/active) and the REST endpoint, but says nothing about pagination behavior despite limit/offset params.

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 and its returned fields, followed by a targeted sentence about locating store_id. Efficient, though the long first sentence packs many return fields without much 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?

With read-only annotations, a complete input schema, and no output schema, the description usefully fills the return-value gap by listing the fields produced. The main missing piece is pagination guidance, which is notable given the limit/offset pattern.

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 limit, offset, order, and order_by are fully documented in the schema. The description adds one genuine hint beyond the schema: where to find store_id (dashboard URL or on orders). Baseline 3 is appropriate since the schema does the heavy lifting and only store_id gets extra context.

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 (list) and resource (products of a connected e-commerce store), and enumerates what is returned (id, title, status, external id, variants, preview images, dates). It is clear, but it does not explicitly distinguish itself from close siblings like gelato_get_store_product or gelato_search_products.

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 never says when to use this tool versus alternatives such as gelato_get_store_product (single product) or gelato_search_products. There is no when-to-use, when-not, or prerequisite guidance beyond the existence of store_id.

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 and destructiveHint=false; the description reinforces this with 'Nothing is created or charged', which is the key behavioral reassurance for an agent deciding whether a quote is side-effect free. It also discloses the shape of the returned data (per-facility quotes, delivery day ranges), adding value beyond the annotation set. No auth or rate-limit context is given.

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

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

Two tight sentences plus the endpoint path. The core purpose and the no-charge guarantee are front-loaded, and the create_order handoff is placed last where it is most actionable. 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?

With no output schema, the description usefully compensates by describing the return payload (prices and shipment methods with uid, price, min/max delivery days and dates, per facility) and the read-only nature. It is close to complete; only edge behaviors such as the effect of allow_multiple_quotes on the response are left to 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% and the nested product/recipient objects are thoroughly documented in the schema, so the baseline is 3. The description mentions no input parameter semantics of its own (currency, allow_multiple_quotes, recipient fields are all explained only in the schema), so it adds nothing beyond structured data.

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 ('Price an order before placing it') and enumerates exactly what the response contains: product prices and shipment methods with shipmentMethodUid, price and delivery days per fulfillment facility. This clearly separates it from siblings like gelato_create_order (which actually places the order) and gelato_list_shipment_methods (which is not address-specific).

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 frames the tool as a pre-purchase step ('before placing it', 'Nothing is created or charged') and gives a concrete handoff: 'Pass a returned shipmentMethodUid to gelato_create_order.' It does not state any exclusions (e.g. when to prefer gelato_get_product_prices instead), so it stops just short of full when/when-not coverage.

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 and openWorldHint=true, so the safety profile is covered. The description adds real value beyond them by disclosing the sort order (newest first) and the underlying endpoint (POST /v4/orders:search), but says nothing about pagination behavior even though the schema exposes next_offset-based paging.

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 dense but well-structured sentences: the result fields come first, then the filter set, then the endpoint. It is appropriately sized for a 14-parameter tool, though the field enumeration is somewhat list-heavy.

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 14-parameter search with no output schema, the description helpfully enumerates the returned fields (id, references, statuses, channel, store, country, currency, totals, dates), which compensates for the absent output schema. Pagination semantics live in the schema and are not reiterated, which is a minor gap.

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

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

Schema description coverage is 100%, so every one of the 14 parameters is already documented in the schema itself. The description's filter list and the free-text note (recipient name or order reference) largely restate that, adding no syntax or format detail 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?

States a specific verb (search) and resource (orders and drafts) and enumerates the visible fields, so an agent can immediately distinguish this from the sibling gelato_get_order (single-order lookup) and gelato_create_order. The scope and result shape are front-loaded.

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

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

The description clearly frames this as a filtered-list operation and names every available filter dimension, giving strong context for when to reach for it. It does not, however, explicitly contrast with alternatives such as gelato_get_order for a known id, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint, so safety is covered. The description still adds real value by disclosing the POST transport and, importantly, the shape of the returned payload (productUid, attributes, weight, dimensions, per-value hit counts) in the absence of an output 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?

One dense sentence with the main action front-loaded, followed by the endpoint for precision. Every clause contributes, though the concatenated list of return fields makes it slightly heavy for a single sentence.

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

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

With no output schema, the description compensates by naming the returned fields and the per-value hit counts, and the schema handles pagination and filter syntax. Cross-references to gelato_get_catalog for attribute names live in the schema rather than the description, a minor gap.

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

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

Schema description coverage is 100%, so limit, offset, catalog_uid, and attribute_filters are already documented at the property level, including the cross-reference to gelato_get_catalog. The description only restates that filtering is by attribute values, adding nothing the schema lacks. Baseline 3.

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

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

States a specific verb and resource ('List the products of a catalog'), scopes it with an optional filter, and enumerates what each result carries. The scope ('catalog products') cleanly separates it from gelato_get_product (single) and gelato_list_store_products (store listings).

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

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

The description implies usage through 'optionally filtered by attribute values' and the HTTP route, but never states when to choose this over gelato_list_store_products, gelato_get_product, or gelato_check_stock, nor any prerequisite. Usage is inferable but not guided.

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 two most consequential effects: Gelato starts production and the account gets charged, plus the constraint that only drafts qualify. This is exactly the extra context an agent needs since annotations only give abstract hints (destructiveHint, openWorldHint). It also notes items stay unchanged.

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 tight sentences, front-loaded with the core action and its side effects (production, charge) before the constraint and the API endpoint detail. 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?

For a single-parameter mutation tool with no output schema, the description covers the action, the trigger condition, the financial and production consequences, and the underlying request. Everything needed to call it safely is present.

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

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

Schema description coverage is 100% and the single order_id param is fully documented with its pattern, length bounds, and that it must be a draft order id. The description adds the draft constraint context but no syntax or format detail beyond the schema, so baseline 3 is appropriate.

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

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

States a precise verb ('Convert a DRAFT order into a regular order') and resource, and distinguishes it from the siblings gelato_create_order (creates) and gelato_delete_draft_order (removes drafts) by making clear this finalizes an existing draft rather than creating or deleting anything.

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

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

Provides a clear precondition ('Only drafts can be submitted') that tells the agent when this tool applies versus the create/delete draft siblings. It does not explicitly name the alternative tools to use for non-draft orders, but the precondition does most of the routing work.

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