Discover car auction links

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

Annotations already declare read-only/idempotent/non-destructive, and the description still adds non-obvious traits: unpriced cars remain eligible, an empty items page may still have a next_page, source counts are not auction counts, links may be ended or feature-gated, and no private lot is exposed or bid placed. These are exactly the behavioral edges annotations cannot convey.

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 with purpose, then organized into three tight bullets covering filtering, pagination, and safety. Nearly every clause carries operational weight, though the pagination bullet is dense enough to require a second read.

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?

An output schema exists, so return values need not be explained; what an agent still needs — how to filter, how pagination terminates, what the read exposes — is fully covered. Nothing material for correct invocation is missing.

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%, so the baseline is 3, but the description adds real semantics beyond the schema: make scans a manufacturer's listings while query is reserved for model-specific requests, and the intersection of the two is explained operationally. It stops short of format examples that the schema does not already imply.

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?

Opens with a specific verb+resource+scope: "Discover existing public car-auction IDs for get_auction." It immediately names the sibling it is not (get_vehicle for a known listing) and positions itself as the discovery step in a two-tool flow, so an agent can route correctly without opening either 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 explicit when-to-use guidance (express the desired car, not an auction title or bid), when-not-to-add filters (add query only for a model-specific request), and names the follow-up tool (get_auction) plus the narrowing action at the source limit. Alternatives and exclusions are both stated.

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