grailed_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. It explicitly discloses that keyword search uses Algolia's typo-tolerant relevance ranking and is 'not a guaranteed exact match.' It also states that zero-match queries return a well-formed empty result rather than an error. These are important behavioral traits. It does not mention rate limits, authentication, or the response structure, but for a search tool these are not critical gaps. The disclosed behaviors are meaningful and go beyond what the schema provides.

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 several sentences long but every sentence adds necessary information: the core purpose, optionality and combination logic, value sourcing, closed enums, search behavior, and error handling. It is front-loaded with the primary action and resource. While slightly verbose, it avoids redundancy and remains focused on actionable details. The structure is logical, moving from general purpose to specific parameter semantics and edge cases.

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's complexity (12 parameters, no output schema), the description is quite complete. It explains the search vs. browse modes, how parameters combine, where valid values come from, the sorting default (heat), and the behavior for zero matches. It does not describe the response structure, but without an output schema that would be a gap; however, it covers the key behavioral and parameter aspects needed to call the tool correctly. Pagination is covered by the schema (page and limit). The description is sufficient for an agent to use this tool effectively.

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 all 12 parameters with descriptions, so the baseline is 3. The description adds significant value by explaining the AND combination logic across all optional filters, clarifying that q can be combined with any facet, and specifying the source of valid values for designer, department, category, size, and color (from grailed-designers and grailed-categories). It also notes that condition and sort are closed enums. These semantics are not present in the schema and are crucial for correct usage, elevating the score above baseline.

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 the tool's function: 'Search or browse Grailed active listings.' It names the specific verb (search/browse) and resource (Grailed's peer-to-peer resale marketplace for currently-active listings). This distinguishes it from sibling tools like grailed_listing (specific listing), grailed_seller (seller info), and grailed_categories (facet values). The purpose is unambiguous and immediately conveys the tool's role as the search/browse entry point.

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 provides clear usage guidance: it explains that all parameters are optional and combine as AND, that a free-text q can be combined with any facet filter, and that omitting all fields browses the full catalog by 'heat' ranking. It also notes that designer and facet values come from grailed-designers and grailed-categories, implying those tools are used to obtain valid values. However, it does not explicitly state when to prefer this over specific alternatives like grailed_listing, though the context makes it implicit. The guidance is solid but could be more explicit about exclusions.

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