IdoSell MCP by usefulapi

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

readOnlyHint=true already covers the safety profile, so the bar is lower; the description contributes the API endpoint and the shape of what comes back (courier, tracking, status). It omits behavior for orders without parcels, batching limits for large serial-number lists, and whether any auth/scope is required.

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

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

Two compact sentences: the payload is front-loaded and the API path follows as a secondary detail. Nothing is redundant or padded.

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

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

For a one-parameter read tool with no output schema and readOnly annotations, the description is sufficient: it names the resource, the returned fields, and the endpoint. Only edge-case behavior (orders with no parcels, invalid serial numbers) 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 the single parameter is documented as 'Order serial numbers.', so the schema does the work. The description's plural 'of orders' loosely hints the parameter is a list, but adds no format, limit, or validity guidance 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?

Specific verb+resource ('Get the parcels (shipments) of orders') with the returned fields enumerated (courier, tracking numbers, status), which tells an agent exactly what it gets. It doesn't name or differentiate itself from siblings like idosell_get_orders, though the resource (parcels vs orders) is distinct enough in practice.

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: an agent can infer it should call this when it needs shipment/tracking data for known order serial numbers. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative (e.g. idosell_get_orders for order-level data, idosell_list_couriers for courier metadata).

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=true already tells the agent this is a safe read, so the description's burden is reduced. It adds the meaningful 'give at least one' constraint and the underlying endpoint, but says nothing about return size, batching behavior, or what happens when an id does not 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?

Three short sentences, front-loaded with purpose and immediately followed by the disambiguation. The trailing raw endpoint is marginal but takes almost no 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 two-parameter read tool with full schema coverage and a readOnly annotation, the description covers purpose, alternative, and the key input constraint. Remaining gaps (batch limits beyond the schema's maxItems, empty-result behavior) are small.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds a constraint the schema does not express: no parameters are marked required and there is no anyOf, so 'give at least one' is genuinely new information about the id/serial-number relationship.

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 orders') and names the two keying options (order ids or serial numbers), which cleanly separates it from the filter-based sibling. An agent can distinguish this from idosell_search_orders without reading either schema.

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

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

Explicitly routes filtering use cases to idosell_search_orders, which is the main ambiguity among siblings. It does not, however, say when this tool is preferable over that one beyond the filtering split, nor mention any prerequisites.

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

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

The readOnlyHint annotation already declares this is a safe read. The description adds the resource granularity (per warehouse and size) and the backing endpoint, which is useful context, but it says nothing about pagination, auth, or volume limits for a potentially large product list.

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

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

Two tight sentences with the resource description front-loaded and the endpoint as a compact trailing note. No waste.

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 2-parameter tool with no output schema, the description adequately conveys what is returned (quantities per warehouse and size). Minor gap: no note on expected number of results or whether all products must exist.

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 both parameters (products, ident_type) are already fully documented including the enum meanings. The description adds nothing beyond what the schema provides, so the baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (stock quantities per warehouse and size for products), which clearly distinguishes it from siblings like search_products or get_orders. It does not explicitly name a sibling alternative, but the purpose 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?

Usage is implied by the resource name - you call this when you need stock levels. There is no explicit when/when-not guidance and no mention of alternatives such as search_products for finding products before querying stock.

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, so the bar is lower. The description adds useful context beyond that: it is a pure configuration read exposing ids, that the response is metadata-oriented, and that it is safe to call first. It doesn't mention response size or caching, but nothing is misleading.

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 payload contents and followed by the practical recommendation and endpoint. Every sentence earns its place with no repetition 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 output schema, the description carries the burden of telling the agent what comes back, and it does so by enumerating the returned entities and noting they include ids. Only minor gaps remain, such as not indicating whether the response is large or nested.

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; baseline applies. The description correctly conveys that the call is parameterless and self-contained.

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

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

States a specific verb ('Get') and resource ('panel configuration') and then enumerates exactly what is returned: owner company data, languages, base currency, warehouses and shops with ids. No sibling tool overlaps with configuration retrieval, and the endpoint reference anchors it further.

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 recommends itself as a first call for learning shop ids and warehouse ids, which tells the agent when it is the right starting point. It stops short of naming a when-not condition or pointing at a follow-up sibling, but the tool is a bootstrap call so the guidance is practically sufficient.

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, so the safety profile is covered. The description adds value by naming the underlying endpoint (GET /products/brands) and disclosing the returned fields ('ids and names'), but says nothing about pagination behavior or total counts.

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 what the tool returns; the API-endpoint clause is compact and useful for API-aware agents. No filler, though it is arguably thinner than a tool description could be.

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

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

For a zero-required-parameter read-only listing tool with no output schema, the description covers purpose, entity scope, and returned fields adequately. Only the paginated nature of the response is left implicit, which the schema largely compensates for.

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%, with both page and limit fully documented including ranges and defaults, so the schema carries the parameter burden. The description adds no parameter meaning beyond that, which is the expected baseline.

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 brands (producers) of the shop') and clarifies the domain term with a parenthetical synonym. It is distinguishable from siblings like list_categories or list_couriers, 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?

Usage is only implied: an agent can infer this is the enumeration tool for brand entities, but there is no statement of when to choose it versus search_products or when not to call it. No prerequisites or pagination-strategy 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, so the safety profile is covered. The description adds the endpoint and the fact that ids and names are returned, but says nothing about pagination behavior, ordering, or the size of the category tree — context that would help an agent plan calls.

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 purpose and followed by the endpoint. Nothing is wasted, though the endpoint line is more useful to a developer than to 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 simple read-only listing tool with full schema coverage and annotations, the description covers purpose and return contents adequately. The absence of pagination hints is the only real gap, and the schema already documents page/limit.

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%, with each of the three optional parameters (ids, page, limit) fully described in the schema. The description adds no parameter-level meaning, so the baseline 3 applies.

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

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

States a specific verb and resource ("List the product categories of the shop") and even sketches the return fields (ids and names). It is clearly distinct from siblings like idosell_list_brands or idosell_list_couriers, though it never explicitly contrasts itself 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?

There is no guidance on when to use this versus alternatives, no prerequisites, and no note about fetching a single category instead. The only signal is the tool name and the API 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, so the safety profile is covered by structured data. The description adds two useful behavioral facts beyond that — the required country scope and that pickup-point support is reported per courier — but says nothing about result volume, pagination, or error behavior when a country has no couriers.

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 clauses, front-loaded with the primary purpose, followed by the distinguishing return attribute and the endpoint. No filler and nothing to trim.

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

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

For a simple, fully documented read-only list tool with annotations covering safety, the description is nearly sufficient; an agent knows what it returns at a high level. It stops just short of noting pagination defaults or the case where no couriers exist for a country.

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%, with page, limit, and country_code all documented in the schema, so the baseline is 3. The description reinforces country_code as the scoping input but adds no format or interaction detail beyond what the schema already says.

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 couriers') plus its scoping dimension ('available for a country') and the key attribute returned ('whether each one handles pickup points'). That is far more than a restatement of the name, though no sibling tool overlaps so no differentiation is needed — hence 4 rather than 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?

Usage is only implied: an agent can infer this is the lookup to call when it needs courier options for a destination country. There is no explicit when-to-use, no stated prerequisites, and no mention of what to do instead if the country is unsupported.

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=true already tells the agent this is a safe read, so the description's job is lighter. It adds the panel-scoped nature of the result set and that each entry carries an id and a name, but says nothing about ordering, pagination, or whether disabled statuses are included.

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 with the purpose front-loaded and the API endpoint trailing as supporting detail. No filler and nothing an agent must read twice.

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 names the payload contents (ids and names), which is what an agent needs to chain into status-setting calls. Minor gap: no note on whether the list is complete or filtered.

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 no parameter semantics to convey; the baseline of 4 applies. The description correctly does not invent inputs.

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

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

States a specific verb and resource ('List the order statuses') plus scope ('configured in the panel') and the returned fields (ids and names). It is clearly distinguishable from the one sibling that mutates status (idosell_set_order_status) by verb alone, though it does not name any 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: an agent can infer this is the lookup to use before calling idosell_set_order_status, but the description never says when to use it or points at that sibling. For a zero-parameter list tool this is acceptable but leaves the workflow connection implicit.

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=true already tells the agent this is a safe read, so the description doesn't need to establish the safety profile. It adds the underlying endpoint (GET /returns/returns) but discloses nothing about result ordering, default page size, total-count behavior, or rate limits — the kind of extra context that would raise this score.

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 capability front-loaded and the API path appended as reference. Nothing is wasted, though the endpoint string is marginal value for most 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?

For a read-only, fully-optional-parameter list tool with a fully described schema and no output schema, the description covers what is needed to invoke it correctly. Missing pieces (pagination defaults, result ordering) are minor and partly covered by the page/limit schema descriptions.

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, and the description's mention of order serial number, return id, and status id merely restates three of the five properties. It adds no syntax, matching, or multi-value 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 and resource ('List returns issued for orders') and names the three filter dimensions, so the tool is immediately distinguishable from order/product/customer siblings. It stops short of explicitly contrasting with siblings like idosell_search_orders or idosell_get_orders, which keeps it at a 4.

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 — an agent can infer 'call this to browse returns filtered by order, return id, or status' — but there is no explicit when-to-use, when-not-to-use, or guidance on paging through large result sets. No alternatives are named.

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

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

readOnlyHint=true already covers the safety profile, so the description adds value by disclosing what comes back (contact data, addresses, balances, consents) and the underlying endpoint GET /clients/clients. It does not explain matching semantics for text search or pagination defaults, which keeps it below a 5.

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

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

Three compact sentences, front-loaded with the primary capability followed by return contents and endpoint, with no filler or redundancy.

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

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

With all five parameters documented at 100% coverage and no output schema, the description's return-value summary plus endpoint reference covers most of what an agent needs. Missing details are minor: pagination defaults and how multiple filters combine.

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

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

Schema coverage is 100%, so baseline is 3; the description earns a bump by clarifying that text matches name, e-mail and login, which the schema only describes vaguely as 'Text searched in customer data'. It does not add anything about limit/page or the customer_ids array 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 (Find) and resource (customer accounts) and enumerates the three filter modes: text, ids, active state. The resource is clearly distinct from siblings like search_orders and search_products, though it doesn't explicitly name the boundary against 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?

Usage is implied by the enumeration of filter modes (text over name/e-mail/login, ids, active state), so an agent can infer the common call patterns. However, there is no explicit when-to-use versus alternatives, no note that all parameters are optional, and no guidance on combining filters.

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?

Adds real value beyond the annotations by pre-empting a likely misread: 'Read-only (a POST search)' tells the agent that a POST endpoint does not imply a mutation, which the readOnlyHint alone might not convey confidently. It also discloses the return payload (products, payments, dispatch data, customer), which annotations do not cover. It stops short of pagination behavior or result caps, which are only partially in the 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?

Three short sentences, front-loaded with the searchable dimensions, then the return shape, then the read-only caveat and endpoint. Nothing is repeated from the schema and no sentence is filler.

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

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

With no output schema, the description usefully summarizes the return payload, and with 10 fully documented parameters the input side is covered by the schema. The only gap is that total-count/pagination semantics for the response are unstated, a minor omission for a 0-required-param search 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 100% — every one of the 10 parameters carries its own description, enum, and pattern — so the schema does the heavy lifting. The description's list of filter dimensions mirrors those parameters without adding format, combination, or defaulting semantics (e.g. how date_from/date_to interact with date_type). 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?

Names a specific verb and resource ('Search orders') and enumerates the filter dimensions (status, date range, customer, ids, serial numbers), so the agent knows exactly what the tool does. However, it never distinguishes itself from the sibling `idosell_get_orders`, which sounds like a competing way to retrieve orders — that ambiguity keeps it below 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?

The enumerated filters imply this is the tool for filtered/queried retrieval, which gives an implicit usage cue. But there is no explicit when-to-use, no when-not, and no routing to `idosell_get_orders` or `idosell_get_order_packages`, so the agent must infer the choice from sibling names alone.

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 readOnlyHint=true, and the description usefully disambiguates that this is read-only despite being a POST search — a real confusion risk it preempts. It also previews return contents (prices, stock summary, images, categories), though it says nothing about result caps or auth requirements.

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

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

Three short sentences with zero filler: purpose and filters first, then return payload, then the read-only clarification. Every sentence earns its place and nothing is front-loaded poorly.

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 what is returned (prices, stock summary, images, categories), and pagination details are fully covered by schema descriptions. Combined with the read-only clarification, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so all eight parameters are already documented with clear semantics in the schema. The description's listing of filters roughly mirrors those parameters without adding syntax, defaults, or combination rules beyond what the schema provides; 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 ('Search products') and enumerates the filterable dimensions (text, code, availability, visibility, promotion), which distinguishes it from siblings like idosell_get_product_stocks and idosell_list_categories. An agent can tell what it retrieves 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 enumerating filter types, but no explicit when-to-use/when-not guidance or named alternatives are given among a crowded sibling set (search_orders, search_customers, get_product_stocks). The agent must infer that this is the general product 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?

Goes beyond the annotations by disclosing a real side effect: 'The panel may send customer e-mails for some status changes.' It also clarifies the idempotency semantics ('Setting the same status again has no further effect'), reinforcing the declared idempotentHint. Missing only permission/auth notes for a destructive mutation.

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 classification and core action, with no redundant phrasing. Every sentence adds distinct 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 2-parameter mutation with a fully documented schema and no output schema, the description covers action, idempotency, and side effects. It could add a note about required permissions or failure modes, but otherwise an agent has enough 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% and the enum lists all valid statuses, so the schema does the heavy lifting. The description names a few example statuses but adds no format or validation details beyond the schema, fitting the baseline 3.

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

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

States a specific verb and resource ('change the status of one order') with concrete example values (packed, ready, canceled) and an explicit WRITE marker. This clearly distinguishes it from read siblings like idosell_get_orders and idosell_list_order_statuses.

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 'WRITE: change the status of one order' framing implies when to use it, and the examples clarify intent, but no alternatives or preconditions are named (e.g., that idosell_list_order_statuses supplies the valid status set). Usage is implied rather than stated.

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