available_serials

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

With no annotations, the description carries the full burden, and it delivers: it explicitly says 'Read-only', explains that held/consigned-out/consignment-warehouse guns are excluded by default because they are not sellable over the counter, and documents the raw-list behavior when exclude_unavailable is false. This meaningfully discloses behavior beyond what annotations or schema would provide.

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 but information-dense: purpose, return shape, default behavior, the flag for raw mode, and safety status are each covered in a single short sentence. The structure front-loads the core purpose before explaining the toggle, and no sentence is wasted.

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

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

For a read-only lookup tool with no output schema and no annotations, this is complete. It covers what the tool returns, when to use it, the default filtering behavior, how to opt out, and that it is safe to call. The agent has everything needed to invoke it correctly in both the normal and audit use cases.

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 thoroughly explains exclude_unavailable, including its default and the difference between POS-picker and raw-audit behavior. item_codes is less explicit—it is inferable from the return shape and 'per firearm item', but the accepted formats and cardinality are not directly described. Still, the description adds meaning well beyond the bare schema.

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

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

The description clearly states a specific verb and resource: it returns in-stock serial numbers per firearm item with per-gun sell prices. The return-shape example and the phrase 'which units do we have of this model + at what price' make it easy to distinguish from broader stock or consignment tools without opening the schema.

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 use case: 'Use for which units do we have of this model + at what price'. It also explains when to change the default parameter, including the inventory-audit scenario that requires exclude_unavailable=false, which is strong practical guidance beyond just describing the tool.

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