Loox MCP by usefulapi

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

Annotations already declare readOnly, non-destructive, open-world behavior, so the bar is lower. The description still adds real context: only published reviews are counted, the result is 0 rather than an error for unrated products, and it is a public Storefront endpoint (GET path given), which signals auth/surface expectations.

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 returned metrics, followed by API surface and endpoint path. Nearly zero waste, though the endpoint path is arguably redundant with the sibling-tool prefix.

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 one required parameter, no output schema, and full annotation coverage, the description supplies what is needed: what is returned (count and average rating), the fallback value (0), and the data scope (published reviews). Only the boundary against loox_get_product_reviews_summary is left unresolved.

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 product_id is documented with a digit pattern and example, so the schema carries the parameter semantics. The description does not mention product_id, its format, or that it is a Shopify numeric ID, adding nothing beyond the structured field; 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 resource and metric (review count plus average star rating for one product), which is clearly narrower than the list_* siblings. It does not, however, distinguish itself from the close sibling loox_get_product_reviews_summary, leaving the agent to infer which aggregate to call.

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

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

Usage is only implied: the 'ONE product' phrasing signals a single-item lookup rather than a list, and 'published reviews; 0 when it has none' hints at the data scope. There is no explicit when-to-use or when-not-to-use statement, and no sibling is named as an 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 and destructiveHint=false, so safety is covered. The description adds genuinely useful context – that unpublished and pending reviews are returned too, and that merchant PII (name, email, Shopify customer and order ids) is included – but says nothing about behavior for an unknown id or about moderation-specific 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?

Front-loaded with the resource and scope, followed by the payload note. The raw endpoint string "GET /api/v1/store/{id}/product-reviews/{reviewId}" is mostly redundant for an agent and is the one part that does not earn its place.

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

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

For a one-parameter read tool with annotations and no output schema, the description covers what is fetched, what moderation states are visible, and which fields come back. Only edge-case behavior (not found, permissions) is left out, 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 coverage is 100% and the single parameter already carries a pattern and a note that the id comes from a list tool, so the description adds only the reminder that any moderation status is accepted. 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 and resource ("One product review by id") plus an important scope qualifier ("any moderation status"), which lets an agent distinguish it from the list/summary siblings 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?

Usage is only implied: it's clear this is the single-record fetch taken after a list call, and the schema even says the id comes from a list tool, but the description itself never names an alternative or states when not to use it (e.g., use loox_list_product_reviews to find ids).

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 substantive context beyond that: the result is limited to published reviews and is served from the public storefront surface. It stops short of noting auth requirements or caching/rate behavior, but for a read-only aggregate that is acceptable.

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: the return payload is stated first, then the data scope, then the endpoint. Minor redundancy between 'Public Storefront API' and the raw GET path, but nothing wasteful.

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

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

With no output schema, the description carries the burden of describing return values and does so explicitly (total count, average stars, per-star counts 1-5). Combined with zero params and annotation-covered safety, an agent has everything needed to call it correctly.

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

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

The tool takes zero parameters, so the schema baseline is 4. The description correctly implies no filtering inputs are needed, and the scope (store-wide, published only) is conveyed in prose rather than left ambiguous.

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?

Clear verb+resource: returns the store-level aggregate of published product reviews (total count, average stars, per-star distribution). It is specific about what is aggregated, but it does not distinguish itself from the similarly named loox_get_store_reviews_summary or loox_get_product_rating siblings, leaving an agent to infer the product-vs-store scope.

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

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

Usage is implied by the 'published reviews only' and 'Public Storefront API' framing, which tells the agent this is the public-facing aggregate rather than a moderation endpoint. However, there is no explicit statement of when to use this versus loox_list_product_reviews or loox_get_store_reviews_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?

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true. Beyond that, the description usefully discloses that the tool returns reviews regardless of moderation status and includes merchant PII fields such as reviewer email, Shopify customer id, and order id.

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

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

The description is compact and front-loaded: it first states the resource and scope, then the key returned data, then the API path. Every sentence contributes useful selection or interpretation context.

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 helpfully specifies moderation-status behavior and several returned reviewer/merchant fields. It does not enumerate all review content fields, but it is sufficient for correctly invoking a simple one-parameter read tool whose safety profile is covered by annotations.

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

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

There is only one parameter and schema description coverage is 100%, so the schema already fully documents review_id. The description mentions lookup 'by id' but adds no syntax or format detail beyond the schema, making the baseline score appropriate.

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

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

The description states a specific verb and resource: retrieve one store-level review by id. The store-level scope and singular 'one' distinguish it clearly from list tools and product-review tools without needing to open the schemas.

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

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

It clearly establishes the retrieval context: use when you have a review id and need that single store-level review, including moderated reviews. It does not explicitly name alternatives such as loox_list_store_reviews or loox_get_product_review, but the context is clear enough for 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 readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the data comes from the public Storefront API and aggregates published reviews only, which tells the agent results may exclude unpublished/pending reviews. The endpoint path is also supplied, though return shape and pagination are not discussed.

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 burst that front-loads the actionable meaning (what the summary contains) before the qualifiers. The raw endpoint path is somewhat boilerplate but short enough to justify itself as debugging/reference context.

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 return-value meaning, and it does list the three result components. It stops short of describing the shape of the per-star breakdown (e.g., keys or ordering) or handling of stores with zero reviews, which is the only remaining gap for a zero-argument read tool.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline applies. The description correctly implies the scope comes from the endpoint path rather than any argument.

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 (store-level review summary) and enumerates exactly what the result contains: total count, average stars, and per-star distribution. The phrase 'store-level' distinguishes it from the sibling loox_get_product_reviews_summary without requiring the agent to open 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 only implied: 'store-level' and 'published reviews only' hint at the scope and at when this is the right tool versus the product-level sibling, but no alternative is named and no explicit when/when-not guidance is given. An agent can infer correct use, but must do the inference 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 and destructiveHint=false, so safety is covered; the description adds genuinely non-obvious context: 'Merchant data: includes the reviewer's name, email, Shopify customer id and order id,' warning that PII flows back, plus 'Real time' freshness. It does not discuss result volume or pagination behavior, which for a 250-per-page list tool would be worth a mention.

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

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

Three sentences plus the endpoint path, front-loaded with the resource and return contents before filtering details. Dense but each clause carries information; the field enumeration is long-ish but useful for deciding whether to call the tool at all.

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, read-only list tool with no output schema, the description covers what is returned, what can be filtered, the default moderation scope, and the PII implication – enough to call it correctly. The omission of pagination/volume guidance (next_page looping) is the main residual 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 parameter is already documented in the schema, including the status default, the sort enum semantics, and the next_page pagination hint. The description's parameter text ('Filter by product, star rating, status...') largely restates what the schema already says rather than adding syntax or edge-case meaning. Baseline 3 is appropriate when the schema carries the load.

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

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

Opens with a specific verb+resource ('List product reviews of the store') and enumerates the data returned (rating, text, media, merchant reply, product, verified flag, AI highlights, country, moderation status), so the agent knows exactly what payload to expect. It is clearly distinct from loox_get_product_review (singular) by the plural/list framing, but it never explicitly contrasts itself with loox_list_store_reviews, which is the closest sibling.

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

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

Gives actionable usage context for filters, notably 'status (default: published only; use pending to find reviews awaiting approval)' and the date-range and rating filters, which tell the agent when to reach for each parameter. It stops short of naming alternatives or exclusions (e.g., when to use loox_get_product_reviews_summary instead of listing everything).

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

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

Annotations already cover the read-only, non-destructive, open-world profile, yet the description still adds meaningful context beyond them: it discloses that responses contain merchant PII (reviewer name, email, Shopify customer id, order id) and that status defaults to published rather than returning everything. It doesn't mention rate limits or pagination mechanics, which keeps it from a 5.

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

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

Three dense sentences: scope first, returned payload second, filtering third, with the endpoint as a trailing implementation detail. No filler, and the most disambiguating information is front-loaded.

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

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

With eight optional parameters, no output schema and annotations already carrying the safety profile, the description compensates by enumerating returned fields and default filter behavior, which is what an agent needs to interpret results. It says nothing about the pagination contract (next_page) or response envelope shape, a minor remaining gap.

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

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

Schema coverage is 100%, so all eight parameters, their enums and defaults are already documented in the schema; baseline 3 applies. The description reinforces that status defaults to published and that date filters hit createdAt, but it adds no syntax or semantics for sort, direction, page or limit beyond what the schema states.

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 store-level reviews') and immediately disambiguates the scope with '(about the shop, not one product)', which is exactly the boundary against the sibling loox_list_product_reviews. It also names the returned fields and the underlying endpoint, so an agent knows precisely what it is calling.

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 parenthetical scoping note plus the filter summary (star rating, status defaulting to published, date range on createdAt) give a clear picture of when this tool applies versus the product-review siblings. It lacks an explicit 'use X instead when' statement and doesn't mention the summary/get variants, so it stops short of full routing guidance.

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