Sellasist MCP by usefulapi

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false; the description gives those hints concrete meaning by explaining that notes are appended and nothing is overwritten, which is exactly the operational consequence an agent needs. It omits auth/permission requirements, rate limits, and the shape of the response, which keeps it from a 5.

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

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

Three short sentences, front-loaded with the WRITE marker, and every clause carries distinct information: action, visibility/append semantics, and the underlying endpoint.

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 mutation with full schema coverage and clear annotations, this covers everything needed to invoke it safely. The one real gap is what the call returns — there is no output schema, and the description never says whether the created note or just a status is returned.

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 (order_id, text) are already documented in the schema, including the 5000-character cap. The description adds no further parameter-level detail, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource ("WRITE: add a new note to an order"), and the sibling list contains sellasist_list_order_notes, so an agent can immediately separate the write path from the read path without consulting 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?

It establishes the operational context for calling it: the note is staff-visible and each call appends rather than replaces, so callers understand the effect of invoking it repeatedly. It stops short of explicitly naming the alternative (list_order_notes) or stating exclusions, so it is clear context rather than full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds value beyond that: it discloses the response contents (per-language names, parent category, status) and pins the underlying HTTP route, which no structured field provides. It stops short of stating error behavior for a missing/invalid id.

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

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

Two short fragments, no filler: the return-shape summary comes first, then the route. Every token earns its place for a simple getter.

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 fields returned, and annotations cover the safety profile, so an agent has enough to call it correctly. The only gap is behavior on a nonexistent category id, which is minor for a read tool.

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

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

Schema description coverage is 100% with a single well-documented required parameter (category_id, integer > 0), so the schema carries the meaning. The description only echoes the id through the endpoint template and adds no format or sourcing guidance, which is the baseline case.

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?

'One category' plus the endpoint GET /categories/{category_id} makes clear this fetches a single category by id, and the field list (names per language, parent, status) previews the response. It is distinguishable from list_categories by the singular scope, though it doesn't explicitly name that sibling.

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

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

Usage is only implied: 'One category' signals single-item detail retrieval versus a listing, but there is no explicit statement of when to prefer it over sellasist_list_categories or what to do when the id is unknown. 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the underlying route (GET /users/{user_id}), which confirms the read nature but adds no new behavioral context such as not-found handling 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?

Two short fragments with no filler; the resource and returned fields are front-loaded. Slightly telegraphic, but nothing is wasted.

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

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

For a single-parameter read tool with no output schema, listing the returned fields (email, registration date, billing/delivery address) fills the gap the missing output schema would leave. Not-found behavior and any auth notes are the only omissions.

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 customer_id parameter is documented with type, bounds and a description, so the schema carries the burden. The description adds nothing beyond that, which is the baseline case.

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?

"One customer" names a singular resource fetch and enumerates the key fields returned, which distinguishes it implicitly from the sibling sellasist_list_customers. It never names the sibling explicitly, so the differentiation depends on the reader inferring singular-vs-list.

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?

"One customer" implies this is the by-ID lookup versus the list tool, but the description states no explicit when-to-use condition, no prerequisites, and does not name sellasist_list_customers as the alternative for browsing.

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 real value on top by enumerating the response contents (seller, buyer, currency, line items with net/gross/VAT, total, paid amount), which is important because no output schema exists. It stops short of noting behavior for a missing/invalid invoice id.

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

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

Two sentences, zero filler, with the returned payload front-loaded before the endpoint reference. Every clause earns its place by telling the agent what comes back.

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, describing the returned fields covers the main gap an agent would face. Only the failure mode (nonexistent invoice id) and the source of valid ids are absent, which is a minor omission.

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's description ('Invoice id.') already carries its meaning, so a 3 baseline applies. The description adds no format hints, ID provenance, or constraints beyond what the schema states.

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

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

The description names the resource (a single invoice) and enumerates the fields returned, so the agent knows exactly what it retrieves. It implicitly separates itself from sellasist_list_invoices by saying 'One invoice', though it never names the sibling explicitly. The trailing 'GET /invoices/{invoice_id}' pins the underlying operation.

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 instead of sellasist_list_invoices, or that an invoice_id must first be obtained from that list tool. Usage is only inferable from the singular phrasing and the required id parameter. No prerequisites, no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real value by disclosing exactly which data classes are returned (line items with EAN/prices, waybills with tracking, payments, additional fields), which is not derivable from 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 dense, front-loaded sentence plus the endpoint path; every clause conveys a distinct payload category and there is no filler.

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

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

With no output schema, the description compensates well by enumerating the returned fields, giving the agent a clear picture of the response. Minor gap: it does not specify the response envelope shape or error behavior for a missing 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 description coverage is 100% and the schema itself carries the key semantic caveat ('the id from sellasist_list_orders, not the marketplace's number'). The description adds nothing about order_id, 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 ("One order by id") and enumerates the returned data (status, addresses, line items, waybills, payments). It is clearly distinguishable from the list_/search_orders siblings by the singular 'one order by id', though it never names them 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: call this when you already have an order id. There is no explicit statement of when to prefer this over sellasist_list_orders or sellasist_search_orders, and no mention of prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the exact HTTP route, which is mildly useful context, but says nothing about error behavior for missing ids, rate limits, or auth expectations.

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

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

One dense sentence plus the endpoint, front-loaded with the lookup key. The long field enumeration is informative rather than filler, though the trailing 'and more' weakens the precision of the list.

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

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

For a single-parameter read tool with no output schema, enumerating the returned fields (title, category, prices, VAT, stock, EAN, weight, availability, manufacturer) is exactly the compensating context an agent needs to decide whether this call suffices. Only the id-provenance guidance 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 description coverage is 100% and the single parameter already states 'Sellasist product id.' with a positive-integer bound. The description's 'by id' adds nothing beyond that, so the schema carries the full load — 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?

Specific verb+resource+lookup key: 'One product by id', followed by an enumeration of the fields returned and the underlying endpoint GET /products/{product_id}. It is clearly distinct from list-style siblings by virtue of the singular lookup, though it never names sellasist_list_products as the alternative.

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: fetch a single product when you already have its id. There is no explicit guidance on where to obtain a product_id (e.g. from sellasist_list_products) or when to prefer sellasist_get_stock for stock data, both of which are reachable siblings that overlap with the fields advertised here.

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, openWorldHint=true, so the safety profile is covered. The description adds genuine value by naming what the response contains (status, refund and payment details, tracking, courier, returned items), letting an agent judge whether it needs this call.

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, payload contents front-loaded and the route appended as supporting context. 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?

There is no output schema, so the description must carry the return-value burden – it does so by enumerating the fields returned. Nothing essential is missing, though a note on error behavior for unknown ids would make it fully complete.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Return document id (from sellasist_list_returns)' with an exclusiveMinimum constraint. The description adds no syntax, format, or sourcing detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('One return document') and enumerates the payload fields it carries, which makes it clearly the single-document fetch counterpart to sellasist_list_returns. It does not name the sibling explicitly, but 'One' contrasts adequately with the list tool.

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 (fetch details for a known return id) and includes the HTTP route, but it never says when to call this versus sellasist_list_returns, nor any prerequisite such as needing a valid id. The workflow hint lives only in the parameter schema.

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 genuine behavioral detail the annotations cannot: the identifier precedence rule and the no-identifier fallback to a paginated listing, plus the underlying GET /products_stock route. It says nothing about pagination shape, behavior when an identifier matches nothing, or whether stock is per-warehouse.

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

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

A single dense sentence that front-loads the primary case (one product) before the fallback (all products), with no filler. The parenthetical precedence clause is information-dense but slightly run-on; still, every clause earns 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?

With no output schema, the description must convey what comes back, and it only says "stock quantity" or "a page of stock levels" without indicating the fields in a stock entry or whether quantities are broken out per warehouse (notable given the sibling sellasist_list_warehouses). Adequate to call correctly, but thin for interpreting results.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning the schema does not encode: the mutual-exclusivity/precedence ordering among id, ean, symbol and catalog_number ("the first one given in that order counts"). That directly changes how an agent should fill these parameters. Limits/offset semantics are 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?

States a concrete resource (stock quantity) and verb (get), and distinguishes its two modes: single-product lookup by identifier vs. a paginated listing of all products. It does not explicitly differentiate itself from siblings like sellasist_get_product or sellasist_list_products, so the agent must infer that this tool is stock-specific.

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 rule for selecting between the two modes: any of id/ean/symbol/catalog_number yields one product, none yields a page. It also specifies a precedence order among identifiers, which is real usage guidance. It stops short of naming alternatives (e.g. use sellasist_get_product for full product data) or exclusions, so it lands at 4 rather than 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine value by disclosing the underlying endpoint (GET /alerts) and the content of each alert (type, severity, title, message), though it omits pagination behavior beyond 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?

A single front-loaded sentence with the field list and endpoint appended; no filler and 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, the description helpfully enumerates the returned fields, which is the main thing an agent needs to know. The only gap is that pagination is left entirely to the schema, which is acceptable given full coverage there.

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

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

Schema description coverage is 100% and the single page parameter is already documented with default, bounds and next_page guidance. The description adds nothing about parameters, so the baseline 3 applies.

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

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

Names a specific verb (list) and resource (active alerts and system messages) plus the dashboard scope and returned fields. No sibling tool overlaps with alerts, so no differentiation is needed, but it stops short of the 5 mark because it doesn't explicitly state that only active/current alerts are returned versus historical ones.

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?

Implied usage only: the mention of 'shown on the Sellasist dashboard' hints at the context an agent would use it in, but there is no explicit when-to-use, when-not-to-use, or alternative guidance. For an alerts listing this is largely self-evident, keeping it at minimum viable.

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the description only needs to add value beyond that. It does add the ranking metric and the returned fields ('with stock and price') plus the underlying endpoint, but says nothing about result ordering ties, empty-result 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?

A single front-loaded sentence naming the ranking, the time window, and the returned fields, followed by the endpoint. No wasted clauses, though the telegraphic fragment style leaves no room for guidance a caller might need.

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 low-complexity read-only list tool with two fully documented optional parameters and existing annotations, the description covers what the tool returns and how it ranks. The absence of an output schema is partly offset by naming returned fields, though the exact response envelope remains unspecified.

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, limit) are fully documented in the schema, including defaults and the next_page chaining hint. The description adds no parameter meaning beyond that, 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 resource and ranking criterion ('Products ranked by units sold in the last month') plus the endpoint, which is far more than a restatement of the name. It doesn't explicitly distinguish itself from the sibling sellasist_list_products, so an agent must infer the bestsellers-vs-full-catalog split.

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 'last month' window implies when this view is appropriate, but there is no explicit when-to-use, no mention of sellasist_list_products as the alternative, and no exclusions or prerequisites. Usage is inferable 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint path, with no word on result ordering, whether all categories are returned at once, or pagination behaviour despite the offset/limit params.

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 fragments are front-loaded and waste no words, but the budget is spent on a redundant endpoint path rather than on information the agent cannot get from structured fields.

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

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

There is no output schema, so the description should describe what a category record looks like or at minimum that results are paged. Instead it says nothing about the return shape, leaving the agent unable to plan downstream use of the response.

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 (limit, offset) are documented in the schema, including the useful hint to pass next_offset, so the baseline is 3. The description contributes nothing beyond that, but it is not required to.

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?

"Product categories. GET /categories." is essentially a restatement of the tool name/title with a REST path attached; there is no verb and no statement of what the call actually returns or its scope. The only differentiator from sellasist_get_category (singular fetch vs. list) comes from the tool name, not 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?

No guidance on when to use this versus sellasist_get_category, sellasist_list_products, or any other listing sibling, and no mention of prerequisites such as requiring paging when the catalogue is large. The agent must infer usage entirely from the name.

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 and the description owes less. Beyond those, it adds only the raw endpoint (GET /users), which even conflicts slightly in naming with "customers"; it says nothing about ordering, pagination flow, rate limits, or what a page contains. Nothing behavioral beyond the structured fields.

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

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

Two terse fragments with no waste, but the terseness comes at the cost of specification rather than being disciplined brevity. The parenthetical definition is front-loaded and helpful; the endpoint string adds little 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 paginated list tool with no output schema, the description should at least say what a page returns and that iteration is via offset/next_offset. It omits ordering, total-count behavior, and any return-shape hint, leaving the agent to discover pagination semantics from the schema alone.

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?

Both parameters are fully documented in the schema (100% coverage), including the 1-100/default-25 limit and the instruction to pass next_offset into offset. The description adds no parameter detail, which is acceptable at full schema coverage, so the baseline 3 applies.

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

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

Names the resource implicitly ("Registered customers") and adds a useful gloss ("the account's buyers"), which distinguishes registered account buyers from anonymous/guest purchasers. But it never uses a verb like "list" or states the scope of the listing, so the operation is inferred from the name and title rather than stated. It also does not differentiate itself from the sibling sellasist_get_customer (single customer).

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 guidance at all: no mention of when to prefer this over sellasist_get_customer, no prerequisites, no note to paginate. The endpoint reference "GET /users" is the only hint of context. An agent must infer usage entirely from the tool name.

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 meaningful context beyond annotations by stating that only three fields are returned and by naming the underlying GET endpoint. It does not describe pagination, authentication, or rate limits, but with annotations covering safety this is a solid addition.

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 two short sentences plus the endpoint reference, front-loaded with what is listed and immediately followed by the returned fields. Every sentence contributes useful information and there is no filler.

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

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

With zero parameters, no output schema, and annotations covering safety, the description provides enough to invoke the tool correctly and tells the agent what fields to expect. It could mention whether results are paginated or whether authentication is required, but the essential calling context is present.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing to document. The description correctly does not invent parameter semantics and instead describes the returned fields, which is appropriate for a no-parameter tool.

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

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

The description states a specific verb and resource: accounts connected in external services, returning id, login, and type. It clearly identifies this as a listing of integration accounts, which is distinct from sibling list tools covering orders, products, customers, and other resources. The endpoint reference reinforces the exact 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?

Usage is implied by the tool name and description, but there is no explicit guidance on when to use this versus other listing tools or what conditions would make it the right choice. For a zero-parameter listing tool the implied usage is clear enough, but it stops short of naming alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered structurally. The description adds the endpoint (GET /invoices) but says nothing about pagination behavior, result caps (limit max 100) or whether filters combine as AND — modest added value beyond 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?

Three terse fragments, front-loaded with the resource and its returned fields, then filters, then endpoint. Nothing is wasted, though the telegraphic style borders on under-specification rather than genuine economy.

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 seven optional parameters, no output schema, and full schema coverage, the description supplies the one thing the schema cannot — the shape of returned records (id, number, date). Pagination is handled in the schema via next_offset, so the remaining gap is minor.

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

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

Schema description coverage is 100%, so all seven parameters are already documented with defaults and ranges; baseline is 3. The description echoes the filter groups (order, series, issue date) which helps orientation but adds no syntax, format, or date-string details beyond the schema.

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

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

Names the resource (invoices) and enumerates returned fields (id, number, date), plus the filter dimensions, so it is distinguishable from the singular sellasist_get_invoice sibling. The verb is only implied by the tool name rather than stated in the description, keeping it just short of a 5.

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

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

The phrase 'Filter by order, document series or issue date' implies a collection-retrieval use case, but there is no explicit when-to-use guidance or named alternative (e.g., use sellasist_get_invoice when you already have an id). Usage is inferable 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 useful context about what the records contain ('date and user id') and the underlying endpoint 'GET /orders_logs', but says nothing about pagination flow or result volume, which matters for a 7-parameter log listing.

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 front-loaded sentences: purpose first, filters second, with the endpoint as a short trailing tag. The action-type enumeration is long but genuinely informative; the bare 'GET /orders_logs' adds marginal value and is the only wasted token.

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 schema-documented list tool with no output schema, this covers purpose, scope and filterable dimensions adequately. It stops short of describing the record shape beyond date/user id, but nothing an agent needs to invoke it correctly 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 description coverage is 100%, so sort, limit, offset, orders, date_from/date_to and operation_tag are already fully documented. The description only restates the filter dimensions at a high level and adds nothing on formats (e.g., date syntax for date_from/date_to) beyond the schema.

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

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

The description uses a specific verb+resource framing ('The audit log of order actions') and enumerates which action families are covered (create, edit, status change, delete, merge, invoice, receipt). This makes it distinguishable from sellasist_list_orders and sellasist_list_order_notes, though it never names those siblings 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?

'Filter by order ids, action type or date' implies the common retrieval patterns, but there is no explicit when-to-use guidance versus list_orders, list_order_notes, or search_orders, and no stated exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the returned field set (author id, date, text, visibility) and the underlying endpoint, but says nothing about pagination, ordering, or what an empty result means.

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 fragments, zero filler, with the resource description front-loaded and the endpoint appended. The lead phrase lacks a verb, which makes it slightly elliptical, but nothing is wasted.

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

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

For a single-parameter read tool with annotations present and no output schema, the description is nearly sufficient — listing the returned fields compensates for the missing output schema. It falls short only on result-set behavior such as ordering or pagination.

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

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

There is exactly one parameter and schema description coverage is 100%, with the schema already stating 'Sellasist order id' and a positive-integer bound. The description adds no format or sourcing detail 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 resource and scope ('notes written on one order') and enumerates the returned fields, so an agent can tell it apart from sellasist_add_order_note. It never names the write sibling explicitly, so differentiation is inferred 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?

Usage is implied: pass an order id, get its notes back. There is no explicit 'use this when…' statement, no mention of sellasist_add_order_note as the write counterpart, and no guidance on when order logs (sellasist_list_order_logs) would be the better choice.

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 default sort direction, the field set returned, and the underlying GET /orders endpoint. What it omits is pagination behavior (limit/offset/next_offset chaining) for a list endpoint that can return large result sets.

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, front-loaded with the verb, default order and returned fields, then filters, then the alternative tool. No filler and the endpoint is appended last where it does no harm.

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 18-parameter, no-required-parameter list tool with no output schema, the description covers what is returned, how to filter, and where to go for detail records. The remaining gaps are pagination expectations and differentiation from sellasist_search_orders, both of which matter given the parameter count.

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

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

Schema coverage is 100%, so every parameter including limit, offset, from_id, currency, shipment_id and payment_status is already documented in the schema. The description only names a subset of filter fields and adds no format or semantics beyond what the schema states, 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 orders") and enumerates what the reply contains (status, billing address, payment, total, source, comment) plus default ordering (newest first). It explicitly routes line items/shipments to sellasist_get_order, so an agent can separate it from that sibling without opening 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?

It names the concrete filter axes (status, email, name, external id, payment, source, date) and gives an explicit alternative with its condition: "Use sellasist_get_order for line items and shipments." However, it never distinguishes this tool from sellasist_search_orders, which is the closest competing sibling for a list/filter workload.

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 by structured data. The description adds the underlying endpoint (GET /sources) and the shape of each record, but says nothing about pagination, result size, or account/permission prerequisites.

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 plus the endpoint, front-loaded with the resource. Nothing is wasted, though the trailing 'GET /sources' is largely redundant with the tool's own 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 parameters and no output schema, the description carries the burden of describing the return values, and it does so at a useful level of abstraction (id, name, type with concrete examples). Only pagination/ordering behavior is left unstated, a minor gap for a small reference list.

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 4 applies. The field enumeration (id, name, type) is a small bonus but concerns the response rather than 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 the exact resource ('order sources available in the account') and even enumerates the returned fields and example types (Allegro, shop, marketplace), which distinguishes it from sibling list tools like list_order_statuses or list_payment_methods. The verb is only implied by 'available' rather than explicitly 'list', which keeps it just short of a 5.

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

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

There is no statement of when to use this tool, when not to, or which sibling to prefer. An agent must infer from the sibling names that this is reference data for resolving an order's source rather than, say, integration accounts.

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 useful fact that results are per-account configuration, but says nothing about ordering, caching, or whether inactive/archived statuses are included — relevant for a lookup the agent will use to build filters.

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 fragments, front-loaded with what the tool returns and followed by why it matters. The trailing 'GET /statuses' is a raw endpoint note of marginal value to an agent but is cheap and does confirm the HTTP surface.

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 read-only annotations, little is required, but there is no output schema and the description never says what a status record contains (id, name, color, whether it is terminal) — the exact thing the agent needs to use the ids it is told to collect.

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?

Zero parameters, so the baseline of 4 applies; there is no parameter semantics to explain and the description correctly spends no words on 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 resource and scope: 'The order statuses configured in the account', which makes clear this is a read-only enumeration of account-level configuration rather than a generic list. It does not explicitly name a sibling to contrast with, but the name and resource are distinct from the other list_* tools (payment methods, sources, warehouses).

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

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

'Use the ids to filter orders or to change a status' gives the agent a concrete downstream purpose, implicitly pointing at sellasist_list_orders (filtering) and sellasist_update_order_status (mutation). It stops short of saying when NOT to call it (e.g. preferring a status filter already known), so it is clear context rather than explicit routing.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the returned fields and the endpoint (GET /payments), but does not discuss auth requirements, pagination, or rate limits.

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 no wasted text, and the resource and fields are front-loaded. The endpoint note is compact and useful.

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 no-parameter list tool with no output schema, the description adequately discloses what is returned (id, title). It is thin on pagination or response shape, but the tool's simplicity keeps that from being a major 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?

The tool has zero parameters, so the baseline is 4. The description correctly signals that there are no filtering inputs by simply describing the output fields and endpoint.

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

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

States a specific resource (payment methods), the fields returned (id, title), and an intended use (filtering orders). It does not explicitly distinguish itself from similar list_* siblings such as sellasist_list_shipment_methods or sellasist_list_order_sources, so it stops short of a 5.

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

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

The phrase 'for filtering orders' implies why an agent would call it, but there is no explicit when-to-use guidance, no prerequisites, and no named alternative among the many sibling list tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds real value by enumerating the returned fields (EAN, stock, reserved quantity, variants) and the GET /products endpoint, which matters since no output schema exists.

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 with zero waste: return fields, filters, and endpoint are front-loaded and each sentence earns 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?

With no output schema, the field enumeration is valuable and pagination is fully covered in the schema. Complete enough to call correctly; only explicit routing to the single-product sibling 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%, so all 11 parameters including enums, limits and offset pagination are already documented. The description's filter list mirrors schema fields but adds no syntax or format detail beyond the schema.

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

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

The description states a specific verb (List) and resource (products), enumerates the returned fields, and names the filter dimensions. This clearly distinguishes a bulk listing from the sibling sellasist_get_product, though it does not 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 (category, manufacturer, EAN, symbol, catalog number), but there is no explicit when-to-use vs when-not guidance and no reference to sellasist_get_product for single-record fetch.

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 beyond that by disclosing the underlying endpoint (GET /returns) and enumerating the return payload fields, which matters because there is no output schema. Pagination behavior (limit/offset/next_offset) is left entirely to the schema rather than mentioned.

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 dense sentences plus the endpoint, with the payload fields and then the filter set front-loaded in that order. Nothing is redundant with the schema and nothing wastes a clause.

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

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

For a 9-parameter, no-output-schema list tool, naming the returned fields compensates well for the missing output schema, and all filter dimensions are accounted for. The gap is that paging semantics and result-set size behavior are not touched at all in prose.

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

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

Schema description coverage is 100%, so every one of the 9 parameters is already documented, including defaults and the next_offset paging hint. The description only restates the filter dimensions (date, order, status, source, return number) without adding format or interaction detail, 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 the resource (return documents / RMZ) and enumerates the fields each record exposes (number, status, source, linked order, refund value, tracking number), which makes it clearly distinct from the sibling sellasist_get_return. It never uses an explicit verb like 'list' in prose, relying on 'Filter by...' and the endpoint to imply enumeration, so it stops just short of a 5.

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

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

The filter list implicitly tells the agent this is the browse/search tool for returns, but there is no explicit when-to-use or when-not, and no pointer to sellasist_get_return for fetching a single return by id. The usage is inferable 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, openWorldHint=true, and destructiveHint=false, so safety behavior is covered. The description adds the endpoint and returned fields, but does not mention pagination, result size, or auth requirements; with annotations present, this is adequate but not rich.

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 fragments, front-loaded with the resource and returned fields, then the endpoint. There is no wasted text.

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

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

For a zero-parameter list tool with annotations covering safety and no output schema, the description supplies the resource, fields, and endpoint. It is broadly complete, though it could mention whether all methods are returned or any result constraints.

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

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

There are zero parameters, so the schema baseline is 4. The description does not need to explain parameter usage, and it correctly does not invent any.

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

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

The description identifies the resource (delivery methods), the returned fields (id, title), and the intended use (filtering orders), with the backing endpoint GET /shipments. It is clear, though it does not explicitly distinguish itself from sibling list methods like sellasist_list_payment_methods.

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

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

"For filtering orders" gives an implied use case, but there is no explicit guidance on when to choose this over related list tools or when not to use it. The agent must infer the 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 safety is covered structurally. The description adds non-obvious behavior the annotations cannot convey: a feature-gating prerequisite and the concrete failure mode (HTTP 406), which lets an agent anticipate and interpret errors.

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

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

Two short sentences with no filler: resource and payload first, then the blocking precondition. Every clause earns its place, and the constraint is front-loaded enough to be seen before the call.

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

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

For a zero-parameter read tool with no output schema, the description supplies the returned fields, the underlying endpoint, and the entitlement requirement. Nothing an agent needs in order to call it correctly and interpret failure 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?

There are zero parameters, so the baseline is 4 and there is nothing for the description to compensate for. The field list (id, title) is return-shape information, useful but not parameter semantics.

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

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

The description names the resource (warehouses) and the exact fields returned (id, title), and the endpoint GET /storages confirms it is a retrieval operation. It is clear but does no work to distinguish itself from the many sibling list_* tools, since the name alone carries the 'list' 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?

It states a real precondition — the warehouse-management feature must be enabled or the API returns HTTP 406 — which helps an agent decide whether the call is viable. It gives no guidance on when to prefer this over siblings (e.g., stock vs. warehouse lookups), so usage is only partially covered.

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 returned field set, the endpoint (GET /ordersshipments), and the important limitation that label files are not returned inline. It stops short of describing pagination behavior or result ordering, which the agent must infer from parameters.

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

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

Four short fragments, front-loaded with what the tool returns, followed by filtering modes, a caveat, and the endpoint. No sentence is filler or repetitive.

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 paginated list tool with full schema coverage and no output schema, this covers purpose, filtering, returned fields, and a key limitation. The only mild gap is pagination guidance, which the schema's offset description already handles via next_offset.

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 (sort, limit, offset, date_from, date_to, order_id) is already self-documenting. The description only restates that filtering is by order or date, adding no format details (e.g., accepted date string format) beyond the schema.

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

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

The description names a specific resource (waybills / shipping labels) and enumerates the fields it returns (order id, tracking number, creation and delivery date), which is far more than a restatement of the name. It does not explicitly distinguish itself from the nearest siblings (list_orders, list_shipment_methods), but the resource is concrete enough that an agent can tell what it retrieves.

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?

"Filter by order or date" implies the two usage modes, and "Label files are not returned inline" steers the agent away from expecting downloads. However, there is no explicit when-to-use vs. alternative guidance, no mention of when to prefer a search/order-level tool, and no note on paging through results despite a paginated schema.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds genuinely non-obvious context: the operation uses POST solely because criteria go in the body, which preempts an agent from misreading POST as a mutation. It also discloses the 100-result cap, a limit not encoded in annotations or 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, scope, and cap; the endpoint trail is compact. The parenthetical '(id, date, status)' is ambiguous, but it doesn't obscure the front-loaded purpose.

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?

All four parameters are optional, the schema is fully described, and no output schema exists, so the description's remaining job is to explain semantics and limits. It covers the result cap and the POST/read-only nuance, but leaves the return shape and ordering unstated.

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 each parameter is already documented, including the 'and/or' optionality. The description reinforces that criteria can be combined freely and that results are capped, but it adds little beyond the schema. Baseline would be 3, but the '(id, date, status)' note clarifies the returned fields, and the read-only-plus-POST framing helps. However, '(id, date, status)' is ambiguous as a return-shape hint, and the 100-cap is not a parameter constraint. I'll score 3, not 5.

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 opening sentence gives a specific verb (Find) and resource (orders) with the exact scope: a creation-date range and/or a single status, capped at 100 results, plus the endpoint POST /orders_search. It does not differentiate itself from the sibling sellasist_list_orders, which an agent could easily confuse with this filtered search.

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 stated filter criteria (date range and/or status) and the 'find up to 100' framing suggests a bounded lookup rather than a full listing. However, there is no explicit when-to-use guidance and no mention of the sibling sellasist_list_orders or sellasist_get_order as alternatives, so the agent must infer routing.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds genuinely new information: the status's automations may fire (emails, stock moves) and the new status is not propagated to the marketplace unless send_status_to_external is set. That is exactly the side-effect disclosure an agent needs before a 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 sentences, each load-bearing: action, side effects, external-push default, and the id lookup pointer. The 'WRITE:' prefix front-loads the most decision-relevant fact.

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 three-parameter mutation with no output schema and full schema coverage, the description covers action, scope, side effects, defaults, and id discovery. Nothing needed to invoke it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the default semantics for send_status_to_external (default false, must be set to true to push) that the schema alone does not state. order_id and status_id are covered by the schema, so no further gain there.

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") plus the scope constraint (single order, only the status field) and even the underlying call shape. This clearly separates it from read siblings like sellasist_get_order or sellasist_list_orders.

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?

Names sellasist_list_order_statuses as the prerequisite lookup for status ids and explains the send_status_to_external branch, which tells an agent how to use the tool correctly. It stops short of stating when NOT to use it versus other order mutation paths, so it's strong but not fully exhaustive.

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