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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that results are compact rows and that category/keyword filtering is supported, but it does not disclose pagination, ordering, result limits, or empty-result behavior. This is acceptable for a simple read-only list tool but not particularly rich.

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 one dense, efficient sentence. It front-loads the tool's purpose, then states filter options, return style, and the alternative tool with no filler. The category mappings are necessary and not wasteful.

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 optional-filter list operation, the description covers the core behavior and return granularity, and routes to get_product for richer details. Since no output schema exists, the description could mention exact returned fields, but the compact-row note is sufficient for tool selection and 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 input schema describes keyword but leaves the category enum values semantically empty. The description compensates by mapping power, distribution, storage, and emobility to concrete product domains, significantly improving param understanding. Keyword's case-insensitive matching is already in the schema, so the main added value is the category clarification.

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 in the catalogue', then clarifies it returns compact rows rather than full specifications. It explicitly contrasts with get_product, so an agent can distinguish this tool from its sibling without inspecting 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 states when to use get_product instead ('call get_product for full specifications'), giving a clear routing signal for the most relevant sibling. It does not explicitly discuss other siblings like search_knowledge, but enough context is provided for the main decision.

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