PlentyONE MCP by usefulapi

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description reinforces this with "an additive note, nothing is overwritten," which is a useful non-destructive guarantee rather than a restatement. It also discloses the default visibility behavior (internal only) and the underlying endpoint, though it says nothing about permissions or what is returned on success.

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: the operation type, target scope, non-destructive nature, visibility default, and endpoint are all front-loaded. Every clause carries information an agent needs before calling.

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 4-parameter, non-destructive write with annotations and no output schema, the description covers scope, default behavior, and endpoint. The remaining gap is what a successful call returns (comment id, timestamps), which an agent may want for follow-up calls.

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 75%, so the baseline is 3; the description earns an extra point by adding policy beyond the schema for visible_for_contact ("only make it visible when the user explicitly asks") rather than just repeating the default. The enumerated reference targets also clarify reference_type semantics, though the 5000-character text limit is left entirely to the schema.

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

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

The description leads with a specific verb+resource pair ("add an internal comment") and enumerates exactly which entities can be commented on (order, order item, contact, category, variation), matching the reference_type enum. The "WRITE" prefix immediately separates it from the read-oriented siblings like plentymarkets_list_comments and plentymarkets_get_order.

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

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

It gives explicit conditional guidance for the one judgment call an agent must make: keep the comment internal by default and set visibility only when the user explicitly asks. It does not name an alternative tool (e.g., use plentymarkets_list_comments to read existing notes), so it falls just short of the full when/when-not/alternatives bar.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so safety is covered. The description adds that the payload includes customer personal data and that `with` pulls in related addresses/accounts, but says nothing about error behavior for missing IDs, auth, or response 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?

Three short clauses with the primary action front-loaded; the parenthetical about documented relations is slightly wordy but earns its place by clarifying which relations apply. No filler sentences.

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 read tool with no output schema, the description covers purpose and relation expansion, but leaves return shape, not-found behavior, and the contact_id domain to inference. Adequate, 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 description coverage is 0%, so the description carries real weight here and it does explain the `with` parameter's semantics (addresses or accounts, single-contact route relations). However it never describes contact_id beyond 'by id', nor the maxItems=2 cap, so the two undocumented parameters are only half compensated for.

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 ('Get one contact by id') with scope made explicit by 'one' and 'customer personal data', which distinguishes it from the sibling plentymarkets_list_contacts without needing 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 only implied: the reader infers this is for single-contact retrieval and the list tool is for enumeration. There is no explicit 'use this when…' statement, no mention of when to prefer list_contacts, and no prerequisites noted.

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 real value by disclosing what the call returns (flags, manufacturer, texts, condition, age rating, item-level settings) and citing the underlying endpoint GET /rest/items/{itemId}, which is important since there is no 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 short sentences, front-loaded with the verb and scope, then the returned fields and the endpoint. No filler or restatement of the tool name.

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?

Without an output schema, the field list is a useful partial substitute, but the description omits what happens for an unknown item id, whether variation data is included (it likely is not, given list_variations exists), and that lang governs the returned texts. Adequate but with clear gaps for a lookup tool.

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

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

Schema coverage is 50%: lang is documented in the schema, item_id is not. The description clarifies that item_id identifies the item and that "texts" are part of the response (hinting at the role of lang), but it does not document item_id's range or explain how lang affects the returned texts. Baseline 3 given partial schema 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?

States a specific verb and resource ("Get one item by id") and enumerates the sub-resources it returns, which separates it from plentymarkets_list_items. It never names the read-only sibling explicitly, so differentiation is inferential rather than stated.

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

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

"Get one item by id" implies the use case (fetch a single known item rather than list them), but there is no explicit when-to-use/when-not guidance and no mention of plentymarkets_list_items or plentymarkets_list_variations as alternatives. Usage is implied, not stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description usefully adds that related data is opt-in via `with` rather than returned by default, but says nothing about auth, rate limits, or behavior when the order id doesn't exist.

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

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

Two compact sentences, front-loaded with the core action, followed by the return payload and the expansion mechanism. Zero filler; the trailing endpoint is a small redundancy but useful for debugging.

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 earns its place by enumerating the shape of the returned order (status, amounts, dates, properties, items, address relations). The only meaningful gap is not stating the error behavior for a missing order id.

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%; the `with` array has an enum but no schema description, and the description compensates by explaining its purpose and naming representative values ('addresses, comments, payments, documents, shippingPackages ...'). `add_order_items` is left to its schema description, which is adequate.

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 — 'Get one order by id' — plus the concrete fields returned and the underlying endpoint. The word 'one' implicitly distinguishes it from the sibling plentymarkets_list_orders, though it never names that 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?

Usage is only implied: the agent can infer 'call this when you need a single order's details, use list_orders for many.' No explicit when/when-not statement, no mention of plentymarkets_get_order_status_history or how this relates to 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, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds useful payload content (status, timestamp, acting user) but says nothing about pagination, result limits, or behavior for an order with no status changes.

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

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

Two tight sentences: the outcome first, the endpoint second. Nothing redundant, nothing padded.

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

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

With no output schema, the description carries return-value burden and does so by listing exactly the three fields the history yields. Missing only edge-case behavior (empty history, pagination) for a read-only single-order tool.

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

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

Schema description coverage is 0% for the single required order_id, and the description never explains it beyond the endpoint template placeholder '{orderId}'. That hint does not clarify whether it is the internal order ID versus an order number, nor any format constraints.

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 (an order's status changes) and enumerates the returned facts (which status, when, by which user), plus the underlying endpoint. It's clearly distinct from list_order_statuses and get_order, though it frames the act as a noun phrase rather than an explicit retrieval verb.

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 use this versus list_order_statuses (the catalog of statuses) or get_order (current state). The agent must infer that this is for historical transitions on a single order; no exclusions or prerequisites 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 readOnly, non-destructive and openWorld, so the safety profile is covered. The description adds the underlying endpoint (GET /rest/categories) and notes that returned names depend on the `with` parameter, but says nothing about pagination behavior or result volume.

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 plus the endpoint reference — no padding. The endpoint token is marginally useful but is the only element that doesn't clearly 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 an 8-parameter list tool with no output schema, the description does sketch the returned fields (id, parent, level, type, names), which is valuable. But it leaves the lang/name filters and pagination expectations unaddressed, so it is only partially sufficient.

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 38% (lang, name, type, level and parent_id are undocumented), yet the description only restates the `with`/details relationship already covered in the schema. It hints that level, parent_id and type describe tree position, which adds some meaning but leaves several filters unexplained.

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 item categories') and immediately clarifies the resource is the category tree with its key fields, which separates it from item/variation siblings like list_items. It stops short of naming any sibling or scope boundary 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 use this versus alternatives, nor any prerequisites or typical scenarios. The only implicit guidance is that `with` details enrich names, which is not the same as usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the raw REST endpoint (GET /rest/comments/{referenceType}/{referenceValue}), which signals a thin API passthrough, but says nothing about pagination, permissions, or whether an empty list vs. an error is returned for an unknown reference.

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 resource and scope, no filler. The endpoint sentence is marginally redundant with the tool name but does add the concrete path mapping for API-aware agents.

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

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

A simple two-parameter read tool with no output schema and annotations covering safety, so the burden is light. Still, the description omits the response shape (a list of comment objects) and any pagination or ordering behavior, which an agent needs to plan a call against a potentially long note 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?

Schema coverage is 50%: reference_id is documented in the schema, while reference_type has only an enum with no description. The description partially compensates by spelling out what each reference type means and by showing the {referenceType}/{referenceValue} path mapping, so the enum values are semantically grounded, but no constraints or defaults are added.

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 (internal notes/comments) and enumerates the four reference scopes (order, order item, contact, category), which is more precise than the tool name alone. The verb is only implied by the 'list_comments' name and the GET endpoint, but an agent can still tell this apart from plentymarkets_add_comment.

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 reference-type enumeration implies when the tool applies (fetching notes attached to an order, item, contact or category), but there is no explicit when-to-use/when-not statement and no routing to siblings such as plentymarkets_get_order (which may also surface notes) or plentymarkets_add_comment for the write side.

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, openWorld, non-destructive), and the description adds a genuinely useful caution that results contain personal data (names, emails, addresses). It also discloses the expansion mechanism (`with`). It stops short of explaining pagination or result ordering.

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

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

Two compact sentences with the resource and PII caveat front-loaded followed by the filter/expansion details. No wasted prose, though the endpoint string is redundant for an agent.

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 16-parameter read-only list tool with no output schema, the description covers resource identity, return content, filterable dimensions and expansions. Pagination behavior is only hinted at in the schema (items_per_page note), a minor gap given annotations already signal a safe read.

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

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

Schema coverage is 75%, so the baseline is 3. The description groups the filterable fields (email, name, number, type, postal code, town) and lists the `with` expansion values, which adds some semantic framing, but it omits the date-range filters (created_after, updated_before, last_order_*) and full_text, leaving several params described only 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?

States a specific verb and resource ('List contacts') and clarifies the entity scope with examples of contact kinds (customers, suppliers). An agent can distinguish it from the single-record plentymarkets_get_contact, though it doesn't name 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?

Usage is implied by the filter list and the `with` expansion note, but there is no explicit 'use this when…' or exclusion against plentymarkets_get_contact or the other list_* tools. The agent must infer that this is the bulk/query path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the response envelope ({page, totalsCount, isLastPage, entries[]}) and the underlying endpoint, though it says nothing about rate limits or default paging behavior beyond what the schema states.

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, each earning its place: identity, disambiguation, return shape. The most decision-relevant content (what an item is, and where variations live) 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 no output schema, the description usefully supplies the return envelope, and the sibling disambiguation is present. Minor gaps remain around pagination defaults and whether filtering is optional, but the schema covers most of that and the core call decision is fully supported.

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 89%, so nearly every parameter is already documented in the schema. The description only says 'with filters' generically and adds no syntax or interpretation 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 and resource ('List items') and immediately clarifies what an item is ('the product containers'), which the agent cannot infer from the bare name. It also distinguishes itself from the sibling list_variations by declaring that prices, stock, barcodes and SKUs are not part of this resource.

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: 'use plentymarkets_list_variations for those' with the exact condition (prices, stock, barcodes, SKUs). The alternative and the trigger for choosing it are both named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint path and the returned field set, which is useful, but says nothing about pagination behavior, empty results, or whether the name filter is exact-match or partial.

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 with the resource and returned fields front-loaded, followed by the endpoint path. No filler; slightly dense but every element carries information.

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

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

For a read-only list tool with no output schema, the description does cover the returned fields, and pagination is handled in the schema. It falls short on the unexplained 'name' filter and on whether results are paginated by default, which an agent needs before constructing a call.

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

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

Schema description coverage is 67%: page and items_per_page are well documented in the schema, including the is_last_page follow-up hint. However, the 'name' parameter has no schema description and the description never explains it, leaving one of three parameters undocumented in both places.

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 and resource ('List the manufacturers (brands) of the items') and even names the returned fields (id, name, address data), so an agent knows exactly what it retrieves. It doesn't explicitly differentiate from siblings, but no sibling covers manufacturers, so confusion risk is low.

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 when-to-use or when-not-to-use guidance, and no mention of alternatives (e.g., get_item for a single item's brand). The agent must infer usage from the tool name alone; the 'brands' gloss and endpoint path are the only context.

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 structurally. The description adds that this is a small reference list of channel ids, but says nothing about stability of the values, result size, or ordering. Some value added, mostly redundant with 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?

One sentence, front-loaded with the resource and its meaning, followed by the consumer tool and the endpoint. No filler, no restating of the 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?

With no parameters and no output schema, the description covers what the tool is and why, but does not enumerate the returned fields (e.g. id, name, backend name) beyond 'ids'. That is a small, tolerable gap for a trivial lookup.

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; there is nothing for the description to clarify beyond confirming no input is needed. It correctly avoids inventing filter parameters that don't exist.

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 (order referrers) and immediately disambiguates it as sales channels (shop, eBay, Amazon, ...) with their ids, so an agent knows exactly what the call returns. It also pins down the API endpoint, which removes any ambiguity against the other list_* siblings.

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

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

Explicitly states the downstream purpose: the returned ids feed the referrer_id filter of plentymarkets_list_orders. That names both the reason to call this tool and the tool it complements, which is the strongest possible routing guidance for a zero-argument lookup.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), and the description adds real value on top: the pagination envelope, which fields each entry carries, and the notable default that order items are included unless disabled. It does not discuss rate limits or auth, which is a minor gap for an open-world read.

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 compact sentences, front-loaded with purpose, then defaults, then return shape, then endpoint. Dense without padding; only the enumerated parenthetical "(sales orders, returns, credit notes ...)" is slightly loose.

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 21-parameter filter tool with no output schema, the description supplies the missing return contract (page, totalsCount, isLastPage, entries[] and entry fields) plus pagination and default-sort behavior. Pagination fields are named exactly as returned (isLastPage), so an agent can page correctly without guessing.

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 already 86%, so the baseline is 3; the description still earns more by stating the effective default ordering (sort_by=createdAt, sort_order=desc) and the payload-size consequence of add_order_items, neither of which is fully spelled out in the schema. It also clarifies that typeId 1 means sales order when reading results.

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 orders") and broadens scope explicitly to sales orders, returns, credit notes, plus the backing endpoint GET /rest/orders, which implicitly separates it from the single-order get_order sibling. It never names a sibling outright, so an agent must infer the list-vs-get 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?

Useful operating hints are present — default sort is newest first, and add_order_items=false makes pages smaller — but there is no explicit statement of when to reach for this tool versus plentymarkets_get_order or plentymarkets_list_order_statuses. Usage is implied by the filter inventory rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the per-language name detail and the REST endpoint, but says nothing about pagination behavior or result size beyond what the schema implies.

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

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

Two compact sentences: what is returned first, then the optional range filter, then the endpoint. 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 read-only list tool with no output schema, the description conveys both the fields returned and the filtering semantics. Minor gaps around pagination are covered by the schema's items_per_page 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 coverage is 60%, and the description compensates for the biggest gap by explaining that status_id_from/status_id_to form an optional id range. The remaining parameters (page, items_per_page, language) are already documented 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?

States the resource (order statuses), the return shape (id and name per language), and the concrete use case (translating a statusId). It is clearly distinguishable from siblings like get_order_status_history or update_order_status, though the verb is only implied by the name rather than the description.

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 usage context — translate a statusId, optionally restricted to an id range. It does not explicitly name alternatives or exclusions, but the stated purpose makes the selection obvious against history/update siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the bar is lower. The description adds genuine behavioral context by clarifying that this returns configuration metadata rather than price values, and cites the underlying endpoint GET /rest/items/sales_prices so an agent can reason about scope. It does not discuss pagination behavior, but the schema already carries that.

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, with the disambiguation in the trailing sentence. The parenthetical field enumeration is dense but earns its place by telling the agent what each record contains.

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 shape of returned records (id, type, names, stores, countries, currencies) and names the endpoint. Pagination semantics are left entirely to the schema, which is acceptable given 100% coverage, but a word on result ordering or typical volume would have closed the 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 description coverage is 100% and both parameters (page, items_per_page) are fully documented in the schema, including the 'ask for the next page when is_last_page is false' hint. The description adds no additional parameter meaning, so baseline 3 applies.

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

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

States a specific verb+resource ('List the sales price configurations') and then defines what a configuration contains (id, type, names, applicable stores, countries, currencies), which is more than the title restated. It explicitly separates these configuration records from actual variation prices by pointing at plentymarkets_list_variations with variationSalesPrices.

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 second sentence effectively routes the agent: if you want the prices attached to a variation, use list_variations with variationSalesPrices instead. That is a clear sibling alternative, but it does not state an explicit trigger condition for this tool or any prerequisite.

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 real value by disclosing the return envelope {page, totalsCount, isLastPage, entries[]} and the underlying endpoint, which lets the agent reason about pagination without an output schema.

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

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

One front-loaded sentence covering scope, optional filters, and return shape, plus a short endpoint tag. No filler or restatement of the name.

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 correctly supplies the response structure and pagination signal, and it marks all filters as optional. Gaps remain around sorting semantics and whether stock values are unit-qualified or per-warehouse aggregated.

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 57%, and the description only reinforces the variation and date filters already annotated in the schema. The sort_by/sort_order enums and paging defaults receive no added meaning in the description, so it is baseline-adequate rather than 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?

Opens with a specific verb and resource ('List physical stock per variation and warehouse') and enumerates the exact stock figures returned, so an agent can distinguish it from list_variations or list_warehouses 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?

Explicitly states the two narrowable modes — a single variation or a changed-since date — which tells the agent when the optional filters apply. It stops short of naming siblings to use instead for pure catalog data, so it is clear but not complete routing guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the GET endpoint and explains related-data expansion via `with`, but does not disclose pagination behavior, default page size, or return shape beyond what the schema already contains.

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: purpose first, then supported filters, then the `with` expansion. Every sentence contributes to understanding the tool, and there is no redundant repetition.

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

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

For a 19-parameter list endpoint without an output schema, the description gives useful scope and filter examples but omits pagination behavior and several filter parameters. It is adequate for basic use, but not complete enough to eliminate ambiguity for the full parameter set.

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 53%, and the description names many filters (item, number, barcode, SKU, active flag, category, warehouse) plus the `with` expansion. However, it leaves several parameters such as id, lang, page, is_main, supplier_id, manufacturer_id, updated ranges, and items_per_page unmentioned, so it adds useful but incomplete meaning 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 ('Search variations') and clarifies that variations are sellable products with number, SKU, barcodes, prices, stock, and categories. It does not explicitly distinguish this from sibling tools like plentymarkets_list_items or plentymarkets_get_item, so it is clear but not fully sibling-differentiated.

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 for filtered variation search and says to use `with` for related data, but gives no explicit when/when-not guidance or alternatives such as list_items or list_stock. This is minimum viable guidance rather than a clear routing statement.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set, which structured data does not provide (no output schema), but says nothing about pagination, permissions, or result size for a global endpoint.

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 action and the payload fields, with the REST endpoint appended as compact provenance. Nothing redundant.

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 carries the burden of telling the agent what comes back, and it does so by listing the fields. It falls short only on operational details such as auth scope or whether the list can be long, which a caller may need.

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 nothing for the description to disambiguate; the baseline for a parameterless tool is 4. The description correctly does not invent parameters that the empty schema would contradict.

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

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

States a specific verb and resource ('List the warehouses') and enumerates the fields each record carries (id, name, type, priority, address settings), so an agent knows exactly what comes back. It does not explicitly contrast with list_stock or other reference-data listings, but the resource is distinct enough among siblings.

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

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

The description implies a reference-data lookup but never states when to call this versus alternatives such as plentymarkets_list_stock (which likely concerns stock levels rather than warehouse definitions). No prerequisites or exclusions 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?

Goes well beyond the annotations by explaining the real side effects — event procedures such as customer emails, stock bookings, documents and shipping — which the destructiveHint=true alone does not convey. The 'Only the status is sent' note clarifies the partial-update semantics that the annotations and schema leave ambiguous.

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 WRITE label and the core action, followed by the risk warning and then the mechanics. Nothing redundant.

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 2-param mutation with no output schema, the description covers the action, the side effects, the update scope and where to get valid status ids. An agent has everything needed to call it safely without guessing.

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 50%: status_id is documented in the schema with an example, and the description adds that ids come from plentymarkets_list_order_statuses, which is useful. order_id is undocumented in both places and the description only implies it via the endpoint path. 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?

Opens with a specific verb+resource ('move an order to another status') and labels it WRITE, which immediately distinguishes it from the many read-only list/get siblings. The endpoint reference (PUT /rest/orders/{orderId}) pins down the resource exactly.

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

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

States a clear precondition: confirm the target status with the user first, and names plentymarkets_list_order_statuses as the way to get ids. That's good routing. It stops short of stating when NOT to use it (e.g. use the history tool to inspect status changes), so it lacks an explicit exclusion.

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