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

Annotations flag destructiveHint and readOnlyHint, but the description adds critical behavioral detail: the response body is undocumented and returned verbatim, and the cancellation may result in a pending_cancel state. This goes beyond the annotations and helps the agent understand potential asynchronous behavior and the need for verification.

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 focused sentences pack in the endpoint, optional parameter, response caveat, and verification step. Every sentence contributes new information without fluff, and the structure is front-loaded with the core action.

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

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

For a destructive, side-effect-producing tool with no output schema, the description covers the essential points: what it does, the ambiguous response, and a concrete alternative to confirm the result. This is sufficient for an agent to invoke and react appropriately.

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 both parameters described. The description only reiterates that reason is optional, which is already evident from the required list in the schema. No additional semantic value is added 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 clearly states the tool cancels an existing order, with a specific verb and resource. It distinguishes from sibling tools like create_order and get_orders_state by explicitly naming the cancellation action and including the HTTP endpoint.

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

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

The description implies usage for cancelling orders and provides clear follow-up guidance: verify the outcome with get_orders_state, expecting canceled or pending_cancel. It does not explicitly exclude alternative tools or state when not to use, but the verification step serves as practical 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?

Beyond annotations (readOnly=false, etc.), the description discloses critical behaviors: 100-item limit, undocumented key names inside nested maps, no list/delete endpoint, and verbatim passthrough of undocumented response body. This adds substantial value.

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

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

Three sentences: purpose, key constraint, and essential warnings. Every sentence earns its place with no fluff. Front-loaded with the primary action.

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?

Despite no output schema, the description explains the undefined response (2xx = success, returned verbatim) and covers limitations (key names, no list/delete). This is complete for a create tool with known upstream gaps.

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 covers 100% of parameters and describes them as string→string maps. The description adds the crucial warning about undocumented key names and 'passed through verbatim', reinforcing and extending schema meaning beyond 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?

The description clearly states the verb 'Creates' and the resource 'per-store product discounts', includes the endpoint path (POST /b2b/v1/discounts/create), and distinguishes it from siblings like create_products and create_order by specifying per-store product discounts.

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 use for creating discounts but does not explicitly discuss when to choose this over alternatives or when to avoid it. The caveat about undocumented key names is caution, not tool-selection guidance.

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

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

Annotations only flag high-level traits (readOnly=false, etc.). The description adds critical behavioral detail: all money fields are decimal strings, the response is undocumented and returned verbatim, and order state must be tracked via get_orders_state because get_order does not return it.

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

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

Four sentences; each delivers a distinct fact: action+endpoint, order_id/body-share, money-format, response, and state-tracking. No wasted words and critical details are front-loaded.

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

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

Despite the tool's complexity (10 params, nested objects, no output schema), the description covers the key non-obvious information needed for correct invocation: money string format, opaque response, how to follow up on state, and the client-supplied order_id. It fully compensates for absent output schema and enriches annotations.

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 covers 100% of parameters with descriptions, so baseline is 3. The description adds minimal new parameter-level meaning beyond what's in the schema; 'All money fields are decimal strings' and 'You supply the order_id' reinforce but don't substantively extend the schema's per-field descriptions.

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 verb+resource: 'Creates an order on the Yango Tech platform (POST /b2b/v1/orders/create).' The mention of order_id supply and the shared body shape with updates distinguishes creation from update operations, and sibling tools like cancel_order/get_order.

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

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

Provides explicit post-creation guidance: 'track progress with get_orders_state (get_order does NOT return the state)' — a clear when-to-use alternative. It also clarifies the order_id is client-supplied, but it doesn't exhaustively contrast with all sibling tools (e.g., cancel_order or update-like flows).

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?

Beyond annotations (readOnlyHint=false), the description discloses the batch limit, the POST endpoint, the requirement that custom_attributes include specific fields, pass-through of extra keys, and that the response body is undocumented and returned verbatim. This adds useful operational context without contradicting annotations.

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

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

Three sentences, each earning its place: purpose and batch limit, input shape and required attributes, and response behavior. Front-loaded and clearly structured.

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 has no output schema, so the description appropriately explains the response (undocumented, 2xx = success, verbatim). It also covers the batch limit, required custom attribute keys, and pass-through, giving a complete picture for selection and 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?

Schema description coverage is 100%, so the baseline is 3. The description repeats the required custom_attributes and pass-through behavior already present in the schema, adding no new parameter-level semantics.

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

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

The description opens with 'Creates (or upserts) products in the catalog' — a specific verb, resource, and write/update semantics. It further distinguishes itself from sibling query_products by noting the input shape matches what query_products returns, clarifying the relationship between the two tools.

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?

Clear context is provided: this tool is for creating or updating products in the catalog, with a batch limit of 100 per request and specific required custom attributes. Although no explicit exclusions or alternatives are named, the purpose and batch nature make the usage scenario 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 and destructiveHint=false, covering the safety profile. The description adds the critical behavioral caveat that the response excludes order state, and notes the alternative for that data. It also reveals the underlying HTTP endpoint, providing extra context beyond annotations.

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

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

The description is two sentences, each earning its place: the first states the resource and contents, the second warns about the missing state and directs to the sibling tool. No filler or unnecessary 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 single-order retrieval with one parameter, the description covers what the response contains, what it omits, and the alternative for the omitted data. Combined with the rich annotations and simple schema, the agent has enough context to select and invoke it correctly.

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

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

The input schema fully documents order_id with a clear description ('the client-side id the order was created with'), achieving 100% schema description coverage. The tool description doesn't add further parameter semantics, but the schema already carries the burden, so the baseline score of 3 is appropriate.

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

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

The description clearly states it returns details of a single order and lists the included fields (cart, delivery_address, payment_type, store_id, create_time). It also distinguishes itself from get_orders_state by explicitly noting that order state is not included, differentiating it from the sibling tool.

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

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

The description implies this tool is for retrieving full order creation details, and explicitly points to get_orders_state for tracking state. While it doesn't enumerate all alternative tools, it names the key alternative for the missing state field, giving clear context for when to use this tool vs. get_orders_state.

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, openWorldHint, and idempotentHint, and the description adds substantial behavioral context: per-order query_result with unknown IDs handled in the response rather than as HTTP errors, a list of known states, and explicit open-endedness. This goes beyond annotation signals.

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 front-loaded with the core purpose, then presents the return format, error semantics, and state list in a compact, organized manner. Every sentence carries useful information with no waste.

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

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

Despite having no output schema, the description fully explains the return shape, per-order error handling, and the range of possible states. Combined with clear annotations and a simple single-parameter schema, nothing critical is missing.

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

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

Schema coverage is 100%, and the schema already documents the 'orders' parameter with its type and client-side ID usage. The description adds context about batch behavior and unknown IDs, but does not add parameter syntax or format details, so baseline 3 is appropriate.

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

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

The description clearly states the tool does 'Batch order tracking' with a specific verb and resource, and names the endpoint. It distinguishes from siblings by emphasizing batch semantics, contrasting with singular get_order and other order-related tools.

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

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

The batch nature implies use for multiple order lookups, and the context distinguishes it from single-order tools like get_order. However, it lacks an explicit 'use this when' or alternatives statement, so not a full 5.

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

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

The description adds valuable context beyond the annotations: it specifies the exact return format and notes that price may be a number or string, requiring decimal handling. Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the description's added behavioral details earn a solid score.

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

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

Two sentences, no fluff. The first sentence states the purpose and endpoint; the second gives the return structure and a crucial type caveat. Every word 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?

Despite no output schema, the description provides the full return format and a type caveat. Combined with the schema (parameter description) and annotations (safety profile), it gives an agent enough to use the tool correctly. Could mention limitations (e.g., max price list count) but not essential.

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 only parameter (pricelist_ids) is fully described in the schema as 'Price-list ids from query_price_lists.' The description does not add any meaning beyond that, so it matches the baseline 3 for high schema coverage. No new parameter semantics are introduced.

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 the tool's function: retrieving product prices for one or more price lists. It includes the endpoint (POST /b2b/v1/prices/get) and return shape, making it specific and distinct from sibling tools like query_price_lists (lists price lists) and set_prices (writes prices).

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 phrase 'for one or more price lists' — the tool is used when you need prices for specific price lists. However, there is no explicit guidance on when to use it over alternatives, no exclusion criteria, and no mention of when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals important response behaviors: receipt_type values, items as a map keyed by item ID, decimal strings for amounts, and conditional PII inclusion via client_fields. This adds substantial context beyond what annotations provide.

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

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

Two dense sentences with zero fluff. The first sentence states purpose and constraint; the second details return structure and PII handling. Every clause adds value, and the structure is front-loaded with the verb and resource.

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?

Given there is no output schema, the description fully specifies the response shape, type details, and PII behavior. It also covers parameter constraints, making it a complete reference for invoking the tool correctly. Annotations mitigate the need for further safety/transaction details.

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%, but the description adds the critical constraint 'pass exactly one of the two' and clarifies that client_fields controls PII inclusion, which is not fully captured in the schema alone. This goes beyond simply restating parameter descriptions.

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 it retrieves fiscal receipts by receipt id OR order id, which distinguishes it from sibling tools like get_order and query_order_events. The specific endpoint and return type further clarify its 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?

It explicitly instructs to pass exactly one of the two IDs, which is a strong usage rule. It does not explicitly name alternatives or when-not-to-use, but the context makes it clear this is for fiscal receipt retrieval, not general order data.

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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds crucial behavioral details: the exact endpoint, the response shape with optional fields, and the fact that status values are not enumerated upstream. This gives the agent a realistic expectation of the output and potential variability.

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 concise, using two sentences to convey scope, response shape, and integration hints. Every sentence adds value, and the front-loaded 'All stores' immediately clarifies the tool's function.

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 fully specifies the return format and key semantics (store id, status). It also accounts for the open-world hint by noting status values are not enumerated, making the tool safely usable despite incomplete API documentation.

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

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

The tool has zero parameters, so the baseline is 4. The description reinforces 'no parameters' and explains what the returned store id represents, which is helpful context beyond the empty 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 clearly states the tool lists all stores (darkstores) for the retailer, with the verb 'list' appearing in the title. It also distinguishes itself from siblings by noting the store id is used by other tools, making its purpose 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?

The description identifies the endpoint and explicitly states no parameters are required, which signals when to call it. It also notes that the store id is used by create_order, update_stocks, and create_discounts, implying this is the prerequisite tool for those operations. However, it does not explicitly mention exclusions or alternatives, though none exist among siblings.

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

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

Annotations already declare the operation as read-only, idempotent, open-world, and non-destructive. The description adds substantial behavioral context beyond those hints: it details the exact return shape, enumerates event types (state_change, new_order, receipt_issued), and clarifies that the feed is continuous and requires repeated polling with the returned cursor. This goes well beyond the annotations.

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

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

The description is three sentences, front-loaded with the tool's purpose and HTTP endpoint, followed by the return shape and then usage guidance. Every sentence provides necessary information without fluff. It is compact yet rich enough to stand alone without an 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?

For a one-parameter tool with no output schema, the description is remarkably complete. It explains the return structure, enumerates event types with their nested fields, and gives a clear pagination/polling loop. Together with the annotations and schema, an agent has everything needed to invoke and interpret results 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?

With 100% schema description coverage, the baseline is 3. The schema already explains that the cursor is opaque, should be omitted for the first page, and that exhaustion is indicated by a page with fewer items than limit. The description re-iterates the cursor usage and adds the 'continuous feed' nuance, but does not substantially add meaning beyond the schema's own parameter description.

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 identifies a cursor-based order event feed with a specific verb ('Poll'), a resource ('order event feed'), and a scope ('new orders, state changes and issued receipts'). It distinguishes itself from sibling getters like get_order, get_orders_state, and get_receipt by framing the operation as a continuous feed rather than a direct lookup.

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 concrete usage instructions: omit cursor for the first call, keep passing the returned cursor, and poll again later with the last cursor. It implies continuous polling context, but it does not explicitly state when to prefer this tool over siblings such as get_orders_state or get_receipt, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds essential behavioral details beyond annotations: cursor-based pagination, exhaustion condition, and the exact response shape with active|removed status. This is more than the baseline expectation, though it stops short of disclosing ordering 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?

Three dense sentences deliver the tool's purpose, usage pattern, response shape, relationships to other tools, and fallback alternatives. No wasted words; each sentence earns its place and the key information is front-loaded.

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

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

With only two parameters and no output schema, the description fully covers the input semantics, output shape, pagination behavior, and relationship to sibling tools. It also points to raw_request for untooled endpoints, making the context complete within the tool ecosystem.

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 both limit and cursor already described, so the baseline is 3. The description adds meaningful semantics by explaining how they interact: cursor comes from previous response, omit for first page, and iteration ends when page size is fewer than limit. This ties the parameters to the pagination pattern beyond the schema's individual descriptions.

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 it's a cursor-based feed to list price lists, the API's only way to list them. It distinguishes itself from sibling tools by noting that IDs feed get_prices and set_prices, and that related endpoints without a dedicated tool are reachable via raw_request.

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

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

Explicitly says this is the only way to list price lists and explains how to obtain a full snapshot by iterating until a page has fewer items than limit. It also directs users with needs for related endpoints to raw_request, providing clear when-to-use and alternative 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses pagination exhaustion behavior, the opaque cursor mechanics, and the structure of products and custom_attributes. It also notes that markCountUnitList is open-ended and that the server-side maximum for limit is undocumented, providing valuable operational context.

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

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

The description is dense but highly efficient. Every sentence earns its place: it states the feed type, API endpoint, pagination rule, and enumerates the full product structure. There is no redundancy or fluff, and the information is front-loaded with the most critical usage 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?

Given there is no output schema, the description thoroughly explains the return shape, custom_attributes details, and how to iterate for a full snapshot. It covers pagination behavior, field semantics, and open-ended values, making it complete for a developer to invoke 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?

The input schema already describes both parameters with 100% coverage, including defaults and pagination behavior. The description does not add significant new parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies a specific verb ('query') and resource ('product catalog / product-updates feed'), and includes the exact API endpoint. It distinguishes this tool from siblings like query_price_lists by focusing on product data and cursor-based pagination.

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 provides clear usage context: use this cursor-based feed to build a full snapshot by iterating until a page returns fewer items than the limit. However, it does not explicitly mention alternatives or when not to use it (e.g., when creating products), leaving some ambiguity relative to sibling 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 read-only, idempotent, and non-destructive behavior. The description adds valuable context about pagination mechanics, shelf_type values being open-ended, and the sellable stock hint. This goes beyond annotations without contradicting them.

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 dense but every sentence conveys necessary information: endpoint, response shape, pagination rule, known values, and practical guidance. It is not overly verbose, though the long list of shelf_type values could be shortened, but it serves an open-world hint.

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?

Despite lacking an output schema, the description defines the response format and pagination exhaustion condition. Combined with the detailed schema and annotations, the tool is fully specified for correct invocation. No significant gaps remain.

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 input schema already provides comprehensive descriptions for both parameters (limit and cursor), including default values and usage. The description does not add further semantic detail beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: a cursor-based stock feed across stores, with a specific endpoint. It distinguishes itself from siblings like query_products and get_stores by focusing on stock levels and pagination.

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

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

It gives explicit instructions on how to paginate using the cursor and when to stop (when a page has fewer items than limit). It also notes that sellable stock normally lives on shelf_type 'store', which guides practical usage. However, it does not explicitly contrast with alternative tools, though the resource is clear enough.

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?

While annotations already indicate destructive and non-read-only behavior, the description adds important context beyond them: it warns 'this tool can perform writes' and discloses that '5xx/network errors are never retried'. It also clarifies that every endpoint uses POST, which is a behavioral trait not covered by annotations.

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

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

The description is front-loaded with the purpose ('Escape hatch') and packs essential usage, examples, and cautions into three sentences. The list of endpoint patterns, though lengthy, earns its place by clarifying scope.

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 raw API tool with no output schema, the description covers the when, how, and safety considerations comprehensively. It addresses method (POST), path format, body, retry behavior, and write risk, making it self-sufficient for agent selection and 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?

Schema description coverage is 100%, so baseline is 3. The description echoes the path example and body object but adds no new meaning beyond the schema's own descriptions, which already detail relative path usage and default JSON body.

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 identifies the tool as an 'escape hatch' for direct calls to any Yango Tech Retail B2B endpoint, with a specific verb ('call') and resource ('endpoint'). It lists example paths that lack dedicated tools, distinguishing it from sibling tools.

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

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

Explicitly states when to use it: 'for paths without a dedicated tool', and provides concrete examples. It also instructs on usage ('pass a relative path like... and the body object') and cautions about non-retry behavior for 5xx/network errors.

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?

Beyond the annotations, the description discloses several behavioral traits: the 100-item limit, decimal string format, price_per_quantity default, undocumented response body, and lack of a delete endpoint. This adds significant value over the annotation flags.

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 sentences long, front-loaded with purpose, and every sentence provides essential operational information. There is no redundant or filler content.

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 tool with no output schema, the description covers the request limit, data format, default behavior, response handling, and API limitation (no delete). This is sufficient for an agent to understand what to expect.

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?

All parameters are fully described in the schema (100% coverage), so the description adds little new semantic information. It reiterates the decimal string format and the default for price_per_quantity, but these are already present in the schema.

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

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

The description clearly states the tool's function: 'Sets product prices in price lists' and provides the specific endpoint. It is unambiguous and distinct from siblings like get_prices, which is a read operation.

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

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

The description provides useful context (max 100 per request, no delete endpoint) but does not explicitly state when to use this tool versus alternatives, nor does it mention when not to use it. Usage is implied rather than explicitly guided.

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

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

Annotations already flag write/non-idempotent behavior, and the description adds concrete details not present in annotations: exact POST endpoints, per-request item cap of 1000, undocumented response body returned verbatim with 2xx meaning success, and a recommendation to verify via query_stocks. No contradictions with annotations.

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

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

The description is three sentences with the main action front-loaded. Every sentence adds essential operational detail—mode behavior, endpoints, limits, response handling, and verification—without any filler or redundancy.

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

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

For a write tool with no output schema, the description covers the essential operational facets: two modes, per-store scope, response passthrough, success condition, and follow-up verification. It could also address error handling or auth, but given annotations and sibling context, it is sufficiently 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%, so baseline is 3, but the description adds value by explaining the default for 'mode' and mapping each mode to its endpoint and intended use case. It also reinforces the 1000-item limit already in the schema, providing marginal additional meaning.

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

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

The description opens with 'Writes stock quantities for one store,' a specific verb+resource that clearly differentiates it from read tools like query_stocks. It further distinguishes the two modes (modify vs initialize) with distinct endpoints, making the tool's purpose 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?

The description provides explicit mode selection guidance: modify (default) for regular updates and initialize for first-time stock load. It also directs the agent to verify results with query_stocks, indicating the appropriate companion tool. However, it does not explicitly state when not to use this tool versus other alternatives.

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