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

Annotations already declare readOnly, idempotent, closed-world, non-destructive behavior, so the safety profile is covered. The description adds real context beyond that: what a result contains (brand, catalog price, page URL) and the non-obvious rule that models and configurations such as steel or color are separate products, which changes how the agent interprets hits. It does not cover result ordering or pagination behavior.

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?

Three tight sentences: what it searches, what comes back, then the routing hint. The catalog scope and the separate-variants caveat are front-loaded before the pointer to find_offers, and no sentence is filler.

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?

There is no output schema, and the description compensates by naming the returned fields (brand, catalog price, page) and the catalog-price-versus-live-price distinction. For a three-parameter search tool this is nearly complete, with only result ordering and empty-result behavior left unspecified.

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 coverage is 100%, with query, limit, and in_stock_only all documented in the schema itself, so the baseline is 3. The description adds only indirect guidance about query semantics (variants are separate products), and says nothing about limit or the default in-stock filter, so it does not meaningfully exceed the schema.

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 ('Search Drop Beacon's catalog of 150,000+ everyday-carry products') and scopes it with concrete category examples (knives, flashlights, sliders, pens, multitools). It also separates itself from the price-oriented siblings by naming find_offers as the follow-up for live prices.

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 explicit sequencing guidance ('Use find_offers next for live prices across retailers'), which tells the agent this tool is the catalog lookup step, not the deal-hunting step. It does not state when not to use it versus deal_check, top_deals, or upcoming, but the context it does provide is clear.

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