Hiboutik MCP by usefulapi

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

Annotations already declare this as a non-read-only, non-idempotent, non-destructive open-world write. The description adds value beyond that: the 'WRITE' marker, the minimum identifying-field requirement, the fact that the new customer id is returned, and the underlying POST /customers/ endpoint. It stops short of warning that repeating the call creates duplicates, which matters given idempotentHint=false.

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; the WRITE classification and resource come first, then the constraint, then the return value. Nothing to cut.

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 10-parameter creation tool with no output schema, the description covers purpose, minimum requirements, the endpoint, and what comes back (new customer id). It is nearly complete; the only missing piece is duplicate-handling guidance, which is notable because the operation is explicitly non-idempotent.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description adds a genuinely non-obvious constraint: although the schema lists zero required parameters, at least one of last name, first name, company or email must be supplied. That resolves a real ambiguity the schema alone leaves open.

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 ('create a customer in Hiboutik') and prefixes it with 'WRITE', immediately separating it from the read siblings like hiboutik_get_customer, hiboutik_list_customers and hiboutik_search_customers. The only other write sibling, hiboutik_update_customer, is clearly distinguished by the create/create-new framing.

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 gives a real precondition ('Needs at least a last name, first name, company or email'), which tells the agent when the call is valid. However, it never says when to prefer this over hiboutik_update_customer, nor whether the agent should check hiboutik_search_customers first to avoid duplicates — a relevant concern given idempotentHint=false.

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 that the response includes variant information alongside the product; it says nothing about behavior when no match exists (error vs. empty result).

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

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

Two short front-loaded sentences with no filler. The trailing REST path ('GET /products/search/barcode/{barcode}/.') is implementation noise rather than agent-relevant guidance.

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 lookup with no output schema this is minimum viable: it names the resource and mentions variants, but omits the not-found behavior and any sense of the returned payload shape, which an agent needs to handle misses 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?

One required parameter with 100% schema description coverage; the schema already documents 'Product barcode.' The description adds no format, length, or encoding guidance (relevant for a barcode string with maxLength 100), 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 and resource ('Find the product (and variant) with this barcode') and the identifier type (barcode) implicitly separates it from hiboutik_get_product (id-based) and hiboutik_search_products_by_name. It doesn't explicitly name those siblings, so the 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 by the barcode-specific phrasing – an agent with a barcode rather than an id or name will pick this. There is no explicit when-to-use/when-not statement nor a pointer to hiboutik_get_product or hiboutik_search_products as alternatives.

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 one genuinely useful behavioral fact — that the response contains 'full details' rather than a summary — but offers nothing on missing-id behavior, errors, or response shape, and the 'GET /customer/{customers_id}' line merely restates the endpoint.

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

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

Two short sentences with the scope front-loaded and no padding. The endpoint string is redundant restatement, which keeps it from a 5.

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 full schema coverage, no output schema, and annotations covering the safety profile, 'one customer with full details' is close to sufficient. Only error/not-found behavior is left unspecified, a minor gap.

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

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

Schema coverage is 100% with 'customers_id' documented as 'Customer id.', so the schema carries the parameter burden. The description adds nothing beyond echoing the id in the endpoint path, 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 retrievable resource and scope: 'One customer with full details' makes clear this returns a single record, which implicitly separates it from hiboutik_list_customers and hiboutik_search_customers. It does not name those siblings explicitly, so it stays at 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?

There is no when-to-use guidance and no mention of alternatives such as hiboutik_list_customers, hiboutik_search_customers, or hiboutik_list_customer_sales. The agent must infer from the name alone that this is the lookup-by-id path rather than the browsing path.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only 'full details', which hints the response is the complete record rather than a summary, plus the REST endpoint that confirms a simple by-id lookup. No mention of error behavior for unknown ids or field contents, so this is modest added context against an already-strong annotation set.

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 is returned. The endpoint path is arguably redundant with the title and schema but functions as a supporting detail rather than bloat.

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 full annotations, the essentials are present, but 'full details' is vague and there is no output schema, so the agent has no idea what fields come back. Minimum viable rather than 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% for the single required product_id, and the description only restates it via the URL template GET /products/{product_id}. Baseline 3 is appropriate since the schema does all the semantic work.

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 product with its full details" states a specific verb (fetch) and resource (a single product), and the singular 'one product' implicitly sets it apart from the list/search siblings. It stops short of explicitly naming find_product_by_barcode or search_products as the alternatives, so it is clear but not fully differentiated.

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

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

There is no when-to-use, when-not-to-use, or alternative guidance. With siblings like hiboutik_find_product_by_barcode and hiboutik_search_products_by_name that also return products, the agent gets no signal about which to pick; it must infer from the singular/plural wording 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 already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile needs no restating. The description usefully discloses the shape of the payload (header, totals, payment, line items), which is genuine added context. It says nothing about behavior when the id does not exist or about 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 terse fragments with the return contents front-loaded, zero padding. The trailing 'GET /sales/{sale_id}' largely restates the name but is cheap and confirms the underlying resource path.

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 enumeration of returned fields is exactly the context an agent needs to know a call is worthwhile. For a single-parameter read-only getter this is close to sufficient; only failure-mode behavior 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 'Sale id.' with an integer constraint. The description adds no format, range, or sourcing guidance 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 the specific resource (a single sale) and enumerates what it contains: header, totals, payment, line items. This distinguishes it from the sibling list tools (list_open_sales, list_closed_sales) which are plural. The verb is only implied by the name/endpoint, so it stops just short of a full verb+resource statement.

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

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

No guidance on when to call this versus the many sibling list/report tools, and no prerequisites or error conditions mentioned. An agent must infer from the name that this is a fetch-by-id operation used when the sale_id is already known.

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 newest-id-first ordering, which is genuinely useful, but says nothing about pagination behavior or the shape/size of results.

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, ordering information front-loaded before the endpoint reference. Nothing is padded, though 'GET /brands' is marginally redundant for an agent that only sees tool definitions.

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 list tool with full parameter documentation and annotation-covered safety, the description supplies what an agent needs to call it correctly. Only the result shape is unaddressed, and that is minor here.

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

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

Schema description coverage is 100%, so page/limit/offset are fully documented in the schema, including the next_page/next_offset continuation pattern. 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?

States a specific verb and resource ('List product brands') and adds the ordering ('newest id first'), which lets an agent distinguish it from list_categories, list_sizes, and other list siblings. No explicit sibling routing, but the resource is unambiguous.

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

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

Usage is only implied: it is the tool for enumerating brands. There are no siblings that overlap (no search_brands), so exclusions are unnecessary, but the description never states when to prefer it or what preconditions apply.

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 establish readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety behavior is covered. The description adds useful behavioral detail: default ordering is "newest id first" and the reply includes parent id and flags. It does not clarify whether the `sort` parameter overrides that default, but the added return-shape and ordering context is meaningful.

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 zero waste. The core purpose and returned fields are front-loaded, and the endpoint reference is a brief additional cue.

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 list tool with rich parameter descriptions and annotations, the description covers the resource, default ordering, returned fields, and endpoint. The only minor gap is not explaining how `sort` interacts with the stated default ordering.

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 pagination, sort, limit, offset, and order_by are already fully documented in the schema. The description adds no parameter-specific meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb ("List") and resource ("product categories"), and adds what fields are included ("parent id and flags"). The resource name alone distinguishes it from sibling list tools like hiboutik_list_brands, hiboutik_list_taxes, etc.

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's purpose: call it when you need product categories. However, there is no explicit when-to-use/when-not guidance, no mention of alternatives or prerequisites, and no note about how this relates to other list endpoints.

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 the store/date scoping constraint but says nothing about result volume or pagination, which matters here since replies can be truncated server-side.

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: behavior first, endpoint path second. No filler and nothing repeated beyond what is needed for orientation.

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?

Adequate for a read-only list tool with a rich 7-parameter schema, but with no output schema the description could usefully hint at what a page of closed sales contains or reinforce the limit/offset continuation pattern for large months.

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 including day, page, offset and limit are already documented in the schema. The description restates the day semantics but adds no syntax or format detail beyond what the schema provides.

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 closed (completed) sales of a store') and scopes it to one day or one month. The 'closed (completed)' qualifier implicitly separates it from the sibling hiboutik_list_open_sales, though that sibling is never named.

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 explains the day-omitted case rolls up to a full month, which is useful usage context. However, it never states when to prefer this over hiboutik_list_open_sales, hiboutik_get_sale, or hiboutik_report_turnover, leaving sibling routing to inference.

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

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

Annotations already cover safety (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real context: the sort order, the exact fields returned, the sensitivity of the data, and the underlying GET /customers/ endpoint. It omits truncation behavior, but the schema's limit param already warns that large replies are cut server-side.

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, zero filler, with the resource, ordering, and field list front-loaded before the endpoint reference. Every phrase carries information.

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

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

For a read-only list tool with no output schema, the description supplies the return fields, ordering, and data-sensitivity note, and the schema handles pagination fully. Only the list-vs-search routing is left ambiguous.

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 each of page/limit/offset has a precise description including defaults, bounds, and the next_page/next_offset continuation pattern. The description adds nothing about pagination or params, so baseline 3 applies.

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

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

States a specific verb+resource ('List customers') and enumerates the returned fields (name, email, phone, country, loyalty points, store credit) plus sort order (newest id first), which is well beyond a restatement of the title. It does not explicitly distinguish itself from hiboutik_search_customers or hiboutik_get_customer, leaving the list-vs-search-vs-fetch boundary to inference.

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 prefer this over hiboutik_search_customers (filtered lookup) or hiboutik_get_customer (single record). The only contextual note, 'Personal data of the shop's customers,' reads as a sensitivity flag rather than a usage rule.

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 two useful behavioral facts not present in structured fields: results are ordered newest first and map to a specific GET endpoint. It says nothing about pagination continuation or reply truncation, which the schema handles but which materially affect usage.

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, zero filler, with the purpose and ordering front-loaded before the endpoint detail. Nothing could be removed without losing information.

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

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

There is no output schema, so the description is the only place an agent could learn what a sales record contains, and it says nothing about the shape or fields of the response. Purpose, ordering, and safety are adequately covered, but the paging model (page/limit/offset with next_page/next_offset continuation) and return contents are left entirely to the schema or to inference.

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

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

Schema description coverage is 100%, so all four parameters (including page/limit/offset continuation semantics) are already documented in the schema. The description adds no parameter-level meaning beyond restating the customers_id target, so the baseline of 3 applies.

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

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

States a specific verb and resource (list the sales) plus a precise scope (made to one customer) and an ordering guarantee (newest first), which implicitly separates it from the broader sale-listing siblings. It does not name those siblings, but the scope is distinctive enough for an agent to disambiguate.

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 per-customer scoping implies when the tool is appropriate (history for a known customer id), but no explicit guidance is given about when to prefer it over hiboutik_get_sale, hiboutik_list_closed_sales, or hiboutik_list_open_sales, and no prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds useful ordering context ('newest first') and the underlying endpoint, but says nothing about pagination constraints or that the sort parameter can override the newest-first default.

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 zero waste, and the key scope fact and ordering are front-loaded ahead of the endpoint detail.

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

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

For a read-only list tool whose schema fully documents pagination (page/offset/limit/sort/order_by), the description provides enough to call it correctly. It stops short of explaining the continuation pattern or that sort/order_by can change the 'newest first' default, which would matter to an agent paginating or sorting.

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 six parameters are documented in the schema itself. The description only references store scope and ordering, adding no syntax or default details beyond what the schema already supplies. 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 (list) and resource (open sales) scoped to a store, and 'not yet closed' implicitly distinguishes it from list_closed_sales. It does not explicitly name the sibling alternative, keeping it just shy 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 'not yet closed' signals when to use it versus closed-sales alternatives, but there is no explicit when-not guidance or named alternative. Usage is only implied.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond that: results are scoped to one store, only *enabled* payment types are returned, and the payload includes currency and flags — useful given there is no output schema.

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

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

Two short sentences with the resource and returned fields front-loaded; the trailing endpoint reference is marginal but compact and gives a cheap mental map to the REST call. No filler.

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

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

For a single-parameter read tool whose annotations cover safety, the description supplies the scoping and return-content information an agent needs; only explicit sibling routing 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 store_id is already documented with a pointer to hiboutik_list_stores. The description only references {store_id} in the endpoint path, adding no new semantics beyond the schema, which is the expected baseline for full coverage.

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

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

States a specific verb and resource ("List the payment types enabled in a store") and clarifies the resource with examples (cash, card, cheque) plus the returned fields. It does not differentiate itself from any of the many sibling list_* tools, 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?

Usage is implied by the resource name: enumerate payment types for a given store. There is no explicit when-to-use, when-not-to-use, or alternative tool mentioned, so the agent must infer 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 establish readOnly/openWorld/non-destructive, so the description's added value is the default ordering (newest id first), the 250-row page size, and the concrete field inventory returned by GET /products/. That is meaningful context beyond structured data, but it does not cover pagination continuation or server-side truncation of large replies (which only the schema mentions).

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 ordering default and pagination constraint front-loaded before the field list. The field enumeration earns its place because there is no output schema.

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

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

With no output schema, the description compensates by naming the returned fields, and pagination is covered by both the description and schema. It stops short of explaining how to know when more pages exist or how sorting behaves with no explicit sort parameter, minor gaps for a simple read-only 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?

Schema description coverage is 100%, so every parameter (page, offset, limit, sort, order_by) is already fully documented, including the 250-row cap and continuation hints. The description only echoes the page size ('250 per page') and adds nothing about how sort/order_by interact with the stated default ordering — 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 ('List products') and immediately characterizes the result set: default ordering (newest id first), the fields returned, and page size. An agent can tell this is a bulk catalogue enumeration rather than a targeted lookup like the get/search siblings, 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?

The enumeration framing ('List products… 250 per page') implies the browse-everything use case versus the sibling search_products / find_product_by_barcode lookups, but the description never says when to prefer it or when not to. No prerequisites, no exclusion of the more targeted 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered without prose. The description adds useful context beyond that: the underlying GET endpoint and the fact that returned size_ids are the identifiers used for stock and sales records. It does not mention pagination, empty results, or behavior for an unknown size_type_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 tight sentences, front-loaded with what is listed and what is returned, followed by the endpoint. Nothing redundant, though the endpoint reference is of marginal value to an agent that only needs the parameter contract.

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

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

A single-parameter read-only list tool with full schema coverage and clear annotations; the description fills the one remaining gap by enumerating returned fields, which matters since there is no output schema. Only the failure/pagination behavior is left 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 coverage is 100% and the parameter description already points at hiboutik_list_size_types for valid ids, so the schema carries the load. The description adds a small amount by explaining what the resulting size_id is used for, but adds no format or range 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?

States a specific verb+resource ('List the variants (sizes) of one variant type') and names the returned fields, so the agent knows exactly what comes back. The distinction from the sibling hiboutik_list_size_types is only implied by 'of one variant type' rather than stated outright.

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 explicit when-to-use or when-not-to-use guidance, and no alternative is named. The sentence 'The size_id identifies a variant of a product in stock and sales' hints at downstream purpose but leaves the agent to infer the calling 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 this as a read-only, non-destructive, open-world operation. The description adds the GET endpoint and the id handoff to hiboutik_list_sizes, but it does not describe return fields, pagination, or other behavioral details.

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

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

Two short sentences, front-loaded with the resource purpose and followed immediately by the sibling workflow. Nothing is repeated or 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 trivial zero-parameter list tool whose annotations already cover safety, the description supplies the needed purpose and sibling relationship. It stops short of describing return values, but no output schema exists and the omission 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?

The tool has zero parameters, so there is no parameter semantics gap. The description correctly focuses on the resource and its downstream use rather than inventing parameter details.

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: list variant (size) types, with concrete examples. It also distinguishes the tool from its sibling hiboutik_list_sizes by explaining the id handoff, so an agent can route correctly.

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 gives clear context for using this tool first and then passing an id to hiboutik_list_sizes. It does not explicitly state when not to use it, but the workflow guidance is strong enough for correct selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the endpoint path: no note on pagination behavior, response shape, or the fact that results are scoped to the authenticated account/warehouses.

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 the resource named first and no filler. The bare endpoint reference ('GET /inventory_inputs/') is marginally useful for mapping to API docs but is low-value 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 read-only list tool with full schema coverage and no output schema, the description is minimally sufficient. It is still thin on what a stock order contains and how results relate to warehouses or suppliers, which would help an agent place it among the other stock tools.

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 paging parameters are documented thoroughly in the schema (page size 250, next_page/next_offset chaining). The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('List the stock orders / goods receipts') plus the underlying endpoint, so the agent knows this returns inbound inventory documents rather than stock levels. It does not explicitly distinguish itself from near-name siblings such as hiboutik_stock_by_warehouse or hiboutik_stock_all_warehouses, which return quantities, not 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?

There is no when-to-use guidance, no prerequisites, and no naming of alternatives. The agent must infer from the name alone that this is for browsing goods receipts rather than querying current 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by listing the response fields (compensating for the missing output schema) and disclosing the underlying endpoint 'GET /stores'; it does not mention pagination or auth, hence not 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?

Two short sentences, zero filler, with the core purpose and returned fields front-loaded before the downstream-usage hint. 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?

For a parameterless read tool with no output schema, the description supplies what matters: what is returned and how the ids are consumed elsewhere. Only minor gaps remain (whether the full account store list is always returned, pagination), which are unlikely to block correct invocation.

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 per the baseline this scores 4. The description correctly implies no filtering or scoping inputs are required.

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 shops (stores) of the account') and enumerates the returned fields (id, name, warehouse id, currency, time zone, address), so the agent knows exactly what it gets. No sibling tool lists stores, so there is little ambiguity, though it does not explicitly distinguish itself from the nearby list_warehouses tool despite mentioning warehouse id.

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 store ids for sales, payment types and reports' tells the agent this is a prerequisite lookup whose ids feed downstream tools, which is real usage context rather than an implied one. There is no alternative tool to exclude, so the absence of explicit when-not guidance costs little.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and the returned fields, but says nothing about paging behavior or result caps — the schema's notes on truncated replies are not echoed here.

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, and the resource plus returned fields are front-loaded. It is slightly under-sized for a list tool, but nothing is redundant.

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

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

For a simple read-only list tool with fully documented params and safety annotations, the description supplies the key missing piece — what each row contains — which matters since there is no output schema. Pagination guidance is delegated to the schema, which is reasonable.

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%: both limit and offset are documented in the schema, including defaults and the next_offset continuation pattern. The description adds no parameter 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?

The description names a specific verb and resource ('List the suppliers') and enumerates the returned fields (id, name, contact details), so the agent knows exactly what it gets. No sibling tool targets suppliers, so explicit differentiation isn't required, though the description does not say so.

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 the field list; there is no explicit when-to-use statement, no mention of pagination strategy, and no reference to alternatives. Since no sibling covers suppliers, the lack of exclusions is acceptable but the guidance is thin.

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 fully covered structurally. The description contributes the fact that it is a full GET /taxes enumeration returning id, name, value, and default flag, which is modestly useful. It adds nothing on pagination, ordering, or failure modes.

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 sentence that leads with the action and resource and packs the return fields plus the underlying endpoint. No filler, nothing that fails to earn its place.

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

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

For a zero-parameter read with annotations carrying the safety profile, the definition covers what the agent needs: no inputs, and what fields come back. With no output schema present, listing the returned fields in the description is a real contribution. Missing only enumeration details like pagination or ordering.

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 there is no parameter semantics to explain and the baseline is 4. The description does not misrepresent any input, and correctly implies the call takes no arguments.

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

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

The description gives a specific verb and resource ('List the tax (VAT) rates') plus the fields returned, so an agent knows exactly what comes back. It does not differentiate from siblings such as hiboutik_list_brands or hiboutik_list_payment_types, but the resource name 'taxes' is unambiguous against those.

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

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

Usage is only implied: it is a parameterless 'list all' tool, so the implicit guidance is 'call it when you need the full tax rate catalogue.' There is no explicit when-to-use, precondition, or alternative named. For a trivial zero-argument read this is adequate but adds nothing.

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. The description adds meaningful behavior beyond those annotations by stating that passwords and keys are never returned and by identifying the underlying GET /users endpoint. It does not mention pagination or rate limits, but the security-sensitive exclusion is a valuable disclosure.

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 three tight sentences with the core list operation front-loaded. Each sentence adds useful information: returned fields, the vendor_id relationship, sensitive-data exclusion, and 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 zero-parameter, read-only listing tool with no output schema, the description provides enough detail to call it correctly: what is listed, which fields come back, how the id relates to sales, and what is intentionally omitted. Annotations cover the safety profile.

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 schema itself is complete and no parameter guidance is required. The description appropriately spends no space on nonexistent 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?

The description states a specific verb and resource: list Hiboutik users. It clarifies the user types (staff, sales vendors) and lists returned fields (id, name, email, access level), so an agent can distinguish this from the customer, product, and sale listing siblings.

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

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

The description gives clear context by explaining that the returned id is the vendor_id used on a sale, which helps an agent know why to call it. It does not name explicit alternatives or when-not conditions, but there is no sibling user-listing tool to route against.

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 that the tool returns id and name and identifies the backing endpoint, but it does not discuss return shape beyond those two fields, pagination, or any authentication requirements. With annotations doing most of the behavioral work, 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?

The description is two short sentences with no wasted words. The key information is front-loaded: what the tool lists, what it returns, and what the returned IDs are used for.

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

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

For a zero-parameter read-only list tool with annotations covering safety, the description gives enough context to call it correctly: it names the resource, the return fields, and the intended use of the IDs. It does not explain the exact response structure or pagination, but those gaps are minor for this simple endpoint.

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

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

The tool takes zero parameters, so there is no parameter semantics to document and the baseline score of 4 applies. The description does not need to compensate for any schema gaps.

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 clearly states a specific verb and resource: list warehouses, clarified as stock locations, and notes the returned fields id and name. It is clear enough for an agent to understand the operation, but it does not explicitly distinguish this tool from the sibling list_stores, which could cause confusion.

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 sentence 'Use the ids for stock levels' gives clear context for why an agent would call this tool, namely to obtain warehouse IDs for subsequent stock-level queries. It lacks explicit when-not conditions or named alternatives such as list_stores, but the usage context is still evident.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and states the shape of the result (quantities and revenue per product) but says nothing about pagination or the server's reply truncation, which the schema handles instead.

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 with zero padding: the result content comes first, the endpoint second. Every clause carries information an agent can use.

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

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

For a read-only report with no output schema, the description conveys what the rows contain and the time/store scope, and the schema covers pagination exhaustively. Only the absence of any routing hint against the turnover sibling keeps it from being fully complete.

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

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

Schema description coverage is 100%, including pagination semantics (page/limit/offset with next_page/next_offset continuation and truncation warnings), so the baseline is 3. The description reinforces that year/month define a single-month window but adds no format or range 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 names a specific resource and aggregation granularity: quantities and revenue per product, for one store in one month, and cites the underlying endpoint. It is clearly distinct from the aggregate turnover sibling, though it never names 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?

The scope (one store, one month) implies when the tool applies, and the required parameters follow from that framing. There is no explicit when-not guidance or reference to a reporting alternative such as hiboutik_report_turnover, so selection relies on inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context the annotations lack: whether the result is a single aggregate or a per-day series, and the fact that it is store-scoped remote data fetched via a dated path.

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

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

Two sentences, front-loaded with the meaning of the returned value, then the granularity rule, then the endpoint. Nothing is padded or 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?

No output schema exists, so the description should anchor the return value; it does so qualitatively ('Sales total (turnover)') and distinguishes aggregate vs per-day output. It does not indicate the currency, tax treatment, or whether a per-day series is an array, which is a minor remaining gap for a reporting 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?

With 100% schema description coverage, the schema already documents every parameter including the 'omit for the whole month' behavior of day. The description repeats that same semantic via the endpoint template but adds no format, default, or constraint detail beyond it, so the baseline of 3 applies.

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

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

The description names the specific resource (turnover / sales total) for a specific scope (one store, one day or one month) and gives the exact REST endpoint. It is clearly distinguishable from the only sibling report, hiboutik_report_products_sold, which covers product-level units rather than monetary totals.

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 explains the day-omitted branch, which tells the agent how to get a monthly per-day series instead of a single-day total. However, it never states when to prefer this report over hiboutik_report_products_sold or hiboutik_list_closed_sales, so tool-selection guidance is only implied.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the input constraints (3-character minimum, date format, comparison prefixes) and reveals the underlying endpoint, but says nothing about match semantics (prefix vs substring), how multiple filters combine, or whether an empty call returns everything. Useful additions, but the operation itself is not fully characterized.

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 resource and the searchable attributes, then the input-format rules, then the endpoint. Nothing is padded, though the endpoint mention earns 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?

With 13 all-optional parameters and a fully documented schema, the definition is adequate but leaves key questions open: whether multiple filters are ANDed, whether text matching is exact or partial, and how this differs from hiboutik_list_customers when no filter is supplied. No output schema exists, so return-shape uncertainty is expected, but match semantics should have been stated.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, which sets the baseline at 3. The description's cross-cutting rules (3-character minimum, yyyy-mm-dd dates, > < >= <= prefixes) largely restate what minLength and the regex patterns already encode. It also enumerates the text-search fields without covering loyalty_points or last_order_date.

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 ("Search customers") and then enumerates the searchable fields, so the agent knows exactly what this tool accepts. It does not name the nearest siblings (hiboutik_list_customers, hiboutik_get_customer), so the boundary between searching and listing is left implicit. Two schema parameters (loyalty_points, last_order_date) are not listed among the searchable fields, which slightly muddies the stated scope.

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

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

Usage is only implied: the field list suggests "use this when you have a customer attribute to match on," and the 3-character minimum hints at how lookups work. There is no explicit statement of when to prefer hiboutik_list_customers (enumerate everything) or hiboutik_get_customer (fetch one by ID). No prerequisites or exclusions are given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds only the vendor endpoint ('GET /products/search/'), and says nothing about result size limits, empty-filter behavior, or pagination semantics beyond what the schema already documents.

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

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

A single front-loaded sentence plus the endpoint; no wasted prose and the filter set is stated immediately. The endpoint fragment is marginal value but not harmful.

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 12 optional parameters and no output schema, the description should say what an unfiltered call returns and how paging relates to results, but it does not; the schema does cover paging and the read-only nature is in annotations. Adequate but with clear gaps for an agent deciding on defaults.

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 twelve parameters already carry meaning in the schema; the description only restates the same filter list without adding syntax, defaults, or interaction notes. 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 gives a specific verb ('Search') and resource ('products') and enumerates the filter dimensions (model, category, brand, supplier, archived, references), so an agent knows exactly what the tool does. It does not name or distinguish itself from the sibling hiboutik_search_products_by_name or hiboutik_list_products, so it falls short of a 5.

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

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

Usage is only implied by the enumerated filter set; there is no statement of when to prefer this over hiboutik_list_products or hiboutik_search_products_by_name, nor what happens when no filters are supplied. The agent must infer the selection rule 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the underlying GET endpoint and match-on-name behavior, but does not clarify whether matching is substring, prefix, or exact, nor what the result shape is.

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 core purpose and followed by the API route. No wasted language.

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?

The tool is simple, annotations cover safety, and the schema fully explains pagination parameters. However, with no output schema, the description could do more to explain the matching behavior or returned product data, leaving some ambiguity for an agent invoking the search.

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

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

Schema description coverage is 100%, so all four parameters are documented in the schema. The description only restates that q is the text to look for in the product name, adding no syntax or behavioral 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?

States a specific verb and resource: finding products whose model/name matches given text. It is distinguishable from get_product and find_product_by_barcode, but does not explicitly contrast with sibling tools like search_products or list_products.

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

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

The description implies a name-based search but gives no explicit when-to-use guidance, no exclusions, and no mention of when to prefer search_products, list_products, or find_product_by_barcode.

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 destructiveHint=true and idempotentHint=true, so the bar is lower; the description still earns credit by spelling out exactly what is destroyed ('it overwrites any existing comment') and naming the underlying endpoint, which corroborates rather than contradicts the safety profile.

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

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

One compact sentence with the write-safety warning front-loaded and zero filler; nothing could be removed without losing information.

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

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

For a two-parameter write with full schema coverage, rich annotations, and no output schema, the description covers purpose, mutation semantics, and overwrite risk. Only the response behavior after the write is unaddressed, a minor gap.

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

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

Schema description coverage is 100%, so both parameters are already documented, and the description adds nothing param-specific (no width limit, no format details for sale_id). 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 ('add or replace the comment of a sale') plus the exact endpoint POST /sales/comments/. No sibling in the list touches sale comments, and the leading 'WRITE:' marker immediately separates it from the many read/list siblings.

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

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

The add-or-replace semantics are clear, which implies when to use it, but there is no explicit 'use this instead of X' or precondition guidance (e.g. that the sale must exist or be open/closed). 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 only the underlying endpoint (GET /stock_available/all_wh) and the filter dimensions; it omits the notable behavioral trait that large replies are truncated by the server and must be paged (only visible 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?

Two short sentences with the filter capability front-loaded and no wasted text. The trailing raw endpoint is marginally useful but not a distraction.

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

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

For an 8-optional-parameter read-only listing with no output schema, the description is adequate but thin: it does not describe the shape of the returned rows (per product/variant per warehouse, fields returned) or the truncation/pagination behavior an agent must handle. It covers what is queryable but not what comes back.

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 with ranges, defaults and cross-references to list_brands/list_categories/list_suppliers. The description restates the filter categories but adds no syntax or semantics beyond the schema, 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+resource: available stock per product and variant across warehouses, plus the supported filter dimensions. It implicitly distinguishes itself from hiboutik_stock_by_product and hiboutik_stock_by_warehouse via 'across warehouses', but never names those siblings, so an agent must infer the distinction.

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 guess this is the broad per-warehouse stock listing, but there is no explicit when-to-use versus hiboutik_stock_by_product / hiboutik_stock_by_warehouse, and no stated prerequisites or conditions.

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, openWorldHint=true, and destructiveHint=false, so safety is covered. The description adds useful return granularity (per variant and warehouse, plus alert level), but does not mention error behavior, auth needs, 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 compact sentences with the key scope front-loaded. The endpoint is extra but harmless and the description contains no filler.

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

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

For a simple one-parameter read tool with annotations covering safety and no output schema, the description gives a useful high-level account of the returned stock dimensions. It could still be more complete about response structure, but it is sufficient to call 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 description coverage is 100%, and the single product_id parameter is already documented in the schema. The description reinforces that the tool is scoped to one product but adds no further meaning about the identifier format or source.

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 resource and scope: available stock for one product, broken down per variant and warehouse, including the alert level. This clearly distinguishes it from warehouse-wide siblings such as hiboutik_stock_by_warehouse and hiboutik_stock_all_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?

Usage is implied by 'one product': an agent can infer this is the tool for a single product's stock. However, the description never explicitly says when to use it instead of warehouse-level stock tools or product lookup 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, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying API route (GET /stock_available/warehouse_id/{warehouse_id}), but says nothing about pagination, server-side truncation of large replies, or result shape — all of which live only 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?

Two compact clauses, scope front-loaded, zero filler. The API route is the only mildly redundant element but it is short and aids traceability.

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 nine-parameter filtered read with no output schema, the description plus the fully-documented schema covers what an agent needs to call it correctly, and 'per product and variant' signals the result granularity. Missing is any note that large responses are truncated and paginated via next_offset, which matters at limit up to 250.

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 nine parameters (limit, offset, warehouse_id, brand/category/supplier filters, archived flag, references) is already documented with cross-references to the list_* tools. The description adds only 'optionally filtered', which does not extend meaning beyond the schema.

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

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

States a specific verb+resource ('Available stock per product and variant') plus a hard scope ('in one warehouse'), which is enough to separate it from hiboutik_stock_all_warehouses and hiboutik_stock_by_product without opening either schema. The endpoint line reinforces that this is a single-warehouse read.

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?

'Optionally filtered' implies you call it when you want a scoped stock listing, but the description never names the alternatives (stock_all_warehouses, stock_by_product) or states the condition that selects one over another. 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 destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description reinforces this with 'it overwrites the current value' and reveals the underlying PUT endpoint, but adds nothing about permissions, error behavior, or return values beyond what annotations imply.

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

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

A single compact sentence with 'WRITE:' front-loaded to signal the mutation immediately. The attribute enumeration partly repeats the schema enum, which is minor waste but keeps the definition short overall.

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 three fully documented required parameters, rich annotations, and no output schema required, the description covers what an agent needs to invoke it. The only mild gap is expected error or permission behavior for a destructive single-field write.

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 three parameters are already documented, including the gender codes and the empty-string-clears rule. The description's attribute list largely duplicates the schema enum; the gender value mapping is a small helpful addition but not compensating for any gap.

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?

Uses a specific verb ('WRITE: change ONE attribute') plus the resource ('customer') and even enumerates the addressable attributes. It is clearly distinguishable from hiboutik_create_customer and hiboutik_get_customer by the single-attribute mutation scope.

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

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

The 'change ONE attribute' framing and the overwrite warning give clear usage context for picking this over create_customer or a broader update. It stops short of explicitly naming a sibling or a when-not condition, so it lands just below the top.

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