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

Annotations already disclose that this is not read-only and not idempotent, so the description carries a light behavioral load. It adds context by naming the destination ('Chirak store contacts directory') and the notion of a new entry, but does not disclose side effects like duplicate handling or authorization requirements.

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

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

The description is a single well-structured sentence that front-loads the core action. No filler, no redundancy, and every word counts.

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 a fully described input schema, an output schema present, and annotations covering the mutation/idempotence profile, an agent has sufficient information to invoke the tool correctly. Nothing critical is missing for this straightforward create 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%, so all seven parameters are individually described with full meaning, including the string list for channel. The description adds no additional parameter-level information, which is acceptable at this coverage level.

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

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

The description uses a clear verb ('Add'), a specific resource ('a new customer'), and a definitive scope ('Chirak store contacts directory'). It unambiguously distinguishes itself from sibling tools like update_customer, delete_customer, and list_customers through the concept of creating a new 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 states the fundamental action ('Add a new customer') and implies it is for new records, but it doesn't explicitly reference alternative tools such as update_customer for existing customers or list_customers for lookups. No exclusions or when-not-to-use guidance is provided beyond the inherent meaning of 'new'.

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

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

Annotations already declare this as mutating (readOnlyHint=false) and non-idempotent. The description adds no behavioral detail beyond creation, such as handling of duplicate SKUs, whether optional fields get defaults, or side effects like inventory changes. It mostly restates the operation indicated by 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?

Two short sentences with no filler. The core action is front-loaded, and the second sentence provides useful usage context. Every sentence earns its place.

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

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

The input schema fully documents parameters, an output schema exists, and annotations cover mutation/non-idempotency. The description adds the key invocation contexts. A slightly more complete version would explicitly mention using update_product for existing products, but the current definition is sufficient for correct selection and calling.

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 all 10 parameters with descriptions, so the description does not need to repeat them. It also does not add extra parameter relationships or constraints beyond the schema, leaving the schema as the primary source of parameter meaning.

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

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

The description states a concrete action ('Add... product') and resource ('Chirak inventory'), and the qualifier 'new' clearly separates it from the update_product sibling. The listed use cases reinforce what the operation covers without ambiguity.

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 names trigger situations: 'when the user asks to add items, parse wholesale invoices, or register products.' It does not explicitly say when not to use it or direct the agent to update_product for existing products, but the main contexts are 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 indicate readOnlyHint=false and idempotentHint=false, so it's a mutating, non-idempotent operation. The description adds that it 'Automatically records a stock movement,' which is a non-obvious side effect not captured by the annotations. This provides valuable extra 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?

Two concise sentences front-load the primary action and side effect. Every word earns its place, with no fluff or repetition. The examples are directly relevant to usage.

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, side effect, and gives representative reasons. With an existing output schema and 100% parameter coverage, the missing pieces (e.g., when to use vs. record_sale, edge cases) are minor. It's sufficient for an agent to invoke correctly in most scenarios.

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 parameters are already documented. The description adds examples for quantityChange (+10, -3) and reason types, but these largely echo the schema descriptions. It adds marginal value over the schema, topping up with the phrase 'audit reason' but not providing substantial 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?

The description clearly states the action: 'Adjust physical stock quantity for a product (+/- change)' with a specific resource (product) and scope. It also mentions the audit reason and examples, making the tool's purpose unambiguous and distinct from siblings like record_sale or update_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?

The description implies usage through reason examples ('purchase', 'damage', 'adjustment', 'return') but does not explicitly contrast with alternatives such as record_sale or update_product. It lacks a direct 'use when...' or 'instead of...' instruction, leaving the decision partly to inference.

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

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

Annotations already establish that this is a write operation and is idempotent. The description adds valuable context about the concrete effect (inventory restoration) beyond what annotations provide. No contradictions found.

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

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

A single, front-loaded sentence that conveys the primary action and its key side effect without any filler or redundancy.

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

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

For a one-parameter cancel operation with an existing output schema and annotations covering idempotency, the description is complete enough. It could mention cancellation prerequisites or failure states, but nothing essential 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 single parameter 'id' is fully described in the schema as the sale order UUID to cancel (100% coverage). The description adds no further parameter details, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (cancel), the resource (a sale order), and a distinctive side effect (restoring ordered quantities to inventory). This differentiates it from related tools like record_sale or adjust_stock, even without naming them explicitly.

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

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

The description gives clear context: canceling a sale order also restores inventory automatically, which implies its use case. However, it does not explicitly discuss when to prefer it over alternatives or mention invalid conditions (e.g., cannot cancel already-canceled sale).

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 agent knows this is a destructive mutation. The description adds no additional behavioral context (e.g., irreversibility, side effects, or required permissions). Since annotations cover the main risk, the description is adequate but not enriching.

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, front-loaded sentence that states the action and resource directly. Every word is necessary, with no fluff or redundant 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 delete operation with one parameter and an output schema present, the description is sufficient. It conveys the core function, and the schema and annotations fill in parameter details and safety profile. The only minor gap is a lack of explicit mention of irreversibility, but the destructiveHint annotation already conveys that.

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

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

The input schema fully describes the sole parameter 'id' as 'Customer UUID to delete (required).' Schema coverage is 100%, so the description does not need to explain the parameter further. Baseline 3 is appropriate as the description adds nothing beyond the schema.

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

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

The description uses a specific verb ('Delete') and resource ('customer from the Chirak store directory'), clearly distinguishing it from sibling tools like delete_product. It unambiguously states the action and object.

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 provide any guidance on when to use this tool versus alternatives (e.g., update_customer or list_customers). It also omits important context like permanence or conditions under which deletion is appropriate, leaving usage to be inferred.

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 and destructiveHint=true, and the description adds 'Permanently', which signals irreversibility beyond the generic destructive hint. This extra context is valuable. 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?

A single, front-loaded sentence that says exactly what the tool does with no filler. 'Permanently delete' is placed first, immediately conveying the critical destructive nature.

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

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

The tool is simple: one required parameter, an output schema present, and annotations covering the safety profile. The description adds permanence context and names the target resource. Nothing essential for invoking the tool correctly is missing.

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

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

The description provides no parameter-specific details, but the schema has 100% coverage with a clear description: 'Product UUID to delete (required).' The schema carries the burden, so baseline 3 applies.

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

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

The description states a clear verb-resource pair: 'delete or remove a product from the Chirak inventory catalog.' The resource (product) distinguishes it from the sibling delete_customer, and the operation distinguishes it from add_product/update_product. No ambiguity.

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 intended usage is directly implied by the verb 'delete', so an agent can infer when to call it. However, there is no explicit guidance about alternatives (e.g., using update_product to deactivate instead, or adjust_stock to reduce inventory without removal) or any exclusion 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?

Annotations already indicate readOnlyHint=true)Skip? Actually readOnly=true; description discloses the return content: a guide, cheat-sheet, store context, and prompt patterns. This adds useful detail without contradicting the annotation. It doesn't describe errors or edge cases, but for a help tool this is sufficient.

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 what the tool returns. Minor redundancy in 'complete operational guide'/'operational cheat-sheet' but no wasted 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 low-complexity read-only help tool with an output schema, the description gives enough context about content areas and invocation triggers. It doesn't enumerate all outputs, but the output schema handles that.

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

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

Schema covers 100% of the single optional parameter with its allowed topics. The description adds no further parameter guidance, so baseline 3 applies.

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

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

The description clearly identifies this as the route to a complete operational guide for the Chirak store, including capabilities, cheat-sheet, store context, and prompt patterns. It is more specific than the generic sibling 'help', so an agent can distinguish its scope, though the phrase 'store features' is broad.

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 to call it 'whenever the user or agent needs help, guidance, or wants to explore store features,' giving a clear general trigger. However, it does not distinguish this tool from the sibling 'help' tool or state when NOT to use it, so the guidance lacks exclusion criteria.

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 doesn't contradict it. It adds some context (e.g., 'current inventory', 'critical low stock items') but does not disclose behaviors like default limit application, result ordering, or how filters combine. Minimal extra value beyond what annotations and schema already imply.

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

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

The description is a single sentence that names the action, resource, source, and available options. It is front-loaded with the main behavior and contains no filler.

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

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

Given the tool's low complexity (three optional parameters, no required arguments), the existence of an output schema, and the read-only annotation, the description is mostly sufficient. Minor gaps like default limit and filter combination aren't critical because the schema already documents the limit and threshold.

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

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

Schema coverage is 100% for all three parameters (limit, category, low_stock_only). The description merely paraphrases the category and low_stock_only features with 'filter by category' and 'critical low stock items' without adding syntax, formatting, or combination rules beyond the schema's existing 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 a specific action and resource: 'Fetch current inventory products from Chirak' with filtering options. However, it doesn't explicitly distinguish itself from sibling tools like search_product or get_chirak_help, leaving some differentiation to the tool name and parameter hints.

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

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

No guidance is provided on when to use this tool versus alternatives. The description mentions filter options but does not say when to prefer this over search_product or when not to use it, nor does it mention any prerequisites or contexts.

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 signals a safe read operation, so the description does not need to repeat that. It adds some useful context by enumerating the report contents, but it does not disclose additional behavior such as data freshness, aggregation scope beyond the period parameter, or whether low-stock alerts span all 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?

A single, front-loaded sentence that names the resource and its key contents with no filler. Every word contributes to understanding the tool's 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 reporting tool with an output schema, an optional enum parameter documented in the schema, and a readOnlyHint annotation, the description is nearly sufficient. It lacks explicit routing guidance relative to siblings, but nothing critical is missing for safe 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 single parameter 'period' is fully documented in the input schema, including its enum values and default. The description adds no further parameter-level meaning, but with 100% schema coverage, 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 uses a clear verb ('Retrieve') and identifies a specific resource ('summary report') with concrete contents (revenue, total sales orders, units sold, low-stock alerts). It is immediately obvious what this tool does and how it differs from inventory-focused siblings like get_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?

No guidance is given about when to use this tool versus alternatives such as get_inventory, search_product, or record_sale. The context is implied by the name and content, but no explicit usage conditions, exclusions, or prerequisites are provided.

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, so the safety profile is known. The description adds content scope but no additional behavioral traits such as response format or performance characteristics; that is acceptable given the read-only annotation, so a baseline 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 entire description is a single front-loaded sentence that names the deliverable ('quick operational guide and cheat-sheet') and its three content areas in sequence. Every word contributes; there is no filler or repetition.

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 help-like tool with an output schema and simple optional parameter, the description is mostly complete. What keeps it from a 5 is the lack of any mention of how this differs from the get_chirak_help sibling, which an agent may need to disambiguate.

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 documents the optional topic parameter and its allowed values at 100% coverage Mend, so the agent already has parameter-level guidance. The description adds no new semantic detail about how topic influences the returned guide, so it remains at baseline.

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

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

The description states a clear purpose: a quick operational guide and cheat-sheet covering capabilities, active metrics, and recommended prompts. It uses content-specific nouns and a recognizable verb phrase ('guide and cheat-sheet'), so the agent knows what the tool returns. It doesn't explicitly differentiate from sibling get_chirak_help, preventing a 5.

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

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

The description implies when to use it: when an agent needs a quick overview of Chirak store capabilities, metrics, or prompt examples. However, it offers no guidance about when not to use it or how it compares to the similarly named get_chirak_help sibling, leaving some routing ambiguity.

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 main safe behavior. The description adds useful scope (returns directory plus spending metrics), but does not disclose other behavioral details like pagination, ordering, or response volume.

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 one clear, front-loaded sentence with no filler. It states the action and the result set compactly without repeating the tool name.

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

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

The description covers the core purpose and the schema covers the optional parameters. It does not mention pagination/ordering, but for a low-complexity read-only list tool with an output schema, this is only a minor gap.

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

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

Parameter meanings are fully covered by the schema descriptions for 'limit' and 'search', so the description does not add extra parameter-level context. This is a case where the schema carries the parameter documentation.

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

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

The description uses a specific verb ('Retrieve') and clearly names both the resource (customer contact directory) and the included data (lifetime spending metrics), distinguishing it from the sibling customer add/update/delete 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 states what the tool does but provides no explicit guidance about when to use it versus alternative tools, such as search, add, or update paths. There is no mention of exclusions or when another tool would be preferable.

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

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

Annotations only indicate readOnly=false and non-idempotent, so the description carries the burden of disclosing destructive side effects. It explicitly states 'automatically deduct the corresponding product stocks,' which is the key behavioral disclosure. It doesn't mention reversibility or other consequences, but the primary side effect is communicated clearly.

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, efficient sentence that front-loads the action and side effect. It is concise and avoids redundancy with the schema. While it could mention return aspects, the output schema already covers that, so the brevity is appropriate.

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 rich schema and output schema, the description covers the essential behavioral context (stock deduction) that an agent needs. It doesn't discuss prerequisites like product existence or payment impacts, but the schema and annotations provide enough for correct invocation. The core side effect is clearly stated, so completeness is strong.

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 schema already thoroughly documents all parameters. The description adds a slight semantic cue by mentioning stock deduction, linking items to inventory, but does not provide additional parameter-level meaning beyond the schema. A baseline of 3 is appropriate given the extensive schema documentation.

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 specific verb 'Record' and resource 'sale order' with the key side-effect of automatic stock deduction. This distinguishes it from sibling tools like adjust_stock and cancel_sale, 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 implies when to use the tool (when recording a sale) and highlights the automatic stock deduction, which is a critical behavioral nuance. However, it doesn't explicitly contrast with siblings like adjust_stock or cancel_sale, though the purpose is clear enough for an agent to infer usage.

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 covers the no-side-effects aspect, and the description adds the supported search fields. However, it does not disclose whether matching is exact, partial, case-sensitive, or paginated. With the annotation, 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?

A single, front-loaded sentence with no filler. It names the action, resource, and search keys in minimal 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 one-parameter read-only search with full schema coverage and an output schema, the description is nearly complete. It could mention match behavior or ordering, but that is not essential for initial tool selection.

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%: the query parameter is already described as 'product name, barcode, or SKU'. The tool description repeats the same information without adding detail like format constraints, wildcards, or examples.

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 ('Search'), the resource ('products in Chirak'), and the search keys ('name, SKU code, or barcode'). It distinguishes this from siblings like get_inventory or product mutations by focusing exclusively on text-based search.

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

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

The description conveys the core usage: look up products by name, SKU, or barcode. It does not explicitly compare against get_inventory or other product tools, so an agent must infer the boundary between searching and listing 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 declare readOnlyHint=false and idempotentHint=true, so the write nature is covered. The description adds no additional behavioral context—critically, it does not clarify whether omitted fields are preserved (patch semantics) or reset (put semantics). Since partial updates are a common behavior for update tools with multiple optional fields, this omission leaves an important behavioral trait undisclosed.

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 sentence that states the purpose without any fluff. It is front-loaded with the primary action and resource, and no word is wasted. Perfectly concise for the information it conveys.

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 8 optional parameters (plus required id) and an output schema, but the description does not explain the update semantics (whether missing fields are preserved or cleared). This is a critical piece of information for an agent to call the tool correctly. The output schema covers return values, but the lack of partial-update clarification makes the definition incomplete for a tool of this 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 description coverage is 100%, so each parameter has a brief description (e.g., 'Updated full name'). The tool description adds no meaning beyond the schema and does not clarify ambiguous fields like 'channel' or 'socialHandle.' With high schema coverage, the baseline is 3, and the description provides no extra 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 states a clear verb ('Update') and resource ('existing customer in Chirak'), and mentions the kind of fields affected (contact details, delivery address, notes). It distinguishes from add_customer and delete_customer by the phrase 'existing customer,' though it does not explicitly name alternatives. The purpose is specific enough for an agent to understand what it does.

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 it is for modifying an existing customer, which rules out creation or deletion. However, it provides no explicit guidance on when to prefer this over add_customer or delete_customer, nor does it mention any prerequisites or exclusions. The context is clear but the guidance is implied rather than stated.

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

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

Annotations already provide readOnlyHint=false and idempotentHint=true, so the write and repeat-safe nature is covered. The description adds useful scope by enumerating updatable fields, but it does not disclose partial-update semantics, failure behavior for nonexistent IDs, or permission requirements. It does not contradict 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 a single, front-loaded sentence with no filler. The action and resource appear first, and the field list is compact and useful.

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

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

With an output schema present and 10 parameters fully documented in the schema, the description is mostly adequate. However, it lacks guidance on stock adjustments via adjust_stock versus updating stockQuantity directly, and it does not state whether omitted optional fields are left unchanged or reset. These are meaningful gaps for correct tool selection and invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor clarity by using 'physical stock quantity' to disambiguate stockQuantity from minimumStock and 'cost' for costPrice, but it mostly restates what the schema already documents and omits unit and minimumStock from its examples.

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

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

The description uses a specific verb ('Update') and resource ('details of an existing product in Chirak'), and names concrete fields. This clearly distinguishes it from sibling tools like add_product and delete_product, so an agent can identify what this tool operates on.

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 'existing product' implies the product must already exist, but the description gives no explicit guidance on when to use this tool versus alternatives. In particular, it does not mention adjust_stock even though it lists 'physical stock quantity' as an updatable attribute, leaving potential ambiguity about which tool handles stock changes.

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