search

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

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond them by disclosing tokenization, synonym expansion (ruby↔rubis), the exact fields matched, merge/dedup behavior ranked by top realized USD sales, and the limit ceiling of 100. That is exactly the kind of engine-level behavior an agent cannot infer from structured fields.

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?

Front-loaded one-line summary followed by mechanics and an Args block, with no filler sentences. Minor redundancy: the intro already explains the no-category fan-out and merge behavior, then the category arg repeats part of it, making it slightly longer than necessary.

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 4-param search tool with an output schema, everything the agent needs to call correctly is present: matching semantics, result merging/ordering, filter syntax, and size caps. Return-value shape is correctly left to the output schema.

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 carries the full burden and does so for all four parameters: query examples ('Daytona 116500', 'Birkin 25'), the dual alias/plain-word semantics of category, the AND-ed filter dict shape with a concrete usd_price_decimal gte example, and limit's default 25 / max 100.

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 specific verb and resource with explicit scope: 'Whole-market keyword search across every ALT/FNDATA category at once.' The line 'so you don't have to guess which table holds an item' implicitly positions it against the per-table query_table sibling, letting an agent choose without opening the schema.

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?

Gives clear use context (use when you don't know which table holds an item; omit category to fan out) and explains that category can be a table alias or a plain word, with gemstone hints searching both loose gems and mounted jewelry. It stops short of explicitly naming query_table or price_check as alternatives, so there is no explicit when-not-to-use routing.

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