catalogue

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

No annotations are present, so the description carries the burden. It discloses that this is a non-mutating read and that data is live rather than cached or remembered. It stops short of describing error behavior or the response envelope, which is a moderate gap for a tool with no output schema.

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?

Three short sentences front-load the operation and payload, then give the usage context and data-freshness rationale. No filler or repeated schema details.

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 single-parameter lookup with no output schema, the description covers what the tool returns, where the id comes from, and when to call it. It omits error cases, but the core information an agent needs to select and invoke it is present.

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 single id parameter is fully documented in the schema, including provenance from search_products and an example value. The description merely reiterates that the id comes from search_products, so it adds little beyond the schema, meeting the baseline for full schema coverage.

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?

States a precise verb and object: reads a single SecuresVault product by id, and enumerates the fields it returns (EUR price, description, colour/size variants). This clearly differentiates it from search_products, which returns a list of matches.

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?

Provides an explicit invocation context: use it before describing a concrete product so prices and options are live, and tells the caller the id comes from search_products. It does not enumerate exclusions or contrast with list_categories, but the intended trigger is clear.

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

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

With no annotations, the description carries the behavioral burden. It discloses that the tool returns authoritative category keys, includes a 'live item count,' and should be treated as the source of truth for filtering. It does not explicitly state side-effect status, but 'List' strongly implies a read-only operation.

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?

Two sentences, both purposeful. The first states exactly what the tool returns; the second gives actionable guidance. No fluff or repetition.

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 zero-parameter listing tool with no output schema, the description covers the output fields, the operational context, and the relationship to sibling tools. An agent has enough to decide when to call it and what to do with the result.

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 tool takes zero parameters, so the baseline is 4. There is no parameter detail to add, and the empty input schema is fully covered.

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 every SecuresVault category with its key, human label and live item count.' It clearly distinguishes this tool from the product-focused siblings by focusing on categories and explicitly naming search_products as the consumer of the keys.

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 gives an explicit when-to-use directive: 'Call this first whenever you intend to filter by category.' It also states why the alternative would need this tool ('the keys are the only values search_products accepts') and warns against relying on memorized values.

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

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

With no annotations, the description carries the full burden and does so well. It discloses that category labels are silently ignored (leading to unfiltered results), that supplying neither query nor category returns newest listings, and that results include a canonical URL which must be given to the user, not an API URL. This goes beyond a generic 'search' probe and sets clear expectations for output handling.

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?

Four sentences, front-loaded with purpose and usage guidance. It packs a lot of information (result contents, parameter rules, output format) without redundancy. The only minor inefficiency is that the category-key warning is quite lengthy, but it is essential and well-targeted.

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 search tool with no output schema and no annotations, the description covers core invocation rules, output expectations (URLs, prices), and fallback behaviors. It doesn't mention pagination details (handled by schema) or error conditions, but for a standard list/search endpoint this is adequate and complete for correct 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 schema already documents all four parameters (100% coverage). The description adds valuable cross-parameter semantics: the requirement that query or category be supplied (and the consequence if not), and the crucial distinction that category must be a key from list_categories, not a label. It also hints that query and category are alternatives, which is not inferable from the schema alone.

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 ('Find physical products for sale on SecuresVault') and distinguishes itself from siblings by mentioning live EUR prices and buyable links, and by referencing list_categories for category keys. It is clearly a search/list tool rather than a single-product fetcher, so an agent can tell it apart from get_product.

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?

Explicitly states when to use: 'when a user asks where to buy something, what something costs in euros, or wants product options in a category.' It also explains the query/category requirement and the fallback behavior when neither is supplied, and warns that a human label is silently ignored. This gives clear selection criteria without ambiguity.

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