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

The readOnlyHint annotation already covers side-effect transparency. The description adds context about the calculation inputs (promotion, surcharge, fee, interest) but does not explicitly state that no data is modified; however, this is adequately covered by the annotation.

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 concise sentences with no redundancy. It front-loads the core purpose, then details the included factors, and ends with a clear directive. Every sentence adds 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 simple calculation tool with no output schema, the description covers the essential behavior, the mandatory usage rule, and the components of the calculation. It does not mention potential error conditions, but given the readOnly annotation and low complexity, it is sufficiently complete.

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

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

The description gives some context for sku and plan_id (via 'for a SKU under one instalment plan'), but it does not explain the sku format or the quantity parameter beyond the schema's minimal 'Default 1.' With schema coverage at 67%, the description adds limited value for parameter understanding.

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

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

The description clearly states the verb 'calculate' and the specific output ('exact monthly payment') for a given SKU and installment plan. It also sets a strong expectation with 'Never quote instalments without calling this,' making the tool's purpose unambiguous.

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

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

It explicitly instructs when to use the tool ('Never quote instalments without calling this'), which serves as a definitive usage rule. It also lists what the calculation includes (promotion, surcharge, fee, interest), clarifying the scope of the result.

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 read-only annotation is consistent with the check action, and the description adds the calculation formula, though it does not discuss auth or rate limits.

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

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

Two concise sentences convey purpose, formula, and usage without unnecessary detail.

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

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

For a simple single-parameter read tool, the description is complete enough; it clarifies the meaning of availability and when to call it, though it leaves the exact output format implicit.

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 identifies the parameter as a SKU but does not specify format, validation, or examples, so it adds only basic meaning beyond the schema.

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

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

The description clearly states the tool checks available units for a SKU, with a specific formula (on hand minus reserved), distinguishing it from product detail or price 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 gives an explicit usage directive: use before promising anything to a customer, making the intended context 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 mark the tool as read-only (readOnlyHint: true), so the description does not need to repeat that. However, it adds no further behavioral details (e.g., output format, potential errors, or performance considerations). The description covers purpose more than transparency, so a score of 3 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 a single, clear sentence that conveys all essential information without redundancy. It is perfectly sized for the tool's simplicity.

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 simplicity and lack of output schema, the description provides sufficient context: what the tool does, the input (SKUs), and the scope (two to four). No additional information is needed 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 schema provides no description for the 'skus' parameter, but the tool description explains that it compares two to four SKUs, indicating that 'skus' are the identifiers of the items to compare. This adds meaning to an otherwise bare parameter, meeting the compensation requirement for low schema coverage.

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

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

The description clearly states the tool's function: comparing two to four SKUs side by side, listing specific attributes (price, key specifications, warranty, availability). It also implicitly distinguishes itself from sibling tools like search_products or get_product_details by focusing on multi-item comparison.

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 what the tool does but does not explicitly state when to use it over alternatives or provide conditions for selection. While the name and sibling context make usage obvious, the lack of explicit guidance prevents a higher score.

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 explicitly states it writes to the database and discounts units from stock, aligning with the destructive annotation and making side effects clear. No hidden surprises.

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

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

Two concise sentences deliver the essential information with no redundant wording. The structure is clean and easily parseable.

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 the core purpose and side effects, and the caution about salesperson confirmation adds important context. It does not mention return values or error scenarios, but these are not critical for a simple write operation among siblings.

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 does not explain the parameters. Only plan_id has a schema description, and reservation_code and payment_method are left undocumented in both schema and description. This would force the agent to infer meanings from names alone.

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 action: turning an active reservation into a confirmed order and reducing stock. It uses a specific verb and defines the resource and outcome unambiguously.

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 direct usage instruction to confirm with the salesperson before calling, and implies this is a state-changing operation. This is helpful guidance, though it could be more explicit about when not to use it (e.g., if a reservation is expired).

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 explicitly notes 'This writes to the database', which is important because readOnlyHint is false. It also discloses the return value (quote code). It does not describe idempotency, but the annotations already indicate idempotentHint is false.

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

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

The description is concise and well-structured, covering the action, optional parameter, return value, and side effect in three short sentences with no unnecessary detail.

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

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

Even without an output schema, the description mentions the returned quote code and states the database write. It is sufficient for basic invocation, though it does not cover prerequisites, error behavior, or when a quote should be created instead of an order.

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 already describes customer, plan_id, and quantity. The description adds little beyond 'optionally under an instalment plan', which mirrors the schema. The sku parameter has no description, though its name is self-explanatory.

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 action ('Create a formal quote'), the target (customer/plan), and the return value (quote code). It also explicitly says it writes to the database, making the tool's purpose unambiguous and distinct from order creation.

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

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

No explicit guidance is given about when to use this tool versus alternatives like create_order, or when to first consult list_installment_plans. The description relies on the tool name and sibling context rather than stating usage conditions.

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

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

The readOnlyHint annotation already covers the lack of side effects, and the description adds the expected output composition. It does not describe error behavior or missing-price handling, but for a read-only lookup this is not a critical omission.

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

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

The description is two concise sentences and front-loads the core purpose. Every phrase adds useful information, with no redundant or filler content.

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

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

For a simple one-parameter read-only tool, the description provides enough context: what is returned and that this is the canonical source. The lack of an output schema is partially mitigated by naming the returned price components, though error cases are not addressed.

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 defines sku as a required string, and the description repeats the term SKU without adding format details or examples. The parameter is self-explanatory to most users, but the description adds minimal 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 returns the current price of a SKU and enumerates the specific price components (list price, active promotion, final cash price, card price). It also distinguishes this tool as the authoritative price source, making its purpose unambiguous.

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

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

The description explicitly says 'This is the only valid source of prices,' providing strong guidance to prefer this tool for price lookups. It could more explicitly contrast with related tools like get_product_details or compare_products, but the guidance is sufficient for most cases.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description's 'Look up' is consistent. However, it adds no extra behavioral context such as error conditions or rate limits beyond what annotations cover.

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 a single, clear sentence with no superfluous words, making it highly concise and well-structured.

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

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

For a simple status lookup, the description fully specifies the input (order code) and output (current status), providing everything an agent needs to invoke the tool correctly without additional 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 schema provides full documentation for the single parameter 'order_code' with an example, and the tool description adds no further semantic detail about the parameter.

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 action ('Look up'), the resource ('order'), and the return value ('current status'), making the tool's primary purpose unambiguous and distinct from siblings.

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

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

The description does not explicitly indicate when to prefer this tool over alternatives like search_products or get_product_details, though the specificity of 'order code' provides implicit 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 and readOnlyHint align: the tool is a read-only lookup with no side effects. It does not detail error cases or response format, but the read-only nature is clear and no contradictions exist.

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

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

The description is a single, compact sentence that efficiently communicates purpose and scope without extraneous detail. The list of included attributes is well organized and easy to parse.

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 gives enough detail for an agent to know what information will be returned, even without an output schema. It lacks explicit mention of return format or error behavior, but for a simple SKU lookup the context 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 single sku parameter is fully explained with a concrete example and is consistent with the description's 'by SKU' phrasing. The schema covers 100% of the parameter, so no semantic gaps remain.

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 retrieves full product details by SKU, enumerating specifications, price, promotion, warranty, and stock by condition and location. This distinguishes it from narrower siblings like get_current_price or check_availability.

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 (when full product detail by SKU is needed), but it does not explicitly contrast it with alternatives such as search_products, get_current_price, or compare_products. There is no direct 'use this instead of X' guidance, though the scope is inferable.

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 annotation readOnlyHint is true, indicating no side effects. The description itself implies a safe read operation by listing information retrieval. No contradictions exist, and the absence of side effects is evident.

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 exceptionally concise—two short sentences that list the policies and provide usage guidance. Every word adds value, with no redundancy or extraneous 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 read-only policy retrieval tool, the description is complete. It covers what the tool returns (policies) and when to use it. The optional key behavior is implied and covered by the schema, so no essential context 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 schema fully documents the single optional 'key' parameter with an enum and description. The tool description reinforces the parameter by listing the same policy types, aiding understanding, though it adds no new detail beyond the schema.

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

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

The description clearly states the tool's purpose: providing current store policies for business hours, location, warranty, returns, and shipping. It also explicitly instructs to use this instead of answering from memory, making the intent 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?

It provides direct usage guidance by saying 'Use this instead of answering from memory,' which tells the agent when to invoke this tool versus relying on internal knowledge. The context of policy retrieval 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?

The readOnlyHint annotation already indicates non-destructive behavior, and the description aligns by using 'List'. The phrase 'currently offered' adds a subtle behavioral nuance (data may change over time), enhancing transparency beyond the annotation.

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 a single, concise sentence with no redundant words. It states the purpose and the optional filter efficiently, adhering to good structure.

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 simple list operation and no output schema, the description provides sufficient context: what it does, what it lists, and the optional filter. It does not need to explain return format or side effects, as those are either obvious or covered by annotations.

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

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

The only parameter 'amount' is described with both its meaning ('Amount to finance') and currency ('quetzales'). This fully covers the parameter's semantic intent, complementing the type information 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 action ('List') and the resource ('installment plans'), and specifies an optional filter by amount. This is unambiguous and distinguishes it from sibling tools that perform different actions like search or calculate.

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 optional filter for amount, giving a clear usage condition. It does not explicitly compare to alternatives, but the purpose is distinct enough that an agent can infer when to use it. Slight deduction for lacking an explicit '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?

The description goes beyond the readOnlyHint annotation by implying the tool checks availability ('propose available products'). This adds a behavioral detail—filtering for availability—that is not explicitly stated in the annotations. It does not contradict the read-only nature.

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—two sentences that state the action and the usage condition. It is front-loaded with the purpose and contains no redundant or filler content.

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

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

The description is sufficiently complete for a simple read-only tool. It indicates the output (proposed products) without needing a formal output schema. It does not mention error handling or edge cases, but given the straightforward nature, this is acceptable. A minor gap is not specifying the format of the returned products, but this is not critical.

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 provides additional context for the 'sku' parameter by framing it as 'the customer wanted.' However, it does not clarify the meaning or purpose of 'limit' or 'max_price' beyond what the schema already states. Since the schema already covers all parameters, the description adds minimal extra value for these fields.

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: proposing available products from the same category and similar price range given a SKU. It uses specific action verbs ('propose') and identifies the resource (SKU) and the output (products). This distinguishes it from sibling tools like search_products or get_product_details, which do not focus on alternatives.

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 provides a usage condition: 'Use this when the requested product is out of stock or over budget.' This gives clear guidance on when to invoke this tool versus alternatives, leaving no ambiguity about the intended scenario.

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 the key side effect: writing to the database and returning units to available stock. It does not describe error cases or repeated-call behavior, but the idempotentHint annotation covers idempotency.

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

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

Two short sentences with no redundant wording; the purpose and side effect are front-loaded before the database note.

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

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

For a simple one-parameter write action, the description covers purpose, side effect, and parameter adequately. It omits output or error behavior, but no output schema is provided and the operation is straightforward.

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 reservation_code parameter is required and clearly described as the code returned by reserve_item, with a concrete format example.

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 action ('Release an active reservation'), the object ('reservation'), and the effect ('return the units to available stock'), leaving no ambiguity about 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?

It indicates this is a state-changing database write and implies it should be used for reservations that should no longer be active. It does not explicitly contrast with sibling tools like reserve_item or create_order, so usage guidance is strong but not exhaustive.

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 explicitly states that this writes to the database (non-read-only) and that it fails on insufficient stock, aligning with the annotations. It also hints at idempotency through the idempotency_key, but does not fully detail all side effects or error handling.

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 brief and to the point, consisting of three short sentences. No extraneous information or repetition is present, making it efficient and easy to parse.

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 the core functionality and failure condition, but it does not mention expected return values or output format, nor does it explain the reservation lifecycle or how it relates to release_reservation. Some context is missing for full autonomous use.

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 60% of parameters with descriptions, but sku and customer lack any description, and quantity/ttl_minutes only have default values. The tool description does not clarify the meaning or format of these parameters, leaving ambiguity for the agent.

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 action (hold/reserve), the resource (SKU units), the condition (fails if insufficient stock), and a note to confirm with the salesperson. It is specific and unambiguous about the tool's primary 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 a usage hint ('confirm with the salesperson first') and implies a precondition (check stock), but it does not explicitly compare with alternative tools or specify when not to use this tool. The guidance is present but not fully 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 readOnlyHint=true, and the description adds valuable behavioral context by specifying it returns real stock and prices with active promotions applied. This goes beyond the annotation and helps the agent understand the output semantics without needing an output schema.

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

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

Two sentences, front-loaded with the main verb and resource, then returning output and usage. Every word earns its place; 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?

The description covers purpose, output, and usage guidance. It does not explain how multiple filters combine or mention the limit parameter, but the schema documents limit defaults and other details. For a read-only search tool with no output schema, this is sufficiently complete 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 description coverage is 67%, with brand and category lacking descriptions. The description adds some meaning by clarifying that filters are combinable ('by free text, category, brand and/or maximum budget') and that max_price represents a budget, but it does not fully compensate for the missing brand/category descriptions or explain how filters interact (e.g., AND vs OR). This is adequate but not exceptional.

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 searches the store catalogue using free text, category, brand, and/or budget, and explicitly lists what it returns (SKU, price with promotions, real stock). This differentiates it from sibling tools like get_product_details or check_availability by establishing it as the general catalogue search entry point.

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 usage context: 'Use this before answering anything about what the store sells.' This directs the agent to use it as a first step. However, it does not explicitly mention when not to use it or name alternatives, so it lacks exclusions.

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