Search Ebay

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 reveals several non-obvious behaviors: zero-result responses include a `hint` and may have already had an automatic narrowed retry ("one automatic narrowed retry may already have run"), and prices/currency follow the configured marketplace. It also states that query is a strict AND over titles only, which is a key behavioral trait. No rate limits or auth are mentioned, but the disclosed behaviors are substantial.

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 moderately long but well-structured: it opens with the core purpose, then covers query semantics, return format, the sibling tool, and the price-parameter relationship. It uses references to parameter descriptions rather than repeating them verbatim, which keeps it efficient. A slightly tighter first sentence could improve it, but the organization is logical and no sentence is wasted.

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 (7 parameters, output schema present, no nested objects), the description provides enough context for an agent to use it correctly. It explains the essential query constraints, previews the result fields, flags the automatic retry behavior, and clearly points to parameter descriptions for detailed syntax. The absence of error-handling specifics is mitigated by the hint mechanism disclosure, and the presence of an output schema excuses the need to describe return structures in 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?

Schema description coverage is 100%, so the baseline is 3. The tool description adds minimal semantic value beyond what the parameter descriptions already provide: it mostly restates the query rules and points the reader to those descriptions ("see the `query` field's description"). It does add cross-tool context (pass item_id to get_item_details) and clarifies min/max as convenience over filter_expr, but the parameter specifics are already richly documented in the schema, so the description does not meaningfully elevate understanding.

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 clear statement of the verb and resource: "Search eBay listings by keyword, with optional filters and sorting." It further differentiates from the sibling tool by explicitly directing "Pass an item's `item_id` to `get_item_details` for the full record," making the boundary between listing summaries and full details unambiguous.

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 explicit when-to-use and when-not-to-use guidance. It names the alternative tool for full details, and it gives precise rules for parameter combinations: "do not also set a `price` or `priceCurrency` filter in filter_expr" when using min_price/max_price, and "prefer `min_price`/`max_price` below instead of writing this by hand" for price ranges. It also offers market-specific advice (e.g., German terms) that helps an agent decide how to compose queries.

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