catalog_search

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it does so well. It explains how filters are interpreted (list value means 'any of these'), how accepts_name filters are resolved to upstream ids, and what the bridge reports in resolutions. It also warns that mixing phrases like 'under $80' into the query fights the filter. It stops short of explicitly stating that the operation is read-only or describing error/edge-case behavior, but for a search tool the read-only nature is strongly implied.

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 appropriately sized for a tool with six parameters. The opening sentence front-loads the core purpose, and the Args section is a clean bulleted list where every line adds unique information. There is no filler, repetition of schema type information, or unnecessary prose.

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 complexity of six parameters, no annotations, and the existence of an output schema, the description is highly complete. It covers parameter defaults, value sources, filter interpretation, name resolution behavior, and pagination semantics. The only missing piece is explicit sibling selection guidance, but that is already accounted for in the usage guidelines dimension; for invoking this specific tool correctly, an agent has everything it needs.

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 fully compensate, and it does. Every one of the six parameters is explained with meaningful semantics beyond the schema's bare type declarations: query is keyword-only, api is optional when only one catalog is configured, filters map names from list_catalogs to values, sort comes from list_catalogs, page is 1-based, and page_size defaults to the catalog's configured size. This is exactly the kind of parameter documentation an agent needs.

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: 'Search a catalog with keywords and explicit structured filters.' It clearly distinguishes this tool from the sibling list_catalogs, catalog_get_item, and understand_query by emphasizing structured filters, and the term 'explicit structured filters' implicitly contrasts with smart_search. The first sentence alone tells an agent what this tool does and where it fits.

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 strong parameter-level guidance: query should contain only keywords, constraints belong in filters, filter names come from list_catalogs, and sort names also come from list_catalogs. However, it never explicitly states when to choose this tool over smart_search or understand_query, nor does it say 'use this when you have structured filters, not for natural language queries.' The usage context is implied rather than explicitly contrasted with alternatives.

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