Pridly — AI copilot for PrestaShop

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

Beyond the destructiveHint and openWorldHint annotations, it explains that only listed languages change while other languages keep their text, that a preview/confirm workflow is required, that preview_id is needed for confirmation, and that apply_at supports scheduled changes. This is strong behavioral context for a mutation tool.

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

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

The description is dense but front-loaded: it opens with the core purpose, then layers in language behavior, prerequisites, preview/confirmation, plan constraints, and scheduling. Every sentence maps to an agent decision or user-safety requirement.

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 multilingual mutation with no output schema, the description covers the necessary workflow: prerequisites, preview behavior, explicit approval, confirmation mechanics, plan limitations, and scheduled application. Item limits and field constraints are left to the schema, which is appropriate.

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 already 80%, so the baseline is 3. The description adds useful meaning beyond the schema by explaining the translations object with an example, the language-only update behavior, and the confirm/preview_id/apply_at workflow semantics.

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

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

The description uses a specific verb and resource: it saves product names, descriptions, short descriptions, and SEO text across one or more languages. It clearly distinguishes the tool from broader update tools by emphasizing multilingual product content and the translations 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?

The description gives explicit workflow guidance: call get_brand_voice first, use translation_gaps to find missing text, preview before confirming, show the preview to the user, get explicit approval, and only then call again with confirm=true. It also states the paid-plan restriction and how to schedule later with apply_at.

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 real context beyond the annotations: it scopes the blast radius (no store data affected) and explains why no rollback is needed. That meaningfully informs the agent beyond destructiveHint=true and openWorldHint=true. It stops short of saying whether a cancelled change can be re-scheduled and whether failures (e.g., change already ran) surface as errors.

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 action and its precondition, then the consequence. Nothing is repeated and nothing padding-like is present.

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

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

For a two-parameter cancellation tool with annotations and no output schema, the description covers precondition, effect, and non-effect on store data. Minor gaps remain: no statement of the outcome/error on an already-executed change and no confirmation/irreversibility note about recreating the schedule.

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% – both 'id' (with its pointer to list_scheduled_changes) and 'store' are documented in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ('Cancels a change') plus a scope qualifier ('that hasn't run yet'), which is enough to distinguish it from undo_change in practice. It never names the sibling explicitly, so an agent must infer the boundary from the 'hasn't run yet' clause.

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 precondition ('hasn't run yet') is stated and the 'nothing to undo' remark implicitly points at undo_change as the alternative for changes that already ran. However, there is no explicit when-to-use statement, no mention of using list_scheduled_changes to obtain the id, and no guidance on what to do if the change already executed.

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 safety is covered structurally. The description adds the valuable fact that ids feed undo_change, but it says nothing about ordering, recency window, or whether results are paginated.

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

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

A single efficient sentence with the core purpose front-loaded. Nothing is wasted, though it is terse to the point of omitting useful scope details.

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

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

For a simple read-only list with no required parameters and no output schema, the description covers purpose and downstream chaining. It leaves gaps around what 'recent' means and how the limit parameter behaves, which the schema alone does not clarify.

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

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

Schema description coverage is only 50%: 'store' is documented in the schema while 'limit' is not. The description adds no parameter meaning at all, so it fails to compensate for the undocumented limit parameter (default 20, max 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?

States a specific verb ('Lists') and resource ('recent changes Pridly made to the user's stores') and clarifies that returned ids are the ones undo_change accepts. That is clear enough to distinguish it from sibling list tools like list_scheduled_changes, though it does not explicitly contrast them.

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 clause about undo_change implicitly tells an agent to call this before undo_change to obtain valid ids, which is useful chaining guidance. However, there is no explicit when/when-not guidance versus related siblings such as list_scheduled_changes or compare_periods.

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 that this is a safe read-only operation. The description adds meaningful behavioral detail beyond the annotations: the exact metrics compared and the implicit comparison-with-preceding-period behavior when period_b is 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?

Two tightly written sentences. The core comparison behavior is front-loaded, and the fallback condition follows naturally with no wasted words.

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

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

For a read-only reporting tool with complete schema coverage and no output schema, the description provides enough context: it identifies the comparison dimensions and the default behavior. It could be slightly more complete by clarifying return shape or how this differs from other reporting tools.

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 all three parameters thoroughly, including formats and defaults. The description reinforces the period_b default, but adds little parameter semantics 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 verb and resource: compares two periods side by side and names the metrics compared. It is clear what the tool does, but it does not explicitly distinguish itself from related siblings like get_sales_summary or multi_store_report.

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

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

It explains the fallback behavior when period_b is empty, which is useful contextual guidance. However, it gives no explicit guidance on when to use this tool instead of alternatives such as get_sales_summary or sales_forecast.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is free to add the two-phase commit behavior, the preview_id handshake, the paid-plan requirement, and the 5-minute-to-90-day window for apply_at. That is meaningful non-obvious behavior. It stops short of saying whether an existing code is rejected or overwritten, which matters for a creation tool.

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

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

Front-loaded with the core action and the required preview-confirm sequence, and every sentence carries operational content. The preview/confirm instruction is stated twice in slightly different words ('Preview first, then confirm' and 'Always show the preview...'), which is minor redundancy rather than bloat.

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 11-parameter mutation tool with no output schema and zero required fields, this covers the workflow, prerequisites, and scheduling constraints well enough to call it correctly. Two gaps remain: nothing about what is returned after confirmation, and the phantom category-restriction mention.

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 45%, and the description compensates only partially: it explains the confirm/preview_id/apply_at workflow and discount shapes, but says nothing about code, amount, minimum_amount, or usage_limit_per_user semantics. It also references a 'category restriction' capability that has no corresponding parameter in the schema, which could mislead an agent into hunting for it.

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

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

Opens with a specific verb and resource ('Creates a coupon') and enumerates the supported shapes (percent or fixed amount, optional expiry, usage limits, category restriction). It does not name the close sibling set_product_discount, so the agent must infer the boundary between a coupon and a product discount.

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

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

Gives an explicit protocol: preview first, show the preview to the user, get explicit approval, then call again with confirm=true and preview_id. It also states the paid-plans-only prerequisite and the exact path for scheduling later via apply_at. This is when-to-use and how-to-sequence guidance at the top of the scale.

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

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

The annotations already declare this is a read-only, non-destructive, open-world tool, lowering the disclosure burden. The description adds useful behavioral context by noting the one-year lookback for new vs returning customers and that customer names are shortened for privacy, but it does not discuss limitations, permissions, or return format.

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

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

The description is a single concise sentence that front-loads the key metrics and includes the privacy note without waste. Every clause contributes useful 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 read-only analytics tool with rich annotations and fully documented parameters, the description adequately enumerates the data returned. It does not specify output shape or limits such as how many top customers are returned, but no output schema exists and the core purpose is clear.

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 store and period parameters are already fully documented in the schema. The description reinforces that results are for a period but adds no parameter-specific syntax or constraints 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 names a specific analytics resource and enumerates the customer metrics returned: counts, new vs returning, repeat-buyer rate, and top spenders. It is clear what the tool does, but it does not distinguish itself from siblings such as customer_segments or get_sales_summary.

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 no explicit guidance on when to use this tool versus alternatives, nor any exclusions. Usage is only implied by the metric names, which is weak given overlapping sibling tools such as customer_segments and get_sales_summary.

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 this a read-only, non-destructive, open-world tool, so the description is freed from covering safety. It adds genuinely new behavioral context: names are shortened and emails are never shown, which is important privacy information an agent would not otherwise know. It stops short of describing return shape or what happens when `segment` is 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?

Two sentences, front-loaded with the segment definitions, then the privacy note, then the `segment` usage hint. Every clause carries information and nothing is repeated from structured fields except where it clarifies the enum.

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, so the description must convey what a call returns. It implies a customer list when `segment` is passed, but never says what the default (no `segment`) response looks like — presumably per-segment counts — and never explains how `lookback_days` or `limit` affect results. For a read-only analytics tool this is adequate but not 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 only 25% (only `store` is documented). The description compensates partially by defining the meaning of each `segment` enum value (VIP top 10% by spend, lapsed 90+ days, etc.), which is real value beyond the bare enum list, and repeats the usage hint for `segment`. However, `lookback_days` (30–730, default 365) and `limit` (1–50, default 10) are completely unexplained in both schema and description, so half the parameters remain opaque.

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

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

The description clearly states the resource and the operation: it groups customers into named segments and defines the criteria for each (VIP top 10% by spend, new = first order in 30 days, lapsed = 90+ days without an order). That is strongly specific, but it never distinguishes this from the close sibling customer_insights, so an agent cannot tell the two apart from the text alone.

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 one concrete usage instruction ('Pass `segment` to list who is in one group'), which implies the default call returns aggregate segments. But it offers no when-to-use vs when-not guidance, no mention of customer_insights as an alternative, and no note on when to omit `segment`.

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 read-only, non-destructive and open-world, so the bar is lower. The description nonetheless discloses a non-obvious output behavior: customer names are truncated ('Anna K.') unless customer_email is supplied — useful, unguessable context that shapes how the agent interprets results.

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

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

Two sentences, filter capability front-loaded, alternative routing last. Nothing redundant with annotations or the name/title.

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 9-parameter search tool with no output schema and light annotations, the description covers what to filter on, the output-shape quirk, and where to go for details. Missing only secondary context: default ordering, how rows are paged beyond the limit param, and what fields a hit contains.

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 67%; min_total, max_total and customer_email are undocumented in the schema. The description compensates partly: 'amount' signals the min/max pair's purpose and the customer_email note explains a real effect of that unlabeled param. It still doesn't clarify amount units or inclusivity, or the schema's vague 'same formats as other tools' for period.

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 ('Finds') and resource ('orders') and enumerates the filter dimensions (status, date period, customer email, product, amount, age). It also names the sibling that handles the single-record case, so an agent can distinguish it from get_order and find_products without reading 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?

Explicitly routes the agent to get_order for full details of one order, which is the key alternative. It also gives the conditional that changes output shape ('unless you filter by customer_email'). No guidance on limits/paging or when multi-filter combinations should be avoided, so not a full 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful behavior about finding missing data and thin descriptions, but it does not describe pagination, return shape, or other operational details beyond the annotations.

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

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

The description is a single efficient sentence that front-loads the main search capability and then adds the special-case filters. Every phrase contributes to understanding what the tool can search for.

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

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

For a 12-parameter search tool with no output schema, the description covers the main filtering capabilities and special cases reasonably well. It does not clarify optionality, default limit behavior, result shape, or how multiple filters combine, leaving some gaps for an agent to infer from the schema.

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

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

With only 42% schema description coverage across 12 parameters, the description does substantial compensating work by mapping filters to name, SKU, category, tag, stock, price, and status, and by explaining special filters for missing data and max_description_words. It omits limit and store semantics, but those are already described in the schema.

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

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

The description states a specific verb and resource: searching products by name, SKU, category, tag, stock, price, or status, plus special missing-data and thin-description searches. It clearly identifies the tool's scope, though it does not explicitly distinguish it from nearby product-related siblings such as update_products or top_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?

Usage is implied by the search-oriented wording, and the mention of missing data and thin descriptions gives some contextual guidance. However, there are no explicit when-to-use or when-not-to-use instructions, and no alternatives are named.

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 one genuinely useful behavioral fact — omitting the name returns all presets — but says nothing about the shape or size of the returned preset list (e.g. whether styles include formatting rules or just prose guidance).

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: what it returns, when to call it, and the fallback behavior of the optional parameter. The purpose is front-loaded before the usage instruction.

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-optional-parameter read tool with no output schema, the description covers what is returned, when to reach for it, and the no-argument case. Missing only detail on the returned preset structure, which the absence of an output schema would otherwise make valuable.

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 0% and the single 'name' property has no description, so the description carries the full burden. It does so partially and effectively: 'With no name it returns all presets' communicates that the parameter is an optional filter rather than a selector, which is the key semantic. It does not say whether matching is exact or partial.

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 — 'Returns the user's saved writing styles (brand voice presets)' — and the parenthetical disambiguates what a 'brand voice' actually is. An agent can distinguish it from the sibling save_brand_voice purely on read-vs-write 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?

Explicit trigger given: 'Call this BEFORE writing product names, descriptions or SEO text, and follow the style.' That tells the agent both ordering and what to do with the result. It does not name a competing alternative or state a when-not condition, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value the annotations cannot: the exact set of fields returned, which matters because there is no output schema. It omits error behavior for an invalid order_id and any per-store scoping caveat, keeping it short of 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?

Two sentences, zero filler, with the payload contents front-loaded and the usage trigger trailing. Nothing could be cut without losing information.

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

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

For a simple two-parameter read tool with full schema coverage and annotations covering safety, the description supplies the one missing piece — the return contents. The only gap is the absence of any pointer to find_orders for the adjacent lookup case.

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 both parameters carry their own descriptions, including the 'leave empty if you have only one store' guidance for store. The description adds no parameter-level meaning 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?

States a specific verb+resource ('Full details of one order') and enumerates exactly what those details comprise (items, totals, status, customer, shipping address, notes), so the agent knows the payload shape before calling. It implicitly contrasts with the list-style sibling find_orders by scoping to 'one order', but never names that sibling 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?

'Use when the owner asks about a specific order' gives a real trigger condition, which is better than nothing. However, it never names find_orders as the alternative for browsing/searching multiple orders, and gives no exclusion for cases where the order id is unknown — the agent must infer the routing itself.

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 value by enumerating the metrics returned, but it does not disclose further behavioral details like permissions, rate limits, or response format. With annotations covering the core behavior, a 3 is appropriate.

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

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

Two sentences with zero waste: the first sentence lists the metrics front-loaded, and the second gives a clear usage context. The structure is efficient and appropriately sized.

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

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

The tool is simple with two parameters and no output schema. The description covers what is returned and when to use it, which is largely sufficient. It could be slightly more complete by noting that it returns a single summary (not a time series) or by mentioning sibling alternatives, but the essentials are present.

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

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

Schema description coverage is 100%, so the input schema fully documents both parameters (store address/id and period with examples and timezone note). The description does not add any parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description lists the specific metrics returned (revenue, orders, AOV, refunds, items sold, payment methods, order statuses) for a period, which clearly states what the tool does. It does not explicitly differentiate from siblings like compare_periods or multi_store_report, so a 4 is warranted.

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

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

The description provides a clear use case: 'Use for "how were sales this week/month?"', which gives context for when to call it. It does not mention when not to use it or name alternatives such as compare_periods, so it lacks explicit exclusions—a 4 rather than 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that results include both pending and recently-run entries, but says nothing about ordering, how many 'most recent' entries are returned, or whether results are capped/paginated.

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

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

A single, front-loaded sentence with no filler; the key fact (pending plus recent) comes first. Nothing wasteful is present.

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

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

With no output schema and no parameters, the description is the only explanation of return values, and it gives only a rough sketch. An agent cannot tell the result shape (fields, ordering, volume of 'recent' entries) or how this differs from change_history.

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, so the baseline is 4 and there is no parameter semantics to compensate for. The description does not need to explain inputs.

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 ('Lists changes') plus the two categories returned: pending and recently executed. It does not distinguish itself from the sibling change_history, which plausibly overlaps with 'the most recent ones that ran', so an agent cannot fully disambiguate from the description alone.

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 only implied by the content description; there is no explicit statement of when to call this versus change_history or the paired cancel_scheduled_change action. No prerequisites, exclusions, or alternatives are named.

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 safety is covered. The description adds useful context about scope and the returned fields (currency and status), but does not describe pagination, ordering, or any other behavioral detail.

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 sentence, front-loaded with the action and resource, with no wasted wording. It conveys the scope and return fields 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?

For a simple zero-parameter list operation with annotations covering safety, the description is nearly complete. It names the data source and returned fields, though it could mention ordering or whether results are ever paginated if the backend does so.

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

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

There are zero parameters, and the schema has no properties. The baseline for zero-parameter tools is 4; no additional parameter semantics are needed.

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 ('Lists') and resource ('PrestaShop stores connected to this Pridly account'), plus return fields currency and status. It is clear what the tool does, but it does not explicitly distinguish itself from related siblings like multi_store_report or store_health_check.

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

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

The description implies usage (when you need to see connected stores), but gives no explicit when-to-use guidance, no exclusions, and no alternatives. For a zero-parameter listing tool that may be sufficient, but the agent gets no routing help versus sibling reporting tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds one non-trivial behavior: only *published* products are reported, which narrows results in a way the annotations don't express. It says nothing about result ordering, row limits or pagination for a potentially long report.

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

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

A single front-loaded sentence with zero redundancy. The inclusion criteria and the threshold comparison both land before any elaboration.

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-optional-parameter read-only report with full schema coverage and annotations, this is nearly sufficient; no output schema exists so return values need not be explained. The only real gap is silence on result size/ordering for what could be a long inventory listing.

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

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

Schema description coverage is 100%, so both parameters (store, threshold) are already documented with defaults and bounds. The description's phrase 'at or below a threshold' reinforces the threshold semantics but adds no syntax or edge-case 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?

Names a specific verb (Lists) plus a precise resource scope: published products that are out of stock or at/below a threshold. That scope separates it from the product-search siblings like find_products and top_products, though no sibling is named 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?

There is no statement of when to reach for this tool versus find_products or multi_store_report, and no mention of prerequisites or the multi-store case. Usage must be inferred entirely from the name and the one-sentence purpose.

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

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

Annotations already cover the safety profile (readOnly, non-destructive), so the description earns credit for what they cannot say: the dependency on stored cost prices and the exclusion rule that cost-less products are dropped and tallied. The only omission is the return shape, which is not covered by 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?

Two sentences, no filler, and the output content leads before the prerequisites. Every clause carries information: what you get, what is required, and how missing data is treated.

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 three optional, fully documented parameters and no output schema, the description covers purpose, prerequisite and edge-case handling. The residual gap is that 'counted' implies an extra field in the response that an agent must discover at call time, since no output schema declares 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%, including the period enum values and the limit ceiling, so the schema already carries the parameter burden. The description only echoes 'in a period' and says nothing about how store, period or limit affect results, which matches the baseline for fully documented schemas.

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 exact metrics (revenue, cost, margin) and the exact grain (products sold in a period), which is more specific than the title and clearly distinct from revenue-only siblings like get_sales_summary or top_products. It stops short of naming the sibling it replaces, so an agent must infer the boundary itself.

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 states a real precondition: the shop must have cost prices in the 'Cost price' field, otherwise the tool is not useful. That is actionable context an agent can check before calling. It gives no explicit contrast with adjacent tools (top_products, compare_periods, multi_store_report), so the when-not guidance is incomplete.

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 real behavioral context beyond that: results are returned as one combined table, and currencies are never summed together, which tells the agent to expect per-currency rows rather than a single mixed total.

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, front-loaded with the output shape, followed by audience context and the currency caveat. Every sentence carries information, though 'also works with one store' borders on redundant with the schema's 'leave empty if you have only one store.'

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 enumerates the returned columns, which is the key missing piece an agent would otherwise lack. Read-only annotations cover the safety profile, and the currency rule covers the main aggregation pitfall; only limits (e.g., max stores, empty-store behavior) are 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%, so all three parameters (store, period, stores) are already documented with enums-like period options and defaults. The description adds only the implicit point that the same period applies to every store; it contributes little parameter-level meaning 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?

The description names a concrete output shape (revenue, orders, average order, refunds, top product) scoped to every connected store over one period, which is far more specific than the title alone. It implicitly separates itself from single-store tools by emphasizing 'each connected store,' but it never names a sibling such as compare_periods or get_sales_summary to sharpen the boundary.

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

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

'Built for agencies; also works with one store' gives a situational cue for when this tool is appropriate. However, there is no guidance on when to prefer compare_periods or get_sales_summary instead, and no note on whether empty results or unconnected stores are handled silently.

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 the readOnly/openWorld annotations, the description discloses the modeling approach, the known blind spots (seasonality and promotions are ignored), and a minimum-data requirement. It leaves unclear what the response looks like or how unreliable the estimate may be numerically.

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, front-loaded sentences: what it produces, how far to trust it, and what it requires. Every sentence carries information an agent would otherwise have to guess.

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

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

For a read-only, zero-required-parameter forecasting tool with no output schema, the description covers purpose, method, caveats and preconditions. Only the return-value shape and the undocumented horizon_days parameter remain 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 coverage is 67%: store and history_days are documented in the schema, while horizon_days has no description anywhere. The description's phrase 'next days or weeks' loosely gestures at the horizon parameter but adds no format, defaults, or constraint 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 ('estimates revenue for the next days or weeks') plus the method ('extending the recent weekly trend'), which distinguishes it from historical siblings like get_sales_summary and compare_periods. It never names a sibling explicitly, so it falls just short of the top mark.

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 use context (short-horizon projection) and an explicit precondition ('needs at least two weeks of past orders'), and warns the output is a rough guide. It does not state when not to use it or point to an alternative for rigorous forecasting.

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=true and readOnlyHint=false; the description adds real value on top by disclosing that an existing preset with the same name is replaced (overwritten), that writes are confined to the user's Pridly account, and that remove=true deletes the preset. It does not mention any confirmation, permission, or failure behavior for the delete path, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the core action, then scope, then the delete flag. Nearly every clause earns its place; only the 'nothing in the store changes' phrasing slightly overlaps the account-scope point.

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

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

For a 3-parameter mutation tool with annotations and no output schema, the description covers action, overwrite semantics, storage scope, and the delete mode. Gaps remain around required fields, length constraints, and what is returned on success or failure.

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 0%, so the description must carry parameter meaning, and it largely does: 'name' is framed as the preset's label with examples, 'guidelines' is described as plain instructions covering tone/words/length, and 'remove=true' is explained as deletion. It omits that name is required and the length limits, so it is not fully compensating.

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 gives a specific verb ('saves/replaces') and resource ('named writing style'), plus concrete examples ('Friendly', 'Luxury') and the content shape (tone, words to use or avoid, length). It implicitly contrasts with the get_brand_voice sibling and with store-mutating tools like apply_product_content, though it never names an alternative 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?

It clearly frames the use case (persisting a reusable writing style in the account) and states the delete path with 'Set remove=true to delete a preset.' The clause 'nothing in the store changes' steers agents away from treating this as a content-application tool, but it does not name the read counterpart or state 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 non-read-only, non-destructive, open-world; the description adds substantive context beyond that: the preview/confirm gate, the auto-expiry of the discount, paid-plan restriction, the 100-product cap, and the 5-minute-to-90-day window for apply_at. It never contradicts the annotations.

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

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

Front-loaded with the core effect and mechanism, then the workflow, then constraints. Every sentence carries information, though the preview-approval requirement is stated twice ("Preview first, then confirm" and "Always show the preview... before calling again with confirm=true"), a minor redundancy.

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

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

For a 12-parameter mutation with no output schema, the description covers the essential workflow, the safety gate, plan and size limits, and scheduling. It omits what the preview returns and how sku/store interact with the id selection, so it is strong but not exhaustive.

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

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

With 67% schema coverage the description adds real meaning for the selector params (ids preferred, or search word/category) and ties preview_id to confirm=true, plus the store-local-time format and bounds for apply_at. It does not explain sku or store, so it does not fully compensate for the coverage gap, but the important workflow params are clarified.

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 (gives products a percentage or fixed discount for a limited time), the underlying mechanism (PrestaShop specific prices), and the automatic lifecycle (old/new price shown, discount ends by itself). It also routes the agent to the sibling top_products for finding product ids, so it is distinguishable from find_products and update_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?

Explicit two-step workflow: preview first, then confirm with preview_id, and always get the user's explicit approval before confirming. It names prerequisites (paid plans only, max 100 products), the alternative for scheduling (apply_at with confirm=true), and the reversal path (undo removes it), leaving little 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 declare readOnlyHint and non-destructive, so the safety profile is covered. The description adds real value beyond that by defining the concrete health criteria, including the specific 'over 3 days' threshold for stalled orders and the explicit inclusion of low-stock and draft items, which an agent could not infer otherwise. It still omits whether results are counts or item lists and whether there is pagination or a cap.

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 checklist framing front-loaded and zero filler. It is long but every clause names a distinct issue type that earns its place; readability would improve with a light structure given the number of categories.

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 carry the return-value burden, and it does by enumerating the issue categories and the staleness threshold. The main remaining gap is the output shape (counts vs items, severity ordering, truncation), which matters for a diagnostic tool an agent may need to act on.

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 optional store parameter is fully documented in the schema, including the 'leave empty if you have only one store' case. The description mentions nothing about the store parameter, so it adds no meaning beyond the schema, which is the correct baseline of 3 for full coverage.

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

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

The description makes clear this is a diagnostic that returns a list of fixable issues, and enumerates the exact categories checked (missing images/descriptions/prices, out-of-stock, low-stock, drafts, stalled orders). It never uses an explicit verb like 'report' or 'list', and it doesn't distinguish itself from the overlapping sibling low_stock_report, which prevents 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?

There is no guidance on when to run this versus low_stock_report, find_products, find_orders, or multi_store_report, all of which surface partially overlapping data. No prerequisites, no frequency guidance, and no statement about when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds real value beyond that by disclosing its inputs (recent sales and stock), the shape of its output (ready-to-use settings for other tools), and the required human-in-the-loop presentation step. It does not describe depth of history analyzed or any limits on how many ideas are returned, which keeps it short of 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?

Two sentences, front-loaded with the capability and then the follow-through workflow. The parenthetical campaign list and the sibling tool references both earn their place by letting the agent recognize and route the output.

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

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

There is no output schema, so the description must carry the return-value burden, and it does the essential part by telling the agent the ideas come with ready-to-use settings targeting create_coupon/update_products. It stops short of describing the full structure of an idea or how many are returned, but an agent has enough to invoke and route 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?

Only one optional parameter, and schema description coverage is 100% — the schema already explains the store address/id and the single-store fallback. The description never mentions the store parameter, so baseline 3 applies with no penalty and no credit.

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 — analyzes recent sales and stock to propose discount campaigns — and then enumerates the concrete campaign archetypes (clear slow stock, grow basket, restock best sellers, win back lapsed customers). It also positions itself against siblings by noting the output feeds create_coupon or update_products, so an agent knows this is an advisory tool, not a mutator.

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 operating context and next-step flow: show the ideas to the user, then follow the normal preview and confirm path before creating coupons or updating products. What's missing is an explicit exclusion (e.g., 'do not use this to apply changes directly — use create_coupon'), though that is strongly implied by the naming of the sibling tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description's real contribution is the disclosure that 'bottom' excludes never-sold products — a genuine behavioral trait beyond the annotations — but it says nothing about multi-store behavior, ranking ties, or result shape.

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 core action and followed immediately by the one non-obvious rule. Every sentence earns its place; there is 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 zero-required-param, read-only ranking tool with no output schema and annotations covering safety, this is close to sufficient. The remaining minor gaps are what the return rows look like and how `store` interacts with `period` timezone handling in multi-store accounts, both of which are recoverable from 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?

At 60% schema coverage, the undocumented enums (`by`, `order`) are the gap, and the description does add meaning for both: 'revenue or units' glosses `by`, and the 'bottom' sentence defines the semantics of `order=bottom`. That is real value, but it does not compensate for the undocumented `store` scoping behavior or the absence of any note about combining `store` with `period` across stores.

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 — 'Ranks products by revenue or units sold in a period' — which is concrete enough to distinguish it from aggregation/report siblings like margin_report or low_stock_report. It stops short of naming an alternative outright, so sibling differentiation is by implication rather than explicit.

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

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

Usage is implied by the ranking framing but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to related siblings such as compare_periods or find_products. The one clarifying rule it does give ('bottom' considers only products that sold at least once) is about semantics, not tool selection.

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 this is a read-only, non-destructive, open-world operation. The description adds useful behavioral context by explaining that results include existing text in other languages, which tells the agent what the response contains and how to proceed.

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

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

Two sentences, front-loaded with the core purpose, followed by a concrete example and next action. There is no wasted text.

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

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

For a read-only lookup with no output schema, the description sufficiently explains what the tool returns: products missing text plus existing translations in other languages. Minor details such as limit and published_only behavior are covered by the schema rather than the description.

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

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

Schema description coverage is high at 80%, so the schema already documents most parameters including language codes, fields, limit, and store. The description reinforces the language and product scope but does not add parameter-level 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?

The description states a specific verb and resource: it lists products that have no text in a given language. The Spanish-description example makes the purpose concrete, and naming apply_product_content distinguishes it from general product search tools.

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

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

The description gives a clear usage scenario and explicitly connects the workflow to apply_product_content for saving translations. It does not name exclusions or alternative tools, but the intended context is clear.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, and the description adds genuinely useful behavioral detail the annotations cannot: the preview/confirm safety flow, the requirement for explicit user approval, and partial-failure semantics ('Fields that were edited again after the change are left alone and listed'). That tells the agent exactly what will and will not be destroyed.

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, all load-bearing; the safety-critical flow and the partial-failure caveat are front-loaded before the confirm instructions.

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 covers the workflow, approval gate, and edge case of re-edited fields, which is enough to call it correctly. It does not describe what the preview response contains or whether an undo itself can be reverted, leaving minor 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 baseline is 3. The description restates what the schema already documents (change_id from change_history, preview_id from the preview call, confirm only after approval) rather than adding new per-parameter meaning.

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

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

States a specific verb (Reverses) and a specific resource (a change Pridly made earlier), and routes id lookup to the change_history sibling. An agent can distinguish this from cancel_scheduled_change because it explicitly scopes to changes already made.

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 two-phase protocol (preview first, then confirm) plus the mandatory user-approval gate, and points to change_history as the source of ids. It does not state when NOT to use it (e.g., use cancel_scheduled_change for not-yet-applied changes), so it stops short of full alternative 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 flag destructiveHint=true and openWorldHint=true; the description adds substantial value on top by disclosing the mandatory two-step preview/confirm protocol, the preview_id handshake, the 5-minute-to-90-day window for apply_at, and the refund exclusion. It loses a point for the garbled phrase 'a note (private, (private notes only))', which muddies whether notes are always private or conditional on note_to_customer.

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 and workflow, and nearly every sentence carries operational meaning. The final sentence is a dense run-on mixing confirm, preview_id and apply_at, and the doubled-parenthesis note phrase is sloppy.

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, open-world mutation with annotations covering the safety profile and no output schema, this gives the agent the full call sequence, constraints, and exclusions. It omits what the preview response actually contains (what to show the user) and whether status/order_id are effectively required, which a careful agent would still need to infer.

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 63%, so the description must carry part of the load; it does explain the confirm/preview_id pairing and the apply_at bounds and time semantics beyond the schema's field-level text. It still never explains status enum consequences or the store parameter's role, so it only partly compensates for the coverage gap.

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

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

States a specific verb and resource — changes an order's status and/or adds a note — and rules out one adjacent operation by declaring refunds must be handled in PrestaShop. An agent can distinguish this mutation from the read-side siblings (get_order, find_orders) 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 an explicit workflow (preview first, then confirm), the human-in-the-loop requirement (always show the preview, get explicit approval before calling with confirm=true), the deferred-application variant, and the exclusion (refunds done elsewhere). No inference is left to the agent.

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 destructiveHint=true annotation: it discloses the preview safety net, that changes are recorded and undoable, a 500-product cap, paid-plan gating, and the 5-minute-to-90-day window for apply_at. It also clarifies prices are tax-excluded (HT), which the 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?

Front-loads purpose, then workflow, then constraints and alternative — well ordered. It is dense but nearly every clause carries operational value; only the tax-exclusion note could be argued as a schema-level 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, 15-param bulk tool with no output schema, it covers safety, staging, limits, pricing units, timing, and the alternative. The main omission is the selector semantics for choosing which products are affected, which matters given the param count.

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 only 40%, and the description adds real meaning for the workflow params (confirm, preview_id, apply_at) and pricing mode. However, it does not explain how the many selector params (ids, sku, tag, search, category, add_categories, set_status vs status) combine to target products, leaving a meaningful gap the schema doesn't fill.

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 (changes) and resource (many products at once) plus the exact editable fields (prices, stock, status, categories). It explicitly names the sibling it is not for ('for a limited-time sale use set_product_discount instead'), so the agent can disambiguate 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?

Explicitly documents the two-step preview-then-confirm workflow, the required user approval, and the rule that confirm=true needs preview_id. It also names the alternative for sales and the deferred-application path via apply_at — clear when-to-use, when-not, and how.

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