add_to_shopping_list

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.