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

With no annotations, the description carries the behavioral burden. It usefully discloses that the code becomes a global resolution alias after attachment, but it does not address what happens if the barcode is already assigned, whether it replaces an existing binding, or any error/authorization 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, front-loads the core action, and uses a short argument list. Every sentence contributes either semantics, usage context, or parameter meaning with no filler.

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

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

For a simple two-argument mutation, the description covers what the tool does, why it matters, and how to fill both parameters. It lacks only edge-case behavior such as duplicate barcode handling, but it is still enough for an agent to select and invoke it correctly.

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

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

Schema coverage is 0%, so the description must define the parameters, and it does: product is 'a name or description fragment' and barcode is 'the full GTIN/EAN as printed under the bars.' These meanings go well beyond the bare string type in the schema, though they stop short of specifying format constraints.

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?

Opens with 'Attach a GTIN/EAN barcode to a product,' a specific verb plus resource, and the follow-up sentence explains the effect of the binding. This clearly distinguishes it from the sibling remove_barcode and from product creation 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 gives clear context: the barcode resolves to the product everywhere a product argument is accepted, enabling scan-based consumption or restocking. It does not explicitly list exclusions or name alternative tools, but the intended use case is evident.

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

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

With no annotations, the description carries the disclosure burden itself. It reveals a non-obvious behavioral trait: products without min_stock are silently ignored, so the operation may be incomplete in instances where few minimums are set. It doesn't specify duplicate handling or return behavior, but the key limitations are covered.

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 and front-loads the primary action before adding context. The limitation and fallback in the second paragraph both earn their place; there is 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 zero-parameter, no-output-schema tool, the description explains what it does, its blind spot, and the recommended alternative. The lack of return-value documentation is not a meaningful gap for an action that appends to a shopping list.

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

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

The input schema has zero parameters and 100% coverage, so there is no parameter semantics for the description to clarify. Per the 0-parameter baseline, this dimension is effectively a non-issue.

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 first sentence states the specific action ('Add everything below its minimum stock level') and the target resource ('the shopping list'), making it clearly distinct from siblings like below_min_stock and add_to_shopping_list. The reference to Grocy's 'add missing products' adds useful context without obscuring what the tool 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 explicitly names a limitation—only products with a min_stock set are considered—and gives a conditional alternative: 'read out_of_stock and add what's wanted by name instead' when few products have minimums. This is clear when-to-use vs when-not-to-use 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?

There are no annotations, so the description carries the behavioral disclosure burden. It discloses the write nature, the reported new total, the requirement that the product already exists, and the special best-before estimation behavior. It does not mention error behavior or side effects on stock history, but it covers the core behavior well.

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 the purpose, and every parameter explanation adds necessary operational detail. There is no repetition of schema type information and 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?

The description is complete for a simple 4-parameter tool: it explains all parameters, the product-matching constraint, the date estimation convention, and the expected result. It could go further by describing error cases or exact response shape, but with no output schema it still gives an agent enough to call the tool 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 0%, and the description fully compensates. Each parameter gains meaning: product may be name/fragment/barcode and must match exactly one existing product; amount is in the product's own unit; best_before_date uses package date or pantry conventions; location_id is optional and may be id or exact name.

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 action and resource: 'Record newly bought stock, and report the new total.' The verb 'record' plus 'newly bought stock' clearly distinguishes this from stock correction, consumption, or transfer tools among the siblings.

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

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

The description gives clear context: it is for newly bought stock, and it explicitly notes that this tool does not create new products, which sets a boundary against create_product. It does not explicitly name alternative tools or provide when-not-to-use conditions, but the context is strong enough for an agent to select it.

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

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

With no annotations, the description carries the full behavioral burden. It discloses the linking logic, the free-text fallback, the refusal on near-miss product names, and the unit convention for amount. It stops short of detailing error conditions (e.g., ambiguous matches) or side effects beyond adding a row, but covers the key behavioral nuances that would affect an agent's 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 a few sentences of behavioral context followed by a clear Args block. It is slightly longer than the bare minimum but every sentence contributes either to purpose, behavioral nuance, or parameter meaning. The purpose is front-loaded, and the structure makes the parameter documentation 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 three-parameter tool with no output schema, the description covers the core behavior, parameter semantics, and the important edge case of refusing near-miss text. It does not mention return values (though no output schema exists) or specific error responses, but it is sufficiently complete for an agent to invoke the tool 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?

The schema has zero descriptions, so the description must fully explain the parameters. The Args section does exactly that: item is defined as 'product name, description fragment, barcode, or free text', amount specifies 'in the product's stock unit', and note gives an example. This adds substantial meaning beyond the bare schema types and defaults.

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 clear verb+resource statement ('Add something to the shopping list') and then elaborates on the two distinct behaviors (link to catalog product vs. free-text note) that set it apart from other shopping-list tools. It explicitly names a downstream dependency (add_stock) that clarifies its role in the workflow.

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 guidance on what inputs are appropriate (product names, barcodes, free text) and explains when free-text is acceptable vs. when it refuses (close matches to existing products). However, it never explicitly names alternative tools or states conditions for choosing this tool over siblings like remove_from_shopping_list or add_missing_to_shopping_list, leaving the selection criteria 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?

With no annotations, the description carries the full burden of behavioral disclosure. It adds meaningful context: this is Grocy's own missing-products calculation, it is blind to products without a minimum, and empty results are ambiguous. It does not describe response format or errors, but for a simple zero-parameter list operation the key behavior is clearly surfaced.

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

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

Three sentences, each earning its place: the core purpose, the min_stock prerequisite and empty-result ambiguity, and the sibling alternative. It is front-loaded with the action and resource, with no filler or redundant restatement.

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

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

For a zero-input, no-output-schema inventory query, the description covers everything an agent needs: what it returns, its limitation, and how to distinguish it from out_of_stock. The caveat about what empty results mean is particularly valuable in a Grocy-specific deployment.

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

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

The tool has zero parameters and the schema lists none, so the baseline is 4. There is nothing parameter-related the description needs to add; it correctly focuses on result semantics and edge-case interpretation instead.

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

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

The description opens with a specific verb and resource: 'List products that have fallen below their minimum stock amount.' This unambiguously defines what the tool does and distinguishes it from related queries like out_of_stock by clarifying that it only considers products with a minimum set.

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 explains when to use this tool: only products with a minimum configured via update_product's min_stock are seen, and empty results often mean no minimums exists. It also names out_of_stock as the tool that 'works regardless,' giving the agent an explicit alternative and a clear routing decision.

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?

With no annotations, the description discloses a key behavioral aspect: checking off does not add stock, and suggests using add_stock for that purpose. It also mentions the un-mark action. However, it doesn't specify whether the row is removed or remains marked in the list, a minor transparency gap.

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 succinct: two sentences of core explanation followed by a clean Args list. It front-loads the primary action and the critical caveat about stock, making it easy for an agent to parse quickly 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?

The description covers the essential aspects: what the tool does, what it does not do, and parameter usage. It lacks details on the post-check state (e.g., whether the row is removed or remains), which could be inferred but isn't explicit. Given the simple 2-parameter scope, it is almost complete.

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

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

Schema coverage is 0%, but the description explicitly defines both parameters in the 'Args' section. 'item' is described as 'Product name or note text, as shown by list_shopping_list,' adding concrete guidance, and 'done' is explained as 'False to un-check a row checked off by mistake,' clarifying its boolean meaning beyond the default.

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 ('mark') and resource ('shopping list row') with a clear outcome ('as bought'), and explicitly mentions the un-mark capability. It distinguishes itself from the sibling add_stock by clarifying that checking off does not add stock, which prevents confusion.

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

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

The description provides a direct alternative: 'call add_stock for that' when stock needs to be added, and explains when to use the 'done' parameter (False to un-check a mistake). It also references list_shopping_list as the source for item names, giving clear context on when this tool applies.

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?

With no annotations, the description carries the burden of disclosing behavior. It clearly explains that the default removes only checked-off rows, and warns that passing False 'wipes the list completely — that discards unbought items too,' which appropriately signals destructive consequences. It could mention irreversibility, but the disclosure is solid.

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 the tool's purpose, followed by a focused parameter explanation. Every sentence earns its place, and there is 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?

For a simple one-parameter destructively scoped operation, the description covers how to invoke it and what will happen in both parameter modes. It does not describe return values or behavior on an empty list, but those are minor for this operation and not necessary for correct invocation.

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

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

Schema description coverage is 0%, so the description is the sole source of parameter meaning. It fully explains done_only: the default True behavior, the effect of leaving items, and the False behavior with its consequence. This goes well beyond the schema's title and default 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 specific action and resource: 'Clear the shopping list after a shop.' It clearly communicates what the tool does and adds the scope of the clearing behavior via the done_only parameter. It does not explicitly name sibling tools like remove_from_shopping_list or check_off_shopping_item, so differentiation is implied rather than stated.

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

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

'After a shop' gives clear contextual timing for when to use the tool. It does not explicitly list alternatives or exclusions, but the distinction between removing checked-off items and wiping the whole list provides practical usage guidance within the 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?

With no annotations, the description carries the behavioral burden. It discloses that the tool mutates stock, raises an error rather than guessing for ambiguous products, and reports remaining quantity. It could mention undo/reversibility, but the core behaviors are clearly communicated.

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 the main purpose. Each sentence in the Args section adds meaningful guidance, and the examples are brief but instructive. There is no fluff or redundant restating of 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 all parameters, the main behavior, error behavior, and references list_stock for verification. It does not explicitly explain how this tool relates to sibling tools like out_of_stock or correct_stock, and it doesn't mention reversibility, but for a simple consume action it is reasonably complete.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains product matching rules, unit-sensitive amounts with a concrete example, and the spoiled flag's semantics. This goes far beyond the bare schema properties.

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, specific action: record that stock was used up and report what remains. It is not a tautology and communicates the tool's core function, though it does not explicitly distinguish itself from sibling tools like out_of_stock or correct_stock.

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

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

The description gives clear context for when to use the tool: consuming stock, with a spoiled flag for thrown-away items. It also directs the agent to check list_stock's qty when unsure, which is useful guidance. It stops short of explicitly naming alternative tools for different stock situations, but the usage context 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?

With no annotations provided, the description carries the full burden. It discloses that it books the difference in either direction, allows upward/downward correction, and that zero clears stock entirely. It also explains the best_before_date requirement for upward corrections. While it doesn't mention potential side effects like transaction logs or permission requirements, the core behavior is well explained. Minor gap but solid for a stock adjustment tool.

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?

Well-structured with a punchy opening, a helpful analogy, clear alternative routing, and a formatted parameter list. Every sentence earns its place, no fluff, and the most critical information (purpose, correction behavior, alternatives) is front-loaded before the parameter details.

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 4-parameter tool with no output schema and no annotations, the description is remarkably complete. It covers when to use, what it does, all parameter semantics, edge cases (zero, best-before requirement), and directs to alternatives. An agent would have everything needed to call this correctly without external help.

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 0%, but the description compensates fully. Each parameter gets meaningful explanation: product accepts name, fragment, or barcode; actual_amount specifies the stock unit and zero-clears behavior; best_before_date is format-specified and its required condition is explained; location_id clarifies its default semantics. This goes far beyond the bare 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 first sentence 'Set stock to the amount actually counted on the shelf' is a precise verb+resource+scope statement. It clearly distinguishes from siblings by naming alternatives (consume_product, add_stock) for ordinary use and purchases, and its 'I looked, and there are three' analogy makes 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?

Explicitly states when to use: when the tracked amount has drifted from reality, with concrete examples (unrecorded use, double entry). It also gives clear when-not-to-use guidance by telling the agent to prefer consume_product for ordinary use and add_stock for purchases. No ambiguity remains.

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?

With no annotations, the description carries the full behavioral burden and does so thoroughly. It discloses duplicate-name refusal, non-blocking near-duplicate behavior with possible_duplicates, and the downstream effect of setting min_stock on below_min_stock and add_missing_to_shopping_list. This goes well beyond a generic creation statement.

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 appropriately detailed for a six-parameter tool with no schema descriptions, and every sentence carries information. The core scoping statement is front-loaded first, followed by duplicate behavior, then the parameter list with meaningful guidance.

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

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

Given no annotations and no output schema, this description gives an agent everything needed to invoke the tool correctly: what it does, what it does not do, how duplicates are handled, which sibling to call next, and the semantics of every parameter. The mention of possible_duplicates also tells the agent what feedback to inspect in the result.

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 0%, so the description must compensate for all six parameters, and it does. It explains category as exact match, location_id as id or exact name, unit as an existing Grocy unit, and min_stock's functional meaning in the same unit. These are constraints the JSON schema alone does not convey.

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 the exact action in the first sentence: 'Add a new product to the catalog, for something never stocked before.' It further distinguishes the tool from add_stock by saying 'This only creates the product record,' making it clear this is a creation-only operation rather than a stock adjustment.

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 tells the agent to call add_stock next to record quantity on hand, and to use add_stock instead when a product name already exists. The near-duplicate warning also gives the agent a concrete follow-up action: check possible_duplicates before assuming the product is 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It discloses irreversibility ('Permanently remove'), the hard precondition that stock must be zero, that the tool refuses otherwise, and that the identifier must resolve to exactly one product. That is strong disclosure for a destructive operation.

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: core behavior, refusal condition, intended use cases, and argument semantics each get one clear statement. Every sentence earns its place by either constraining usage or preventing foreseeable misuse.

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 destructive mutation with no annotations and no output schema, this describes purpose, constraints, refusal behavior, alternatives, and argument semantics. Nothing critical is missing for an agent to decide when to call it and how to call it safely.

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 0%, with the schema only defining 'product' as a required string. The description fully compensates by specifying the accepted identifier forms (name, description fragment, or barcode) and the uniqueness requirement. It gives the agent exactly the semantic information needed to supply a valid argument.

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

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

The description states a specific verb ('Permanently remove') and resource ('a product with zero stock from the catalog'), and immediately distinguishes the tool from sibling operations by saying what it is not for. It is immediately clear how delete_product differs from consume_product, update_product, or search_products.

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

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

It explicitly says when to use this tool (cleaning up mistakes, test products, typo'd duplicates) and when not to use it (retiring a product still in use). It also names the prerequisite workflow: use consume_product to bring stock to zero first. This is model alternative routing.

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?

With no annotations provided, the description carries the full burden. It discloses that only provided arguments are changed and the rest of the entry is preserved, which is useful. However, it does not mention potential error cases (e.g., non-existent entry), whether the operation is irreversible, or what the response looks like. For a mutation tool this is a moderate gap, but the core behavior is communicated.

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 slightly longer than necessary but every sentence earns its place. It front-loads the purpose, then gives usage context and parameter details in a logical order. The only minor inefficiency is the arg list formatting, but it remains clear and 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 no output schema and no annotations, the description covers the essential aspects: what the tool does, when to use it, how to source the required identifier, and parameter formats. It omits return-value details and error handling, but those are less critical for a mutation tool. Overall it is sufficient for an agent to call 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 has zero description coverage, so the description fully compensates. It explains each parameter: `entry_id` is sourced from `list_stock_entries`, `best_before_date` uses YYYY-MM-DD format, `location_id` accepts either an id or an exact name, and `amount` is in the product's stock unit. This adds meaning far beyond the bare schema types.

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

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

The description opens with a specific verb and resource: 'Fix one stock entry' and immediately enumerates the exact fields it can modify (date, location, amount). It also distinguishes itself from the sibling `correct_stock` by stating this tool targets a single batch rather than a total. This makes the purpose unambiguous and clearly differentiated.

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

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

The description gives explicit when-to-use guidance: correcting an estimated best-before date or a misplaced batch. It also states when NOT to use it, recommending `correct_stock` for total-amount corrections, and tells the agent to obtain `entry_id` from `list_stock_entries`. This leaves no ambiguity about tool selection.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure. It mentions the ordering ('worst first') and the default behavior for the 'days' parameter, but it does not explicitly state that this is a read-only operation, nor does it mention pagination, result limits, or any other side effects. The 'List' verb implies a read, but it is not made explicit.

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

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

The description is two sentences, with the purpose front-loaded. The Args section is clean and provides exactly the needed parameter information with no waste. Every word earns its place.

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

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

For a simple list tool with a single parameter and no output schema, the description is mostly complete. It explains the filtering and ordering, and the parameter default. The only missing piece is an explicit statement of the return format or whether pagination is used, but that is a minor gap for a tool of this simplicity.

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 descriptions (coverage 0%), so the description must fully explain the parameter. It clearly states what 'days' means ('Look-ahead window in days') and its default behavior ('Defaults to the configured window'), adding significant value beyond the schema definition.

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

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

The description states a specific verb ('List') with a clear resource ('items') and a precise condition ('already expired or due within N days'), plus ordering ('worst first'). This distinguishes it from sibling tools like list_stock or below_min_stock without needing to open their schemas.

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 the use case (checking items near expiry), but it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or alternative tools. The purpose is obvious, but there is no direct guidance on tool selection.

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

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

With no annotations, the description carries the behavioral burden, and it delivers meaningful context: locations, categories, and units are 'read live' and stay correct after web UI renames. It implies a safe read-only query, although it never explicitly states that no mutation occurs or discusses any output-size or freshness caveats beyond live reading.

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

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

Three tight sentences front-load the core content, then give a usage instruction and a freshness guarantee. No filler or repetition beyond a natural recapitulation of the entities named.

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

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

For a parameterless metadata-retrieval tool with an output schema and no annotations, this description covers what the agent needs: what is returned, why it is the canonical source, when to call it, and how fresh the data is. 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 tool takes zero parameters and the schema coverage is 100%, so there are no parameter semantics to flesh out. The description adds useful context about ids being included in the returned locations, which agents need for later calls.

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 exactly what the tool exposes — locations with ids, categories, quantity units, and house rules — and explicitly identifies it as the cross-referenced reference for other tools. This makes the tool's role unambiguous and distinct from the many operation-oriented 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?

It gives an explicit directive: 'Call this once at the start of a session rather than guessing or trial-and-erroring an id.' This tells the agent exactly when and why to use it, preempting the common failure mode of guessing identifiers.

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?

With no annotations, the description carries the burden of behavioral disclosure. It does disclose that checked-off rows remain until clear_shopping_list removes them, which is useful stateful behavior. It also explains the two row types. However, it doesn't mention whether the list is sorted, whether it returns only unchecked items or all items, or any read-only guarantee. The description adds some value but leaves notable behavioral gaps.

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: the first sentence states the tool's purpose, and the second adds essential behavioral context. Every sentence earns its place, and there is no redundant or filler content.

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

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

For a zero-parameter read tool, the description covers the core purpose and key behavioral nuance (checked-off rows persist). However, it doesn't describe the return format or whether the output includes all rows or only unchecked ones. Given no output schema and no annotations, a bit more detail about what the response contains would make it 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 tool has zero parameters, so the schema provides no parameter semantics. The description compensates by explaining what the output represents (what to buy, how much, checked-off status) and the distinction between catalog products and free-text notes. Since there are no parameters to document, a baseline of 4 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 shows the shopping list and what it contains (what to buy, how much, checked-off status). It distinguishes itself from siblings like add_to_shopping_list, check_off_shopping_item, and clear_shopping_list by focusing on display/listing. However, it doesn't explicitly name a sibling alternative, so it falls just short of a 5.

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

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

The description implies this is the read/display tool for the shopping list, contrasting with mutation siblings like add_to_shopping_list and clear_shopping_list. It explains the two row types (catalog product vs free-text note) and checked-off behavior, which helps an agent know when to call it. But it doesn't explicitly state when to use it versus alternatives or mention 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about live queries and no caching, and the read-only nature is obvious from 'list'. It doesn't mention output format, but for a simple list tool that is acceptable. No contradiction with annotations (none 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 front-loaded with purpose and the live-query advantage, followed by concise parameter explanations. No wasted words; every sentence adds value. Format is clean and 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 simple listing tool with 2 optional parameters and no output schema, the description covers purpose, behavior, and parameter semantics thoroughly. An agent has enough information to call it correctly, and the sibling list provides context for specialized queries. No missing critical details.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains both parameters: location and category are optional case-insensitive substrings, with examples and the 'omit for everything' default. This goes beyond the bare schema and provides complete usage semantics.

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

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

States a specific verb (list) and resource (pantry), and clarifies it reads live from Grocy. It distinguishes itself from siblings like list_stock_entries by presenting itself as the general, always-current listing. Clear 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?

Implicitly tells when to use it (whenever current stock is needed) and explicitly dismisses cache concerns by stating it queries live each call. However, it does not name alternatives like expiring_soon or below_min_stock, nor state when not to use it. Adequate but could be more explicit about routing to specialized 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?

No annotations are provided, so the description carries the full burden. It explains that each batch has its own best-before date and location, and that the tool returns entry_id. While it implies read-only behavior through 'List', it does not explicitly state side effects or edge cases, but for a simple listing 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?

The description is concise and well-structured: it leads with the core purpose, distinguishes from a sibling, gives two concrete use cases, and then documents the parameter. No filler or redundancy; every sentence contributes.

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 single parameter and lack of output schema, the description covers the essential behavior and usage. It implies the return includes entry_id, best-before date, and location, but does not explicitly state the full response format or potential error cases. Still, it is adequate for a simple listing 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 schema has only one parameter 'product' with no description, but the description explicitly defines it as 'Product name, description fragment, or barcode.' This adds essential semantic meaning beyond the raw string type, fully compensating for the 0% 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 lists a product's individual stock entries per purchase batch, and immediately contrasts with list_stock which shows the total. It also mentions the purpose of retrieving entry_id for edit_stock_entry, making the resource and action 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 states when to call this tool: to get an entry_id before edit_stock_entry or to see which pack expires first. It also differentiates from list_stock by noting it shows the total versus the breakdown, giving clear guidance on when to use which.

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?

With no annotations provided, the description carries the behavioral burden; it discloses that this is a non-consuming status change and that it affects expiring_soon suggestions. It does not address reversibility or edge cases such as over-opening, but the core side effect is clearly stated.

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?

Every sentence serves a purpose: the first defines the action, the second justifies it, and the bulleted Args explain parameters. There is no filler and no repetition of schema metadata.

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 tool with no annotations or output schema, the description gives enough to select and call it correctly: purpose, rationale, and parameter meaning. It omits return/undo details, but those are secondary for this 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 description coverage is 0%, so the Args block is the only semantic source. It clarifies that product accepts a name, description fragment, or barcode, and that amount is denominated in the product's stock unit.

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 phrase 'Mark stock as opened' gives a concrete verb and resource, and 'without consuming it' explicitly separates it from the sibling consume_product. This is more specific than a generic 'open product' reading.

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

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

It explains that opened items usually keep for less time than the printed best-before date and that flagging them helps expiring_soon stay useful, giving a clear use case. It stops short of naming an alternative like consume_product or listing explicit when-not-to-use 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It clarifies the exact edge-case definition of 'out of stock' and notes that no minimum stock levels are needed. The verb 'List' implies a read-only operation, though it does not detail output format or ordering; still, this is strong for a zero-parameter read tool.

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. The first sentence gives the core purpose, and the second clarifies the boundary against below_min_stock 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 simple, zero-parameter listing tool with no output schema, this description is fully sufficient. It explains what is returned, the precise condition, and where to go for the adjacent case, so an agent can invoke it correctly without further 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 tool has zero parameters, so the schema is trivially covered. The description adds conceptual meaning by explaining that the absence of parameters is intentional: no minimum stock thresholds are required to use this tool.

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

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

The description states a specific verb and resource: 'List products with zero stock.' It also clearly scopes the meaning ('there is none left at all') and distinguishes it from below_min_stock, 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?

It explicitly states when to use this tool: for products with zero stock, with no minimum stock configuration required. It also names the alternative below_min_stock for products that still have stock but are under a configured minimum, giving clear routing 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?

With no annotations, the description carries the behavioral burden. It discloses several outputs (last bought, last used, shelf life, spoil rate, open amount, minimum stock) and implies a read-only lookup. However, it does not state the absence of side effects explicitly, nor does it describe error behavior, authorization needs, or what happens if the product is not 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?

The description is relatively compact and front-loads the core behavior ('Everything Grocy knows about one product') before listing output fields and the parameter format. Every sentence adds content, though the field list is somewhat long and could be tightened.

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 what data is returned, the intended decision context, and the flexible input format, which is adequate for a simple one-parameter lookup. However, with no annotations, no output schema, and no sibling or error guidance, an agent is left without signal about failure modes or how this relates to tools like stock_history or search_products.

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 0%, and the schema only says the parameter is a string. The description's 'Args' section adds valuable meaning by explaining that 'product' can be a product name, description fragment, or barcode. However, because this is the only piece of parameter documentation and output details are bundled into the description rather than schema, the parameter semantics coverage remains thin.

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

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

The description clearly identifies the resource ('one product') and scope ('stock, dates, and history'), and enumerates the specific data returned. However, it lacks an explicit verb like 'retrieve' or 'get', and it does not explicitly distinguish itself from sibling tools such as stock_history or search_products.

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

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

The description provides a clear use context: deciding whether to restock a product or stop buying it ('the context for deciding whether to restock something or stop buying it'). It does not mention exclusions or when to prefer sibling tools, but the single-product context is reasonably 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?

With no annotations, the description must reveal behavioral traits. It states that the barcode is removed 'from whichever product currently holds it,' which is a key behavioral detail (no product parameter needed). It doesn't mention side effects, reversibility, or auth requirements, but for a simple detach operation this is reasonably transparent.

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 compact two-sentence structure: a clear one-liner for the purpose plus an Args section explaining the parameter. Every sentence adds value; no 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?

For a single-parameter tool with no output schema and no annotations, the description covers the essential aspects: purpose, parameter, and target selection behavior. It stops short of specifying error handling or return semantics, but those are minor for a straightforward remove 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 0%, so the description must compensate. It explains the parameter as 'The code to remove' and adds crucial behavior: it is removed from the current holder, not a specified product. This goes beyond the schema and fully disambiguates the parameter's role.

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: 'Detach a barcode' and specifies the resource (barcode) and context (attached to the wrong product). It distinguishes from add_barcode implicitly and is a specific verb+resource pair.

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 a barcode is attached to the wrong product) and clarifies that it removes from the current holder. It doesn't explicitly name alternatives or exclusions, but the context is clear enough for a simple 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 are not provided, so the description carries the behavioral burden. It states 'Take a row off entirely' which implies destructive, irreversible removal, but does not mention whether the action is reversible or if there are any side effects. It doesn't contradict any annotations, but could add more detail about what happens after removal.

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 with the core action. It includes necessary context and parameter explanation without unnecessary details. The Args section is minimal but sufficient, though arguably the parameter explanation could be integrated into the body for better flow.

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 (1 parameter, no output schema), the description covers what an agent needs: the action, when to use it, and how to specify the item. It does not describe edge cases like if the item doesn't exist, but that may be beyond the scope 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?

With schema coverage at 0%, the description must explain the parameter. It does so explicitly: 'Product name or note text, as shown by list_shopping_list', adding meaning beyond the schema's mere 'item' string, clarifying the expected format and source.

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

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

The description clearly states it removes a row from the shopping list entirely, using the specific verb 'Take' and resource 'shopping list'. It distinguishes itself from check_off_shopping_item, which is a sibling, by noting that removal is for items added by mistake or no longer needed, not for purchased items.

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 when-to-use: for items added by mistake or no longer needed. It also clearly states when NOT to use it: if the item was bought, prefer check_off_shopping_item (and add_stock) for record-keeping, explicitly naming the alternative.

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?

With no annotations, the description carries the burden of behavioral disclosure and does it well: it explains what a miss means, what in_stock: false means, and asserts that misses are genuine non-existence rather than search failures. It does not discuss read-only guarantees, rate limits, or full response shape, but it covers the most decision-relevant 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 front-loaded with the core purpose, and every subsequent sentence earns its place by explaining miss semantics, hit semantics, or when to call the tool. 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 single-parameter search tool with no annotations and no output schema, the description is nearly complete: it explains input formats, result interpretation, and key workflows. It could go slightly further by listing the expected return fields beyond in_stock, but that is not essential for correct invocation.

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

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

The schema only defines query as a string, but the description adds crucial meaning: it accepts a case-insensitive substring or a full GTIN/EAN barcode. This fully equips the agent to format the parameter correctly.

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

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

The description opens with a specific verb and resource: 'Find products by name, description, or barcode.' It also scopes the operation to the whole catalog, which distinguishes it from shelf/stock-focused sibling tools like list_stock or expiring_soon.

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 directs the agent to call this before create_product to detect duplicates and before add_stock/consume_product when naming is uncertain. It does not name alternative tools explicitly, but the catalog vs. shelf distinction implicitly excludes stock-status-only lookups.

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?

With no annotations, the description carries the behavioral disclosure burden. It communicates read-only journal semantics, newest-first ordering, and the availability of transaction_id in results. It does not fully describe the response structure, but for a simple query tool this is adequate.

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: purpose first, then use cases, then parameter descriptions. Every sentence contributes value and nothing is redundant with the schema.

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

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

For a tool with no output schema and no annotations, it explains what the tool returns conceptually, when to use it, how results are ordered, and all parameter meanings. Minor gaps remain around exact return fields and product value format, but no major behavior is hidden.

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 0% description coverage, so the description must define the parameters itself. It explains days as a lookback window, product as an optional filter, and limit as a row cap with newest-first ordering. It could specify whether product expects an ID or name, but the essentials are covered.

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

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

The description opens with a specific verb and resource: it is the stock journal showing what has been bought, used, opened, or corrected. It clearly establishes this as a historical audit tool, distinguishable from siblings like list_stock and consume_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?

Concrete usage contexts are provided: answering 'what did we get through this week', investigating suspicious amounts, and locating transaction_ids for undo operations. It does not explicitly name sibling alternatives or give when-not-to-use guidance, but the intended scenarios 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?

With no annotations provided, the description carries the full burden. It clearly states the operation is a location change, not a quantity change, and explains the ambiguity risk with from_location. It does not mention permissions, reversibility, or what happens if the product is not found, but the core behavioral semantics are well disclosed.

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 with a short opening, a clarifying sentence, and a clear Args list. It is slightly longer than necessary but every sentence earns its place, especially the from_location guidance. The front-loaded purpose sentence is effective.

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 4-parameter tool with no output schema and no annotations, the description covers the key decision points: what the tool does, how to identify locations, and when from_location is required. It does not describe return values or error cases, but the essential calling context is present.

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 0%, so the description must compensate. It explains product as 'name, description fragment, or barcode', to_location and from_location as id or exact name, and amount as 'in the product's stock unit'. It also explains the optionality of from_location. This adds substantial meaning beyond the raw 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 opens with a clear verb and resource: 'Move stock from one location to another' and gives a concrete example ('freezer to fridge'). It also distinguishes itself from related stock tools by emphasizing it changes location, not quantity, which separates it from add_stock, consume_product, and correct_stock.

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 explains when from_location is optional vs required, and why guessing would be wrong when stock is split. This gives an agent actionable decision criteria for when to include the parameter. It also implicitly distinguishes from sibling tools by stating it changes where, not how much.

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?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'reverse' without specifying the actual effect on the transaction record, stock levels, best-before dates, or whether the operation is irreversible. It mentions best-before dates in the context of the alternative, but not the outcome of the undo itself, leaving key behavioral aspects implicit.

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, begins with the primary purpose, and is front-loaded with the key point. The 'Args' section adds useful parameter context, though it is slightly redundant with the schema; however, it adds value by clarifying the source of the ID. Overall, it is efficient without waste.

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

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

For a single-parameter undo tool, the description covers the purpose, input source, and the reason to prefer it over alternatives. However, it stops short of describing the actual consequences of executing the undo (e.g., whether the transaction record is deleted, whether it can itself be undone, or how it affects stock and best-before dates). These details would be important for an agent to fully understand the tool's behavior.

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 schema description coverage at 0%, the description fully compensates by explaining the transaction_id parameter: it is obtained from a write tool's response or from stock_history. This is crucial, as the schema provides no help, and the description gives the exact source for the 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 specific verb and resource ('Reverse a stock transaction') and clearly differentiates the tool from alternative write operations by explaining why creating opposite entries is wrong. It is unambiguous and immediately tells an agent what the tool is for.

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 states when to use the tool ('Undoing is the right way to fix a mistake') and when not to use it (booking an opposite consume/purchase). It also tells the agent exactly where to obtain the transaction_id (from a write tool's response or stock_history), leaving no ambiguity about the correct invocation 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?

With no annotations, the description carries the full behavioral burden. It discloses that only provided arguments are changed (partial update), and crucially explains the unit-change failure mode: 'Refused while any stock is on hand... 2 Packs silently becoming 2 Grams.' It also notes that min_stock is read by below_min_stock and add_missing_to_shopping_list, providing important side-effect 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 well-structured: a clear summary sentence, an explicit scope statement, and a compact argument list. Every sentence adds value—the unit constraint and min_stock note are not fluff. It is front-loaded with purpose and alternatives, and the argument documentation is organized and readable.

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 7-parameter tool with no output schema, this description covers all necessary aspects: purpose, alternatives, parameter semantics, behavioral nuances, and caveats. An agent could confidently invoke this tool correctly without further information.

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 0%, so the description must fully document each parameter. It does so thoroughly: product (name/description fragment/barcode), name, description (brand, size, variant), category (exact name, see get_conventions), location_id (id or exact name), unit (with constraint), and min_stock (meaning and clearing behavior). Each parameter gains meaning beyond the raw schema.

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

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

States a specific verb and resource ('Edit an existing product's catalog record') and enumerates concrete use cases (typo, recategorising, moving shelf, min stock). It explicitly differentiates itself from stock-related tools by naming add_stock, consume_product, and correct_stock, so an agent can immediately identify when this tool is the right choice.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For fixing a typo, recategorising something, moving its default shelf, or setting a minimum stock level' and 'This does not touch stock amounts — use add_stock, consume_product or correct_stock for those.' It also points to get_conventions for the category parameter, giving the agent a clear routing strategy.

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