List Inventory

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

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

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

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

The description is well-organized: opens with a clear purpose statement, then breaks down parameters, and closes with return structure. Each sentence adds value and there is no redundancy or fluff.

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

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

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

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

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

Input schema covers 100% of the parameters with descriptions, defaults, and ranges. The description repeats the same parameter details without adding new meaning beyond what's already in the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the tool lists on-hand inventory records with warehouse locations, paginated. It distinguishes itself from sibling tools like list_products and report_total_inventory by specifying the inventory scope and the inventoryIdentifier field used by mutation tools.

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

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

The description provides clear context by noting that inventoryIdentifier is used by add/adjust/remove tools, implying when this list tool is relevant. It does not explicitly name alternative tools for reports or aggregation, but the purpose is self-evident enough for an agent to select it appropriately.

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