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

With no annotations, the description carries the behavioral burden itself. It discloses no key/auth requirement, warns that the catalog id is an ASCII slug to copy exactly, and lists the returned fields so the output shape is predictable. It does not mention pagination or ordering, but for a read-only catalog listing this is a minor 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 compact: it front-loads the key facts ('Free, no key', 'Lists every piece') and follows with exactness warning and usage guidance. Every sentence earns its place 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?

Since there is no output schema, the description supplies the essential return fields (catalog id, display name, width_mm, depth_mm, group) and explains the optional group filter. An agent has everything it needs to make a correct first call and interpret the response.

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 already covers 100% of the group parameter and describes it well, so the baseline is 3. The description adds 'Call it with no group first' as practical usage context, which is meaningful but not extensive extra semantic detail.

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: 'Lists every piece Roomproof knows' and enumerates the exact fields returned. It also distinguishes standard catalog items from custom pieces read via read_product, so an agent can tell it apart from sibling tools like show_plan.

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 instructs the agent to 'Call it with no group first' and notes that custom pieces 'do not need the catalog', giving clear when-to-use and when-not-to-use guidance. The 'Free, no key' statement also removes any auth prerequisite ambiguity.

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