REVIEWS.io MCP by usefulapi

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the returned fields (average rating, review count) and the backing endpoint, which is modest extra value, but says nothing about rate limits, pagination, or missing-SKU behavior.

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

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

One compact sentence plus the endpoint path — the return content and SKU scoping are front-loaded with zero filler. Nothing could be removed 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 single-parameter read-only tool with no output schema, disclosing the returned fields (average rating, review count) covers the main gap an agent would have. Some minor detail is missing (what happens with unknown SKUs, response shape per product), 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% and the single sku parameter is fully documented there, including the semicolon separator and example. The description only restates 'by SKU (batch)', adding no format or edge-case detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific resource (product ratings) and states exactly what is returned — average rating and review count — plus the batch-by-SKU scope. It implicitly separates product-level ratings from the company-level sibling get_review_stats, but never names an alternative to make the distinction 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?

The '(batch)' parenthetical hints that multiple SKUs can be handled at once, but there is no statement of when to use this versus get_review_stats, get_review_nuggets, or the list_* siblings. No prerequisites, exclusions, or routing guidance are given.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-data scope are covered structurally. The description adds the useful framing that results are curated marketing snippets (not raw reviews) and discloses the endpoint path, but says nothing about pagination, ordering, or how many nuggets are typically returned.

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

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

Two tight sentences plus the endpoint, with the defining concept ('nuggets') front-loaded ahead of the filter list. Nothing is wasted, though the trailing GET path is redundant with the tool's own framing.

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 list endpoint with no output schema and full schema coverage, the description gives enough to understand what is returned (curated marketing snippets) and what can be filtered. The only real gap is that it never mentions the required 'types' selector, which an agent could miss.

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, establishing a baseline of 3. The description repeats the filterable dimensions (SKU, tags, branch, minimum rating) but omits the required 'types' parameter and per_page, adding no syntax or semantics 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+resource ('Get review nuggets') and defines what a nugget is ('short, highlight-worthy review snippets of company and/or product reviews'), which meaningfully separates it from siblings like list_reviews or get_review_stats. It does not explicitly name an alternative tool, so it falls short of a 5.

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

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

'for marketing' implies the intended context and the filter list hints at narrowing use, but there is no explicit when-to-use/when-not guidance or named alternative. The agent must infer that this is for pulling promotional snippets rather than raw review listings.

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 openWorldHint=true, so safety and locality are covered. The description usefully adds that the payload spans product, company and third-party reviews, but says nothing about freshness, rate limits, or auth needs.

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. The trailing raw endpoint path ('GET /stats/all') is developer-facing but harmless and cheap.

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 characterize the return value. It names the metrics but not the shape (per-scope breakdown, totals, counts structure), leaving the agent to guess at the response format for a zero-arg call.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline of 4 applies. The schema is trivially complete.

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: it returns average rating and review count, and it enumerates the three scopes covered (product, company, third-party). That scope list partially separates it from siblings like get_product_ratings, though it never explicitly contrasts with 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?

No statement of when to call this versus the overlapping reviewsio_get_product_ratings, nor any prerequisites or context. The agent must infer that this is the general summary endpoint.

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 openWorldHint=true, so the safety profile is covered. The description adds the concrete endpoint (GET /merchant/invitations) and enumerates the returned fields, which is useful, but says nothing about auth, rate limits, sorting, or pagination metadata beyond the parameter names.

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 covers resource, returned fields, filters, and paging, followed by the endpoint. Dense and near-waste-free, though the parenthetical field list is slightly listy.

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

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

With no output schema, the description compensates by naming the returned fields, and annotations cover the safety profile, leaving little the agent needs before calling it. Minor gaps around response structure and defaults (page default is in the schema) keep it from a 5.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the schema (including the true/false semantics of invite_sent). The description restates order id, sent state, and page/limit without adding format or range detail beyond what the schema provides, 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?

Names the specific resource (company review invitations), its scope (queued or sent), and the fields returned (customer, order, send date, status), which clearly separates it from the sibling list_product_invitations. It does not explicitly name that sibling, so it stops short of a 5, but an agent can identify the tool's remit without opening the schema.

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

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

Gives clear operational context: filter by order id or sent state, and page with page/limit. It does not state when to prefer the product-invitation sibling or any exclusions, so it lacks the explicit when-not routing 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 and openWorldHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: pagination is 0-based, next_page appears only when more results remain, and replies are opt-in via include_replies. It still says nothing about rate limits or result-size expectations, but the added context is substantive.

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

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

Three tight sentences with no filler, and the resource scope plus the private-data characteristic is front-loaded. The middle sentence partly duplicates what the schema already documents, which keeps it from being maximally economical.

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 15-parameter, entirely optional filter tool with no output schema, the description covers scope, filtering, ordering, and pagination, which is most of what an agent needs. It does not explain the response shape beyond next_page or how company reviews differ structurally from product reviews, but nothing critical is missing.

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

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

Schema coverage is 100% and every one of the 15 parameters carries its own description, so the schema does the heavy lifting. The description's filter enumeration largely restates schema content (rating range, dates, order number, branch, invitation id) without adding new semantics such as defaults or interaction rules. Baseline 3 is appropriate.

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

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

States a specific verb+resource (list company/store reviews) and scopes it with 'private data (order number, reviewer details, tags)' and the GET /merchant/reviews endpoint, which implicitly separates it from the generic reviewsio_list_reviews. It never names a sibling explicitly, so an agent must infer that the other list tool covers different review types.

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

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

The filtering sentence tells the agent what can be narrowed (rating range, dates, order number, branch, invitation id) and how results can be ordered, which implies the use case. However, there is no explicit when-to-use/when-not guidance or comparison against siblings such as reviewsio_list_reviews or reviewsio_get_review_stats.

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?

readOnlyHint and openWorldHint already declare this is a safe, non-destructive read against an external service, so the burden is light. The description adds the record shape (customer, order, send date, status) and the endpoint, but says nothing about pagination limits, total counts, or ordering, leaving the behavioral picture only partially filled in.

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

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

A single dense sentence plus endpoint: the resource comes first, then the returned fields, then the filters, then paging. The parenthetical list is slightly cluttered, but every clause carries information and nothing is redundant filler.

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

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

With a read-only list tool, no output schema, and full parameter coverage, the main remaining question is what comes back — and the description answers that by enumerating the record fields (customer, order, send date, status). Nothing essential is missing, though ordering/pagination behavior is left implicit.

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, including the invite_sent boolean semantics. The description only restates the filter axes (SKU, order id, sent state, page/limit) without adding format or default details beyond the schema — the baseline 3 for schema-covered params.

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 the specific resource (product review invitations), the sub-populations covered (queued or sent), and the fields returned (customer, order, send date, status), plus the underlying endpoint GET /product/invitation. The 'product' qualifier cleanly separates it from the sibling reviewsio_list_company_invitations.

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

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

The filter options (SKU, order id, sent state) imply how to narrow results, and 'page through with page/limit' implies paging usage, but there is no explicit when-to-use guidance or naming of the company-invitations alternative. An agent can infer context but must decide on its own when this tool is the right pick.

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 openWorldHint, so the safety profile is covered. The description goes further by disclosing that the response includes the account's private data (reviewer e-mail, order) and how pagination behaves ('Pages are 1-based; next_page is set when more results remain'), which an agent cannot infer from the annotations alone.

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

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

It front-loads the key claim ('The recommended way to read reviews') and packs scope, filters, pagination and endpoint into three dense sentences with little waste. The middle filter-list sentence is long, but each clause corresponds to real capability rather than filler.

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

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

With no output schema, the description partially compensates by describing the timeline contents, private-data inclusion and the next_page continuation signal. For a 16-parameter read tool it covers scope, filtering and pagination adequately, though it omits auth requirements and any sense of result volume or rate limits.

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

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

Schema description coverage is 100%, so every one of the 16 parameters is already documented, making 3 the baseline. The description adds only a high-level synthesis of the filter dimensions plus two defaults ('newest-first by default', 1-based pages) that are also present in the schema, so it does not meaningfully extend 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?

The description states a specific verb and resource and enumerates the four review kinds it covers (company/store, product, third-party, questions), which lets an agent distinguish it from narrower siblings like list_company_reviews. It stops short of naming those siblings explicitly, so the differentiation is implied by 'the recommended way to read reviews' rather than spelled out.

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?

Calling itself 'the recommended way to read reviews' gives clear guidance to prefer this tool over the more specific list siblings, and the filter enumeration shows what it is for. There is no explicit when-not-to-use statement or named alternative, so it lands at clear-context-but-no-exclusions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered without prose. The description adds only the underlying endpoint (GET /widget/survey-responses), with no mention of pagination, result caps, or authentication needs, so it adds little behavioral context.

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

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

Three short sentences, front-loaded with what the tool returns followed by the sourcing hint. The trailing raw endpoint path is implementation detail that a model does not strictly need, keeping it just short of perfectly economical.

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 identification and the id-sourcing dependency. It omits pagination/volume behavior, which is typical and important for a list endpoint, leaving a real gap.

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

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

Schema coverage is 100% and the single parameter is fully described there, including the campaign_id alias, so the baseline is 3. The description reinforces where to obtain the id, which slightly aids correct invocation but adds no syntax or format detail beyond the schema.

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

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

The description identifies the resource precisely (responses belonging to a single survey) and the list_ prefix plus the sibling list_surveys makes the intent unambiguous. It does not name a verb directly, relying on the name/title for that, but a reader can immediately distinguish it from reviewsio_list_surveys or reviewsio_list_reviews.

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

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

It gives an explicit prerequisite workflow: fetch the survey id from reviewsio_list_surveys before calling this tool. That is clear context for when to use it. It does not state exclusions or what to do when the survey has no responses, so it falls 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 and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (GET /widget/surveys) and the fact that ids are returned, but says nothing about pagination, ordering, or result size for an open-world list operation.

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 tight sentence plus an endpoint reference, with the key scoping/next-step information front-loaded. Almost no waste, though the trailing 'GET /widget/surveys' is of limited value to an agent choosing a tool.

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

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

For a one-optional-parameter read-only list tool with no output schema, stating that ids are returned covers the main return-value question an agent would have. It is complete enough to call correctly, missing only minor detail on result shape.

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

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

Schema description coverage is 100% and the single boolean parameter (exclude_inactive) is documented in the schema itself; the description adds no further meaning about its effect. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description names the resource concretely — the store's surveys (campaigns) — and states that ids are returned, and it differentiates itself from the sibling list_survey_responses by naming it. The verb 'list' is only carried by the title/name rather than the description text, so it falls just short of a fully self-contained verb+resource statement.

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

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

It gives one piece of forward guidance: use an id with reviewsio_list_survey_responses. However, it never says when to choose this tool over other list tools or what prerequisites/scoping apply, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so 'GET /ugc' adds nothing beyond what the annotations say. No mention of pagination behavior, rate limits, or result size despite a per_page parameter, so the description contributes almost no behavioral context.

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

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

Two short front-loaded fragments with no padding; the resource is stated before the filter list. The trailing 'GET /ugc' is redundant with the annotations, a minor waste of space.

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 list tool with a fully documented schema and annotations covering the safety profile, the essentials are present. However, it says nothing about return shape or pagination (no page cursor is exposed, only per_page), leaving the agent to guess how to page through UGC results.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including the semicolon separator convention and the 1-100 per_page range. The description only restates the filter dimensions at a high level, adding no syntax or default-value detail, which is the expected baseline 3.

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

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

States a specific resource (customer photos/videos UGC) and the filter dimensions it supports, which distinguishes it from text-review siblings like reviewsio_list_reviews. It never names an alternative sibling explicitly, so it stops short of a 5, but the resource is unambiguous.

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

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

Lists what you can filter by ('SKU, tag, category or videos only'), which implies the use case, but gives no explicit when-to-use guidance, no prerequisites, and no statement about when to prefer the review-listing siblings instead.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds one genuinely useful behavioral detail: the list includes both users who unsubscribed themselves and those unsubscribed by an admin. It does not mention pagination, ordering, or result size.

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, front-loaded sentences with no filler; the resource definition comes first and the endpoint last. It reads as a noun fragment rather than a full sentence, but nothing is wasted.

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

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

For a zero-parameter, read-only list tool with no output schema, the description covers what the data represents and its scope. The only meaningful gap is the absence of any hint about result shape or pagination, which is minor here.

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

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

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-parameter tool applies. The endpoint note (GET /unsubscribe/list) adds no parameter meaning but is harmless.

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 (email addresses that unsubscribed from REVIEWS.io invitation emails) and the underlying endpoint, so the agent knows exactly what data this returns. It is distinguishable from the sibling reviewsio_unsubscribe_user, though it does not explicitly name that sibling to contrast read vs. write.

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

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

No guidance on when to use this versus the sibling reviewsio_unsubscribe_user (which performs the unsubscription) or the invitation-listing tools. The agent must infer that this is the read-only retrieval counterpart. No prerequisites or context conditions are stated.

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

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

The description partly restates readOnlyHint=true, but it adds genuine behavioral context beyond the annotations: only review-submitted webhooks are returned, and this server has no write path for webhook management at all. That capability boundary is useful for an agent deciding whether this tool can accomplish a task. It does not describe response shape or pagination behavior.

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

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

A single compact sentence that front-loads the resource and scope before the parenthetical constraint. The trailing 'GET /webhook/list' is mild but useful implementation detail, so no sentence is wasted.

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

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

With no output schema, the description could have said what a webhook entry contains (URL, subscribed event, status), but it stays silent on return content. For a simple two-optional-parameter read tool with full schema coverage this is adequate-but-thin rather than incomplete.

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% (page and per_page are both documented with defaults and ranges), so the schema carries parameter semantics. The description adds nothing about paging behavior or defaults, which makes the baseline 3 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 names the resource ('the review-submitted webhooks registered for the store') and implies the list operation, plus gives the underlying endpoint GET /webhook/list. The 'review-submitted' qualifier genuinely narrows scope. The verb itself is implied rather than stated, and no sibling tool covers webhooks, so no sibling differentiation is required.

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

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

There is no explicit when-to-use statement, but usage is strongly implied by the read-only listing nature of the tool and by the note that the server never adds or removes webhooks, which signals that no create/delete alternative exists. No conditions, prerequisites, or alternatives are spelled out.

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, destructiveHint=true, openWorldHint=true, but the description adds critical context beyond them: a real e-mail reaches a real person, timing follows the Flow Sequence/template_id, and the action cannot be recalled from this server. That irreversibility detail is exactly what an agent needs before calling a destructive tool.

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

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

Front-loaded with the highest-stakes fact (write that sends a message to a real customer) and structured as escalating constraints. Slightly verbose with the caps-heavy warning framing, but every sentence carries operational weight.

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, non-idempotent mutation with no output schema, the description covers safety profile, timing, reversibility, and the confirmation gate. An agent has everything required to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by emphasizing the confirm_send_email: true requirement and the template_id override semantics as behavioral guidance rather than mere field docs. It does not, however, add format examples 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 ('queues ONE company review invitation e-mail') with explicit scope ('ONE', 'company' vs product invitations) and names the endpoint. An agent can distinguish it from sibling list/tag tools immediately.

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

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

Explicit when-to-use ('Only call it when the user has explicitly asked to invite this exact customer'), the required confirm_send_email: true gate, and an explicit absence of alternatives ('There is no bulk or SMS invitation tool'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real context beyond that: the tag is dashboard-visible and filterable, duplicate tagging is a no-op (reinforcing idempotency in operational terms), and no customer-facing notification is sent — a meaningful disclosure for a write 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?

Four short sentences, front-loaded with the 'WRITE:' marker, then effect, idempotency, side-effect scope, and endpoint. No filler; every clause carries information an agent can use.

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 write tool with no output schema, the description covers the operation, its idempotent behavior, and its visibility/side-effect scope, while annotations carry the safety profile and the schema documents both params. It is essentially complete, with only the lack of explicit sibling disambiguation keeping it from the top score.

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

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

Schema description coverage is 100% and both parameters carry their own descriptions and constraints (review_id as store_review_id, tag with example and 1-100 length). The description adds nothing parameter-specific beyond the path template, 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?

Opens with 'WRITE: adds a tag to one company review', giving a specific verb and resource and explicitly scoping to company reviews, which separates it from the sibling reviewsio_tag_product_review. The endpoint POST /review/tag/{id} reinforces exactly what is being mutated.

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

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

The description conveys the effect and constraints (visible in dashboard, usable as a filter, nothing sent to the customer), which implies when it is useful, but it never states when to choose this over reviewsio_tag_product_review or when tagging is inappropriate. Usage is implied rather than spelled out.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds genuinely new context beyond the structured fields: the tag is visible in the REVIEWS.io dashboard and usable as a filter, and crucially "nothing is sent to the customer", which rules out a customer-visible side effect an agent might otherwise assume.

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

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

Four short sentences, front-loaded with the WRITE classification and the core action, followed by side-effect clarifications. Every sentence carries distinct information and nothing is repeated for padding.

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

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

For a two-parameter write with no output schema and full annotation coverage, the description covers effect, idempotency, visibility, and absence of customer notification. It omits only peripheral details such as error behavior for an invalid review_id or any permission requirements, which keeps it just short of fully complete.

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

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

Schema description coverage is 100%, so both parameters (tag with its example and length bounds, review_id) are already documented in the schema. The description only echoes the path with {id} and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with a specific verb and scope ("WRITE: adds a tag to one product review"), and the "product review" qualifier cleanly separates it from the sibling reviewsio_tag_company_review. An agent can identify the resource acted on 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?

Usage is implied by the purpose plus the note that tags are usable as filters in the dashboard, which hints at when tagging is worthwhile. However, it never states when to tag a product review versus the company-level sibling, nor any preconditions (e.g. review must exist). No explicit when/when-not guidance.

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

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

Annotations declare destructiveHint=true and idempotentHint=false; the description goes beyond them by disclosing irreversibility ('no tool to re-subscribe... only undone in the dashboard'), that nothing is sent to the customer, and the HTTP endpoint. This is exactly the extra context an agent needs before an irreversible write.

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

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

Front-loaded 'WRITE:' marker, then scope, use case, irreversibility warning, side-effect note, and endpoint – every sentence earns its place with no padding.

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

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

For a one-parameter irreversible write with no output schema, the description covers purpose, trigger condition, reversibility, and side effects. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100% for the single email parameter, and the description only restates 'one e-mail address' without adding format or normalization rules. Baseline 3 applies since the schema already fully documents the parameter.

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 + scope: 'stops REVIEWS.io sending review invitation e-mails to one e-mail address.' The 'WRITE:' prefix and the endpoint make it immediately distinguishable from read-oriented siblings like reviewsio_list_unsubscribed_users.

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 it for a customer who asked not to be contacted' gives clear situational context. It doesn't name a sibling alternative (e.g. list_unsubscribed_users to check first), but the no-re-subscribe caveat effectively steers usage.

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