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

Annotations already indicate a non-read-only, non-destructive operation. The description adds behavioral context by stating the effect (increasing on-hand quantity), the requirement that the record must exist, and that adjustmentReasonName must match a configured reason. However, it does not discuss side effects, error cases, or idempotency beyond what annotations provide, so a 4 is appropriate.

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 well-structured: a clear one-sentence purpose, a brief identifying instruction, an Args list, and a Returns line. It is not excessively long, but the Args section largely duplicates schema information, which is slightly redundant. Overall, it is organized and front-loaded, earning a 4 rather than 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?

The tool has five parameters, no output schema, and is a mutation operation. The description covers the main inputs, the requirement to use an existing record, and the return value as 'the operation result from Logiwa,' which is vague. It lacks detail on error handling or what the result contains, leaving some gaps for such a complex 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?

The input schema already documents all five parameters with descriptions, so coverage is 100%. The description mostly repeats the schema content, but adds a useful constraint ('adjustmentReasonName must match a configured reason') not present in the schema. This is a modest addition, consistent with a baseline 3 when schema does the heavy lifting.

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 increases the on-hand quantity of an existing inventory record by a given quantity. This specific verb+resource combination distinguishes it from sibling tools like logiwa_adjust_inventory or logiwa_remove_inventory, and the reference to 'existing inventory record' clarifies it is not a creation 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 clear context for use: it increases quantity on an existing record and instructs the user to identify the record via inventoryIdentifier (UUID) from logiwa_list_inventory. It does not explicitly mention alternatives or when not to use this tool, but the 'increases' wording implies it is for increments specifically. Lacks explicit exclusions, hence not a 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 reveals that the operation overwrites the counted quantity, which is a concrete destructive behavior beyond the general destructiveHint annotation. It also notes that adjustmentReasonName must match a configured reason and that the operation returns the Logiwa result. These details add meaningful behavioral context not fully captured 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 a clear purpose, followed by a prerequisite and a structured argument list. It is somewhat redundant with the schema but remains efficient and well-organized. No filler sentences.

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

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

The tool has 5 parameters, a nested additional_fields object, no output schema, and destructive annotations. The description covers purpose, prerequisites, overwrite behavior, the reason constraint, and return value. The schema covers the remaining parameter details, making the overall context adequate for an agent to invoke it correctly.

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

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

The input schema covers all parameters with descriptions, providing a high baseline. The description adds value by specifying the inventoryIdentifier should come from logiwa_list_inventory and that adjustmentReasonName must match a configured reason, which is not in the schema. The argument list largely repeats schema, but the extra constraints justify a slight bump.

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 'Adjusts the on-hand quantity of an inventory record to a new value' and emphasizes 'overwrites the counted quantity.' This distinguishes it from sibling tools like logiwa_add_inventory or logiwa_remove_inventory, and it specifies the record source (logiwa_list_inventory).

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 context by saying the adjustment sets a new value and overwrites the existing quantity, making it clear this is for absolute updates. It also instructs to identify the record via inventoryIdentifier from logiwa_list_inventory. However, it does not explicitly contrast with add/remove/transfer alternatives, so it's clear but lacks explicit exclusions.

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

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

Annotations already cover destructiveHint=true and readOnlyHint=false, so the description's 'Destructive state change' adds little new information. It does mention the return value ('Returns: the cancellation result'), which is useful, but overall behavioral disclosure relies heavily on annotations rather than description-specific 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?

The description is compact and well-structured, split into purpose, args, return value, and a destructive-state note. Every sentence adds useful information with no filler or redundancy, making it easy for an agent to parse quickly.

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 tool with 8 parameters, no output schema, and complex identification requirements, the description provides a coherent identification scheme and states the return outcome. It lacks detailed cancellation semantics (e.g., status changes or prerequisites), but given the annotations cover destructive and idempotent hints, the description is sufficient for most selection and invocation needs.

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 only 25% schema description coverage, the description compensates by clarifying the roles of key identifiers: it explains that rmaNumber is the RMA to cancel, that shipmentOrderCode and shipmentOrderIdentifier are alternatives, and that warehouseIdentifier/clientIdentifier are used. It also points to additional_fields as an escape hatch, adding meaning beyond the schema's bare field names.

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 with a specific verb ('Cancel') and resource ('return order'). It distinguishes from the sibling tool logiwa_cancel_shipment_order by emphasizing the return order context, making the 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 explains how to identify the return order (via rmaNumber and related shipment/warehouse/client) but does not explicitly state when to use this tool versus alternatives like logiwa_cancel_shipment_order. There is no guidance on exclusions or when-not-to-use, leaving usage largely implied from the tool name.

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

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

The description discloses that this is a destructive state change, which aligns with the destructiveHint annotation, and mentions the return result. However, it adds little beyond the annotations, and the additional_fields note is more parameter semantics than behavioral 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 compact, front-loaded with the main action, and uses a clear Args/Returns structure. Every sentence contributes value, including the note about cross-checking and additional_fields.

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

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

Given no output schema, the description covers the required identifier, optional parameters, and the return value at a high level. It lacks details about preconditions (e.g., cannot cancel shipped orders) and consequences beyond 'destructive', but the annotations provide safety context.

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 description explains each parameter's purpose, including clarifying that shipmentOrderCode is for cross-checking and listing example additional_fields. This goes beyond the schema, which omits a description for shipmentOrderCode.

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 'Cancel a shipment order by its identifier (UUID)' with a specific verb and resource, clearly distinguishing it from siblings like cancel_return_order and get_shipment_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?

The description clearly implies when to use this tool (to cancel a shipment order) and provides clear context. It does not explicitly mention alternatives or exclusions, but the tool name and sibling list make the intended scope obvious.

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 signal readOnly=false, openWorld=true, and idempotent=false. The description adds that additional_fields are merged verbatim into the request and that the return is typically the new product identifier/status, which goes beyond annotation defaults. It does not mention auth or duplicate-SKU behavior, but the annotation coverage lowers that burden.

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

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

Four short sentences front-load the purpose, then cover required fields, lookup guidance, extension, and return value with no filler. Every sentence contributes actionable 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 tool with 17 parameters, nested packingSettings, and no output schema, the description provides required fields, cross-tool lookup guidance, an extension mechanism, and expected return shape. It could be more precise about duplicate-SKU behavior and exact response format, but it is largely sufficient for selecting and invoking the tool.

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

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

Schema description coverage is only 59%, so the description compensates by listing all seven required fields and directing agents to logiwa_lookup for resolving key values. It also explains the additional_fields escape hatch for untyped Logiwa fields. Optional fields are not individually detailed, but schema descriptions partially cover them.

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 'Create a new product (SKU) in Logiwa,' clearly identifying the action and resource. This distinguishes it from sibling tools such as logiwa_update_product and logiwa_get_product.

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 clearly frames the tool for new-product creation and provides actionable guidance to use logiwa_lookup to resolve clientIdentifier and currency/pack-type values. It does not explicitly contrast with update_product for existing SKUs, but the 'new product' framing gives sufficient 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 indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds that it returns 'the create response (new PO identifier / status)' and requires certain fields, but does not elaborate on side effects or error behavior. It doesn't contradict annotations, but adds limited additional behavioral 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 concise and well-structured: it leads with the action, then lists required fields, gives resolution guidance, and ends with return value. Every sentence earns its place without unnecessary fluff.

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 the tool's complexity (11 parameters, nested objects, no output schema), the description covers required fields, resolution strategy, the return payload, and the additional_fields escape hatch. It's well-aligned with the schema and provides sufficient context for an agent to invoke it correctly.

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

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

Schema coverage is high (82%), but the description adds meaning by listing required fields, advising to resolve certain identifiers via lookup tools, and explaining that 'Other fields via additional_fields' serves as an escape hatch. This goes beyond the schema for those parameters.

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 'Create a new purchase (inbound) order,' a specific verb+resource that clearly distinguishes it from sibling tools like create_shipment_order and create_return_order. It also lists required fields and the return value, reinforcing the tool's purpose.

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 explicitly instructs to 'Resolve client/warehouse/type/currency with logiwa_lookup and logiwa_list_warehouses,' providing clear guidance on prerequisites and alternative tools. It doesn't explicitly state when not to use the tool, but does offer context for field resolution.

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 indicate readOnly=false and destructive=false, and the description adds that the tool returns 'the create response (new return order identifier / status).' It also clarifies required fields and the need to link to an original sale, which is useful behavioral context beyond the raw 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 concise and front-loaded: it states the purpose first, then required fields, linking guidance, a pointer to a sibling tool, and the return value. Every sentence earns its place with no unnecessary noise.

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 the tool has 12 parameters, a nested object, no output schema, and moderate schema description coverage, the description covers the most important operational details: required fields, product line structure, linking to original sale, and expected return value. It could be expanded with examples or more explicit field semantics, but it is sufficient for a competent agent.

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

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

Schema description coverage is only 50%, but the description highlights the critical requirements: rmaNumber, returnOrderProductLineList with each line needing productIdentifier + requestedQuantity. It also explains the purpose of shipmentOrderCode/shipmentOrderIdentifier and additional_fields, adding meaning beyond the schema's bare property definitions.

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 tool name and title clearly state 'Create Return Order', and the description opens with 'Create a return order (RMA).' This is a specific verb+resource pairing that directly distinguishes it from siblings like logiwa_cancel_return_order or logiwa_list_return_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?

The description states required fields (rmaNumber, returnOrderProductLineList) and explains how to link to the original sale using shipmentOrderCode or shipmentOrderIdentifier. It also directs users to logiwa_list_products for resolving product identifiers. While it doesn't explicitly name alternatives or exclusions, the context for when to use this tool is clear.

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 indicate readOnlyHint=false and openWorldHint=true. The description adds value by listing required fields, explaining the additional_fields mechanism, and stating the return value ('new order identifier / status'). This goes beyond the 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 three sentences, front-loaded with the primary action, and each sentence adds critical information (required fields, lookup resolution, return type). No filler or redundancy.

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

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

For a 15-parameter tool with nested objects and no output schema, the description covers required fields, additional_fields, and return value. It does not address error cases or duplicate-code behavior, but given schema richness and openWorldHint, this is adequate.

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 80%, so the baseline is 3. The description adds meaningful guidance by instructing to resolve type/warehouse/currency values via logiwa_lookup, which is not in the schema. It also clarifies that customer/shipmentAddress/billingAddress should be objects matching the Logiwa API, reinforcing schema 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 opens with 'Create a new shipment (outbound) order,' which uses a specific verb and resource. It clearly distinguishes from sibling tools like logiwa_create_purchase_order and logiwa_create_return_order by naming the order type (shipment/outbound).

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 context for when to use this tool (creating a shipment order) and includes actionable guidance such as 'Resolve type/warehouse/currency values with logiwa_lookup' and 'Any other fields go in additional_fields.' However, it does not explicitly mention when not to use it or compare with 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 the tool as read-only, idempotent, and non-destructive, so the description need not repeat those. It adds meaningful behavioral context by specifying the return content (SKU, name, description, pricing, packing settings, custom fields, flags) and the response_format behavior (markdown vs json). This goes beyond the structured fields.

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

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

The description is compact and front-loaded, with a clear purpose sentence followed by labeled Args and Returns sections. Every line serves a purpose; there is no redundancy or irrelevant 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 simple two-parameter get tool with annotations and a complete schema, the description is fully sufficient. It explains the return value and parameter behavior, and the schema covers required fields and enums. 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?

Schema coverage is 100%, so baseline is 3. The description enriches both parameters: it cross-references the identifier's origin (from logiwa_list_products) and clarifies that response_format defaults to markdown for a human-readable summary versus json for the full structured payload. This adds value over the schema 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 the tool gets the full detail of a single product by UUID, with a specific verb ('Get'), resource ('product'), and scope ('single product by its Logiwa identifier'). This distinguishes it from siblings like logiwa_list_products (which lists many) and logiwa_get_shipment_order (a different entity).

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 the appropriate usage context by specifying that the identifier comes from logiwa_list_products items[].identifier, guiding the user to first list products. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to infer when to use this tool.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds behavioral specifics: 'full detail (including line items)', the configurable response_format with default markdown, and the return fields (vendor, warehouse, dates, line products).

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

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

The description is compact: a one-sentence purpose, a brief args list, and a return line. It is well-structured and every sentence adds 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?

Given the 2-parameter schema, no output schema, and strong annotations, the description covers the essential aspects: what it returns, the line items, and output format. It lacks only edge-case behavior (e.g., not found), but that is not required for a simple GET-like tool.

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

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

Schema description coverage is 100%, so the schema already documents both parameters sufficiently. The description restates the params but adds only the provenance hint for identifier and confirms the default output format, which adds marginal value.

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+resource: 'Get full detail (including line items) of one purchase order by its identifier (UUID).' This clearly distinguishes it from sibling list/receive/create tools, which operate on collections or different actions.

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 mentions the identifier comes 'from logiwa_list_purchase_orders', giving a usage context. It does not explicitly name alternatives or exclusions, but it clearly implies use for single-PO detail retrieval, which is sufficient 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 indicate read-only, idempotent, non-destructive behavior. The description adds useful context about the return contents (status, addresses, line products, carrier, tracking) and the response_format options, which goes beyond the annotation coverage.

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

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

The description is compact and well-structured: one-sentence summary, args list, and return summary. Every line adds value, and the main purpose 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?

For a simple 2-parameter read tool with high schema coverage and annotations, the description covers the essential usage and return information. No output schema exists, but the described return fields are sufficient for invocation decisions.

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 descriptions for both parameters. The description adds extra value by noting the identifier comes from logiwa_list_shipment_orders and clarifying the response_format usage, which is not fully captured 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 fetches full detail for a single shipment order by UUID, using the verb 'Get' and specifying the resource exactly. It distinguishes from list/cancel/update siblings by focusing on singular detail retrieval.

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: use this to retrieve one shipment order by its UUID, and even tells the agent the identifier comes from logiwa_list_shipment_orders. It doesn't explicitly exclude alternatives, but the usage scenario is unambiguous.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds valuable context about pagination behavior and the return payload (customers with identifier, name, contact/address details), going beyond the annotations and 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?

The description is concise and well-structured: a one-line purpose, a clear argument list, and a returns summary. The Args section is somewhat redundant with the schema but is organized and easy to scan, making it useful in a tool description context.

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's no output schema, so the description's return details ('identifier, name and contact/address details') are essential and provided. It also covers pagination and defaults. For a read-only list tool with 100% schema coverage, this description is complete enough to invoke and interpret results.

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

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

Schema description coverage is 100%, so a baseline of 3 is appropriate. The description repeats each parameter in a docstring format, but does not add significant meaning beyond the schema. It does add a 'Returns' line describing output fields, which is useful since there is no output schema, but parameters themselves are fully covered by the schema.

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

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

The description states 'List customers (ship-to parties), paginated' with a specific verb and resource, and clarifies that customers are ship-to parties. This clearly distinguishes it from sibling list tools like logiwa_list_products or logiwa_list_inventory.

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 explicit guidance on when to use this tool versus other list tools. The description only states what it does and its parameters; it does not mention when to prefer it over alternatives or any exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds behavioral details about pagination, response_format options, and the fact that each record carries an inventoryIdentifier useful for mutations. This goes beyond simple safety and provides operational context, with no contradiction.

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 well-organized: opens with a clear purpose statement, then breaks down parameters, and closes with return structure. Each sentence adds value and there is no redundancy or fluff.

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?

Even without an output schema, the description defines the return shape (items[] with inventoryIdentifier, sku, warehouse, location, quantity). It also covers pagination and format options, and annotations cover safety. For a list tool of moderate complexity, this is 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?

Input schema covers 100% of the parameters with descriptions, defaults, and ranges. The description repeats the same parameter details without adding new meaning beyond what's already in the schema, so 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 lists on-hand inventory records with warehouse locations, paginated. It distinguishes itself from sibling tools like list_products and report_total_inventory by specifying the inventory scope and the inventoryIdentifier field used by mutation 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 description provides clear context by noting that inventoryIdentifier is used by add/adjust/remove tools, implying when this list tool is relevant. It does not explicitly name alternative tools for reports or aggregation, but the purpose is self-evident enough for an agent to select it appropriately.

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, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds valuable behavior context: pagination is by page index only, there is no server-side filter, and it specifies the response shape. This goes beyond the annotations and helps set expectations for output.

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 well-structured: a clear one-line purpose, then pagination behavior, then parameter summaries, then return details. It is slightly longer than strictly necessary due to overlapping with the schema, but every sentence serves a purpose, so it remains efficient.

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?

Since there is no output schema, the description fully documents the return object and item contents. It also covers pagination mechanics, filtering limitations, and the alternative tool, making it sufficient for an agent to invoke and interpret results correctly. The context provided is complete for the tool's complexity.

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 is 3. The description's arg list largely duplicates the schema's parameter descriptions, adding little beyond stating that page is 1-based and page_size has a max of 200. It does not introduce new semantic meaning for parameters that the schema already 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?

The description opens with 'List products (SKUs) in the Logiwa catalog, paginated', using a specific verb (List) and resource (products/SKUs), and clearly distinguishes itself from siblings by noting pagination and the absence of server-side filters. It also references logiwa_get_product for known identifiers, differentiating its scope from a single-product 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 explicitly states when to use this tool ('page through results to find a SKU') and when to use an alternative ('or use logiwa_get_product when you already know the product identifier'). It also explains the pagination-only behavior, giving clear guidance on how to retrieve products in the absence of search/filter capabilities.

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, idempotentHint, and destructiveHint, covering safety. The description adds meaningful behavioral context by specifying that results are paginated and by describing the return payload structure (items array with PO UUID, code, vendor, warehouse, status, dates). This goes beyond what annotations provide, 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 concise and well-structured: a one-line summary followed by an Args list and a Returns clause. Every element carries necessary information, and there is no fluff or redundancy beyond the schema repetition, which is acceptable for a standalone tool description.

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 paginated list tool with no output schema, the description is complete. It specifies all parameters with defaults, enumerates the response format options, and summarizes the fields present in each item. Given the low complexity and strong annotations, no additional context is needed.

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

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

Schema description coverage is 100%, with detailed descriptions for each parameter (page, page_size, response_format) including ranges, defaults, and enum meanings. The tool description repeats these details without adding additional semantics, such as edge-case handling or parameter interactions. Therefore, the baseline 3 is appropriate.

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

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

The description clearly states the tool lists purchase (inbound) orders and explicitly notes pagination. The parenthetical '(inbound)' distinguishes from outbound shipment orders, and the verb 'List' is specific to the collection-level operation, clearly differentiating it from sibling tools like get_purchase_order or create_purchase_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?

The description implies usage by the verb 'List' and the clarification of inbound orders, but it does not explicitly state when to use this tool versus alternatives such as get_purchase_order for a single order or create_purchase_order. There is no exclusionary guidance, but the intended use for listing multiple orders is clear from the title and description.

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, idempotentHint=true, and destructiveHint=false. The description adds behavior beyond annotations: 'paginated' behavior, 1-based page index, page size limits, and the returned fields ('identifier and name'). It also notes the response format options, giving context on output shape 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?

The description is compact: one main sentence, a concise Args list, and a one-line return type. No filler or redundant text; every element adds value. It is front-loaded with purpose.

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

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

For a simple, read-only list endpoint with no required parameters and a fully documented schema, the description plus the annotations cover all essential aspects: what is retrieved, pagination, output formats, and return shape. No output schema exists, but the description's return statement suffices.

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%; all three parameters (page, page_size, response_format) are fully described with defaults, ranges, and enums. The description's Args section largely paraphrases the schema ('records per page, 1-200 (default 20)') without adding new semantic meaning, so the baseline 3 applies.

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

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

The description opens with 'List retailers / sales channels configured in the account, paginated,' using a specific verb ('list') and clearly scoping the resource ('retailers / sales channels'). This distinguishes it from sibling list tools like logiwa_list_customers or logiwa_list_products, and the return statement confirms its purpose.

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 the tool is for retrieving account-configured retailer/sales channel data, and the pagination/formatting details clarify usage. However, it does not explicitly name alternatives or state when not to use it, so an agent must infer from sibling names; it lacks exclusion guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds behavioral context beyond these by explaining the pagination mechanism (1-based page, page_size) and the return structure (items[] with specific fields like rmaNumber, warehouse, status), which is valuable for the agent.

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 and well-structured, front-loading the purpose in the first line, followed by a clear Args list and Returns summary. Every sentence earns its place without redundancy or fluff.

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 the simplicity of the tool (3 optional parameters, no output schema), the description fully covers the core aspects: purpose, parameters, and return format. It provides enough detail for an agent to correctly invoke the tool and interpret results, and the annotations cover the safety profile, making it complete for its complexity level.

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 has 100% coverage with descriptions for all three parameters. The description's Args section essentially restates the schema information without adding new meaning. However, the Returns section clarifies what the agent can expect from the response, which indirectly helps parameter understanding but doesn't enhance parameter semantics further.

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 explicitly states 'List return orders (RMAs), paginated.' This clearly identifies the verb (list), resource (return orders), and distinguishes it from sibling tools like list_shipment_orders or list_purchase_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?

The description provides clear context that this tool is for listing return orders with pagination and different output formats. It does not explicitly mention alternatives or exclusions, but the purpose is unambiguous given the sibling tool names, so the context is sufficient without explicit when-not guidance.

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

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

The description discloses pagination behavior and return structure ('Returns: paginated { items[] } where each item includes the order identifier (UUID), code, status, warehouse, customer and dates.'). This adds value beyond the annotations, which already declare read-only and idempotent hints. It does not contradict 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 well-structured and front-loaded with the core purpose. It then concisely lists parameters and return format in a clear, scannable layout. Every sentence earns its place without unnecessary verbosity.

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 list tool with full schema coverage and informative annotations, the description is complete. It explains pagination, parameter defaults, and return fields. The lack of an output schema is mitigated by the detailed return description. No critical information 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?

The input schema covers 100% of parameters with detailed descriptions, including defaults and constraints. The description restates the parameters but adds no additional semantics beyond what the schema already provides. 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: 'List shipment (outbound / sales) orders, paginated.' The verb 'list' plus the specific resource 'shipment orders' with the qualifier '(outbound / sales)' distinguishes it from sibling list tools like logiwa_list_purchase_orders and logiwa_list_return_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?

The description provides clear context by specifying that these are outbound/sales orders, which helps differentiate from purchase and return orders. However, it does not explicitly state exclusions or alternative tools, though the parenthetical qualifier gives sufficient context for the agent to choose this tool over related list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context by specifying pagination (page and page_size), default values, and the return fields (identifier, name, contact details). This goes beyond the annotations and clarifies the output shape, which is especially helpful since there is no output schema.

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

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

The description is compact and well-structured: a one-line purpose, a bulleted Args list, and a Returns line. Every sentence serves a purpose, with no filler or repetition. It front-loads the core behavior and then provides parameter details in an easily scannable format.

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 paginated list tool with strong annotations and full schema coverage, the description is complete. It states the purpose, scope, all parameters with defaults, and the return fields (identifier, name, contact details). Since there is no output schema, the explicit return information is critical and provided. No additional behavior or edge cases need explaining for this straightforward read-only operation.

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

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

Schema coverage is 100%, with each parameter already described in detail (type, defaults, ranges, enum for response_format). The description's Args section replicates the schema almost verbatim, adding no extra semantic meaning beyond what the schema already provides. The baseline of 3 is appropriate because the description does not need to compensate for 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 'List vendors (suppliers) used on purchase orders, paginated.' The verb 'List' plus the specific resource 'vendors (suppliers)' and the scope 'used on purchase orders' distinguish it from sibling list tools like list_customers or list_products. The added scope prevents ambiguity with potentially similar entity types (e.g., retailers).

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 context by specifying that this lists vendors used on purchase orders, implying when to use it (e.g., when looking up PO-related suppliers). However, it does not explicitly mention alternatives or state when not to use the tool, so it stops short of full usage guidance. The implicit exclusion of vendors not on POs is a clear contextual hint.

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, idempotentHint, and non-destructive behavior, so the description doesn't need to restate safety. It adds useful behavioral details: pagination semantics, response_format options, and the returned fields (UUID, code, zone/group, warehouse). These details go beyond annotations and help the agent understand runtime behavior.

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

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

The description is compact and well-structured. It uses a clear 'Args:' block and a 'Returns:' line, making it easy to scan. Every sentence contributes meaningful information—purpose, parameters, and return value—without padding 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?

There is no output schema, so the description appropriately covers return values, listing the specific fields (identifier, code, zone/group, warehouse). It also covers pagination and output format controls. For a simple list operation with optional parameters, this is fully complete and actionable for an agent.

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 schema already documents all three parameters with defaults and ranges. The description's Args section largely duplicates this information. It adds a remote link to the tool's purpose ('resolve location codes') but no substantive parameter semantics beyond what the schema provides. Thus, 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's purpose: 'List warehouse locations (bins/shelves), paginated.' This distinguishes it from sibling tools like logiwa_list_warehouses, which lists warehouses (facilities), not individual locations. The verb 'List' and resource 'warehouse locations' are specific and 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 clear context by noting the tool is 'used to resolve location codes for inventory transfers and receiving.' This gives the agent a concrete scenario for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing pagination behavior (1-based pages, page_size cap of 200), response_format options, and the return composition (UUID, code, name). No contradiction 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 well-structured, starting with a clear purpose sentence, followed by an Args section and a Returns line. It is slightly redundant with the schema, but not bloated, and every section is easy to scan.

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 endpoint with rich schema and annotations, the description supplies pagination limits, output format options, and return purpose. It is sufficient for an agent to select and invoke the tool correctly without needing an output schema.

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 covers 100% of parameters with detailed descriptions including defaults and ranges. The Args section in the description mostly repeats schema content, adding little new meaning beyond quick readability, so the high-coverage 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 opens with a specific verb-resource pair: 'List the warehouses configured in the account, paginated.' It clearly identifies the scope and differentiates from sibling tools like logiwa_list_warehouse_locations and other list_* tools by naming the exact resource.

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

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

It states the return value is 'used to resolve warehouseIdentifier / warehouse code for other tools', giving concrete context for when this tool is needed. It does not explicitly name alternatives or exclusions, but the purpose is specific enough to guide selection 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 readOnlyHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavior context: it returns a list with typically an identifier and name, or a summary with counts when category is omitted, and supports markdown/json response formats. This goes beyond the annotations to clarify what the agent can expect from the call.

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

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

The description is well-structured: it opens with a clear one-sentence purpose, adds a practical usage note, then lists parameters and return value concisely. Every sentence earns its place with no repetition or fluff, and the use of a short args list keeps it scannable.

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 the tool's low complexity (2 optional params, no output schema), the description covers purpose, parameter behavior, return content, and usage context. It explains the category summary and typical entry structure, but could be more precise about the exact response format (e.g., JSON structure). Still, it is sufficiently complete for effective 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?

The input schema already provides full descriptions and enums for both parameters (category and response_format), achieving 100% schema coverage. The description repeats these values and adds little new parameter-level semantics; it mentions the optionality and default but not beyond the schema. Thus 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 states 'Fetch Logiwa reference/lookup data used to resolve names and identifiers needed by other tools' – a specific verb, resource, and purpose. It clearly delineates this lookup tool from sibling tools like logiwa_list_inventory or logiwa_create_product by focusing on reference/lookup data, and lists the exact categories handled.

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 guidance: 'Many create/update tools need a clientIdentifier, type name, or currency — use this first to discover valid values.' This tells the agent when to use the tool, though it does not explicitly mention alternatives or when not to use it. Still, the directive 'use this first' is strong and contextually clear.

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 mutability (readOnlyHint=false) and non-idempotency. The description adds that it 'records an inbound receipt' for one product line and returns 'the receipt result from Logiwa,' giving a clear expectation of the outcome. It does not discuss failure modes or side effects, but it does not contradict 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 compact and well-structured: a one-sentence summary, a brief instructional line, a bulleted list of common args, and a return note. It is easy to scan and contains no redundant or excessive text.

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

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

For a tool with 13 parameters and no output schema, the description covers the essential workflow and states the return value. However, it omits some parameters (clientIdentifier, warehouseIdentifier) and references a non-existent purchaseOrderIdentifier, leaving gaps in completeness. It is reasonably helpful but not exhaustive.

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 description clarifies the meaning of key fields like purchaseOrderCode, sku, quantity, and warehouse/warehouseLocationCode, and lists optional parameters. However, it introduces 'purchaseOrderIdentifier' which is not in the schema, and omits clientIdentifier and warehouseIdentifier, creating confusion. With schema coverage at 54%, it adds useful detail but is not fully aligned with 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 begins with a clear verb+resource: 'Receive stock against a purchase order' and explicitly scopes it to 'one product line.' This distinguishes it from sibling tools like add_inventory or adjust_inventory by tying the action to a PO, making the purpose unmistakable.

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 when to use the tool by instructing the user to identify the PO, product, warehouse, location, and quantity, which signals a receiving-against-PO scenario. However, it does not explicitly compare with alternatives (e.g., add_inventory) or state when not to use it, so the guidance is implicit rather than explicit.

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 readOnlyHint=false, so the description doesn't bear a heavy burden. It adds that the record must be 'existing' and that adjustmentReasonName must match a configured reason, but doesn't detail side effects (e.g., exceeding quantity, permissions). No contradictions.

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?

Description is compact, front-loaded with a clear purpose, followed by structured Args and Returns. 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 destructive inventory operation, it explains how to identify the record, what parameters are needed, and what it returns. However, it doesn't describe error conditions or edge cases (e.g., removing more than available), and the return is vaguely 'operation result from Logiwa' with no output schema.

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 has 100% coverage, so baseline 3. The description adds extra value by specifying that inventoryIdentifier comes from logiwa_list_inventory and that adjustmentReasonName must match a configured reason, which goes beyond the schema descriptions. The Args section mirrors schema but with useful operational context.

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?

Clearly states the operation: decreases quantity units from an existing inventory record. Uses specific verb 'Decreases (removes)' and resource 'inventory record', and distinguishes from siblings like add_inventory and adjust_inventory by specifying removal.

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 clear context: identify the record via inventoryIdentifier from logiwa_list_inventory. It implies this tool is for removing inventory, but doesn't explicitly contrast with adjust_inventory or transfer_inventory, nor state when not to use.

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 and idempotentHint, so the safety profile is covered. The description adds pagination behavior, default output format, and the return structure (ATP rows with on-hand, allocated, available quantities), which is valuable non-obvious context 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 compact and well-structured: the core purpose is stated first, followed by a brief args list, then return description. Every sentence carries useful information, and the formatting makes it easy to scan.

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 only three parameters, no output schema, and simple read-only behavior. The description adequately explains pagination, defaults, and what the returned rows contain, making it complete for an agent to use correctly.

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

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

Schema coverage is 100% and every parameter has a detailed description with defaults and constraints. The description's arg list essentially repeats schema information without adding new semantics, so it meets the baseline but does not exceed it.

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 reports available-to-promise (sellable) quantities per SKU, a specific verb+resource. It distinguishes itself from sibling report tools like total inventory by focusing on sellable quantities, and the question 'how many can I still sell?' adds a practical use case.

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 'Best for "how many can I still sell?"' provides a clear usage context. However, it does not explicitly mention when not to use this tool or name alternative tools like report_total_inventory, so it lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds behavioral context: it is paginated and returns specific fields (SKU, quantities, purchase order, date information). It does not mention potential side effects or further behaviors, but the annotations lower the burden. This is adequate with some added 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?

The description is extremely concise, front-loaded with the core purpose, and uses a clear structured format for arguments and returns. Every sentence contributes to understanding, with no fluff 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?

Despite having 3 optional parameters and no output schema, the description explains the return content, pagination behavior, and output format options. It is sufficient for an agent to know what results to expect and how to invoke the tool, though it does not describe any filtering capabilities or limitations beyond pagination. This is complete for the tool's complexity.

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 provides 100% coverage of all three parameters with descriptions, defaults, and constraints. The description's 'Args' section duplicates this information without adding new meaning. Since the schema already does the heavy lifting, a 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 states 'Historical receipt records (inbound receiving history), paginated.' This clearly identifies the tool as a report for receiving history, using specific terminology ('receipt records', 'inbound receiving history') that distinguishes it from siblings like report_shipment_history. The verb is implied ('retrieve', 'list'), but the resource and scope are 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 implies usage for retrieving historical receiving records but does not explicitly state when to prefer this tool over alternatives. It mentions 'paginated' and the return content, giving some context, but there is no exclusion or alternative guidance. A score of 3 reflects the implied usage without explicit guidance.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds pagination behavior, page/page_size defaults, and response_format options, which are useful 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?

Description is compact and well-structured: a one-line purpose, a clear Args list, and a Returns line. No unnecessary words.

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 report with three optional parameters, the description covers purpose, pagination, output formats, and return fields. No output schema exists, so the Returns line sets correct expectations.

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 all three parameters are documented with defaults and constraints. The description's Args list essentially restates the schema without adding new 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?

Description clearly identifies the tool as returning historical outbound shipment line records, using 'outbound fulfillment history' to distinguish it from the sibling 'logiwa_report_receiving_history'. The Returns line further specifies the data content.

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 'outbound fulfillment history' phrase provides clear context for when this report is appropriate versus receiving/inventory reports. It does not explicitly name alternatives or exclusions, but the sibling list provides enough differentiation.

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 mark the operation as read-only/idempotent; the description adds useful behavioral context including pagination, response format options, and the returned row structure (per SKU/warehouse with on-hand/available quantities). It does not over-claim or contradict 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 concise and front-loaded: a one-sentence summary, a bulleted Args list, and a Returns line. Every sentence earns its place; there is no redundancy or filler.

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

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

For a read-only report tool with optional parameters and no output schema, the description covers the purpose, usage context, parameter defaults, and the response shape (consolidated rows with quantities). With strong annotations, this 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?

The input schema already covers all three parameters with full descriptions and defaults (100% coverage). The description's Args section mostly mirrors the schema, adding only a slightly condensed version, so no additional semantic value 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 provides total consolidated on-hand inventory across locations and highlights the use case 'how much of each SKU do we have?'. The word 'consolidated' differentiates it from list_inventory and other inventory 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?

It provides a clear use case with 'Best for' and indicates that it's paginated, but does not explicitly specify when not to use it or name alternative tools like logiwa_list_inventory.

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 specify readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is known. The description adds the outcome 'completes fulfillment' but does not disclose potential side effects like inventory changes, reversibility, or prerequisites (e.g., order must be in a certain state). 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 compact and well-structured: a one-sentence purpose, a brief Args list, and a one-line Returns note. No redundant information, and the most important content (the action) is front-loaded. Every sentence provides value.

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 mutation with annotations covering idempotency and safety, the description gives the core information: action, parameter, and return value. It could improve by mentioning prerequisites or irreversible consequences, but given the simplicity and existing annotations, it is largely complete. However, the Returns line is vague ('the ship operation result from Logiwa') without a schema, and no usage guidance is included.

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 describes the parameter fully: 'Shipment order UUIDs to mark as shipped (required, >=1).' The description restates the parameter in the Args section as 'one or more order UUIDs to ship,' which adds minimal clarification (e.g., that they are UUIDs) but doesn't materially exceed the schema's own description. 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 clearly states the tool's action: 'Mark one or more shipment orders as shipped (completes fulfillment).' The verb 'mark as shipped' directly identifies the operation on shipment orders, and the parenthetical 'completes fulfillment' provides additional domain context. This clearly distinguishes it from sibling tools like cancel, create, or update.

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 context that this tool is for shipping orders and completing fulfillment, which implies its usage. However, it does not explicitly mention when not to use it or point to alternatives among the sibling tools, such as cancel_shipment_order or update_shipment_order. Thus it meets the 'clear context, no exclusions' level rather than the top tier.

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=false, destructiveHint=false, and idempotentHint=false, so the description is not burdened with stating those. It adds useful context that codes or UUIDs are accepted and that additional_fields can be used for extra API fields. However, it does not disclose potential side effects like how the source stock is decremented or what happens on partial failure, which would be valuable for a mutation.

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

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

The description is front-loaded with the core action, then provides a structured list of common arguments and a return note. Each sentence contributes useful information, but the informal 'Args (common)' list is slightly verbose and could be tightened without losing clarity.

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 parameters, no output schema, and sparse annotations, the description covers the main requirements: what the tool does, how to identify the product and locations, optional fields, the escape hatch for additional fields, and a basic return statement. It is adequate for complex usage, though it could be more explicit about the need for a product reference and what the 'transfer result' contains.

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

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

Schema description coverage is only 38%, so the description needs to compensate. It does this by explaining the core parameters: productSku/productIdentifier, quantity, source/target warehouse locations, and optional fields like packTypeName and lotBatchNumber. It also clarifies the role of additional_fields as a merge into the request body. Some parameters (e.g., sourceLicensePlateNumber) are not individually explained, but the opening phrase about license plates provides partial context.

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 'Move a quantity of a product between warehouse locations / license plates', which uses a specific verb and resource, clearly distinguishing it from sibling tools like add_inventory, adjust_inventory, and list_inventory. This is an unambiguous statement of the tool's function.

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 clearly indicates when to use the tool (to transfer stock between locations/license plates) and recommends resolving values with logiwa_lookup, logiwa_list_warehouses, and logiwa_list_warehouse_locations. However, it does not explicitly compare against alternatives such as adjust_inventory or add_inventory, so it lacks explicit exclusions.

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

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

The description discloses a critical behavioral nuance: 'Required by the API: sku, name, description, packingSettings. Send the full intended state of these fields.' This goes beyond the annotations, which only indicate write, idempotent, and non-destructive behavior. It also mentions the additional_fields escape hatch and the return value, adding useful 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 four concise sentences, each carrying essential information: purpose, identifier use, required fields/full-state behavior, and additional fields/return value. No wordiness or redundancy; front-loaded with the main 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?

The description covers key aspects: how to locate the product, which fields are mandatory, the full-state update requirement, the escape hatch for extra fields, and the return type. With no output schema, the return description is brief but sufficient. Minor lack of guidance on optional field behavior (e.g., whether omitted optional fields are cleared) is a small 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?

With only 43% schema description coverage, the description compensates by clarifying the role of 'identifier' (UUID to locate the record), highlighting the required fields, and explaining the full-state requirement. It also points to additional_fields for any other Logiwa fields, providing a fallback for undocumented parameters.

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 purpose: 'Update an existing product.' It uses a specific verb (update) and resource (product), and distinguishes from siblings like logiwa_create_product and logiwa_get_product by emphasizing 'existing' and requiring an 'identifier' to locate the record.

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 when to use this tool (for products that already exist) by requiring an identifier and stating 'existing product.' It does not explicitly name alternatives or exclusions, but the context of siblings and the phrase 'existing product' provide clear usage 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 indicate a write operation (readOnlyHint: false), non-destructive (destructiveHint: false), and idempotent (idempotentHint: true). The description adds valuable context by stating that the full intended state of required fields must be provided, indicating a replace-style update rather than a partial patch. It also explains how to handle extra fields via additional_fields.

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

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

The description is concise and front-loaded: the first sentence states the action, followed by the critical instruction about required fields and a brief note about additional fields. Every sentence earns its place, with no redundant or vague 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?

Given the tool's complexity (10 parameters, nested arrays, no output schema), the description covers the essential inputs but is thin on return details and the handling of optional fields. It mentions the response only as 'the update response from Logiwa,' and does not explain what happens to omitted optional fields, leaving some ambiguity for the agent.

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 schema covers 70% of parameters, and the description adds meaning by listing the required fields and emphasizing the 'full intended state' semantics, which is not clear from the schema alone. It also clarifies the role of additional_fields as an escape hatch for unexposed fields, though this is already 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 'Update an existing shipment order' with a specific verb and resource, and distinguishes it from sibling tools like create, cancel, and get. It also specifies the requirement to provide the UUID identifier, which further clarifies its purpose.

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 context for when to use this tool (updating existing orders) and implies not to use it for creating/cancelling via the sibling list. It does not explicitly name alternatives or exclusions, but the 'existing shipment order' phrasing and the requirement of an identifier make the use case unambiguous.

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