hermes_suggest

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

Annotations are not provided, so the description carries the full burden. It discloses that an empty query is allowed and returns default suggestions instead of an error, which is useful edge-case behavior. It doesn't mention return format or pagination, but for a suggestion tool, this is adequate. No contradictions with annotations since none exist.

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 two sentences, front-loaded with the core purpose and then adding the key integration hint. It is efficient with no fluff, though it could be slightly more structured but is still concise and readable.

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?

Given the tool has only 2 optional parameters and no output schema, the description covers the essential aspects: what it returns, the empty-query behavior, and the link to category browsing. It doesn't describe output structure, but that's less critical for a suggestion tool. Slight gap in not mentioning locale behavior, but overall sufficient.

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 coverage is 100% with clear descriptions for both parameters: query (partial term, can be empty) and locale (enum of market codes). The description adds value by clarifying that the query is for autocomplete and that category codes feed into other tools, but the locale parameter is fully described in schema, so no extra needed. Baseline 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 it returns Hermès' search autocomplete for a partial term, including matching categories with item counts and matching products. It is distinct from hermes_search (which likely does full search) and hermes_category (which browses categories), and explicitly notes the category codes are the same as those accepted by hermes-category, making the purpose clear.

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 explains when to use this tool: for autocomplete suggestions on a partial term, and how it connects to category browsing. It doesn't explicitly state when not to use it or compare to hermes_search, but given sibling tools like hermes_search, hermes_category, the context is implied enough. Could be stronger with a direct alternative mention.

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