carmax_search

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

With no annotations provided, the description carries the full burden. It discloses that the data is credential-free and sourced from CarMax's mobile-app search API, which is valuable insider context. It also enumerates the return structure (make, model, trim, year, mileage, colors, engine, fuel economy, pricing, store, images, facets, total count), offering transparency about what the agent will receive.

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 compact overall but has redundancies: the first sentence 'Search CarMax vehicle listings' is nearly repeated by the second 'Searches CarMax for used car listings.' This wastes a sentence, though the rest is efficiently packed and front-loaded with the most important information.

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?

Since there is no output schema, the description appropriately enumerates the return fields and notes the presence of facets and total count. It also mentions the data source and credential-free nature. It could be slightly more complete by explicitly noting pagination behavior, but the schema already covers the 'page' parameter with 48-per-page detail.

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 provides 100% parameter descriptions, so the baseline is 3. The description does not add extra meaning about parameters beyond what the schema already documents; it focuses on output rather than input semantics.

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 immediately uses a specific verb and resource ('Search CarMax vehicle listings') and elaborates with concrete output details: normalized vehicle summaries, search facets with live counts, and total matching count. This distinguishes it from sibling tools like carmax_vehicle or carmax_search_suggestions, which focus on specific vehicles or suggestions.

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 context: it searches used car listings and is credential-free, which tells the agent no authentication is required. However, it does not explicitly mention when to avoid this tool in favor of siblings like carmax_vehicle or autotrader_search, so it lacks direct exclusions or alternative guidance.

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