Auction status

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond them: the full return field set, the conditional presence of minimum_next_bid, the warning that bids are observations that may change, that seller reserves and bidder identities are never exposed, and that bidding requires a verified dealer account and a human decision. Error behavior is spelled out ('isError=true with structuredContent.error') including the closed-live-auction case.

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?

Purpose and scope lead, then the acquisition workflow, then return shape, then error semantics and prerequisites. Every sentence carries load, and the long field enumeration is justified because there is no output schema.

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 single-parameter read tool with no output schema, the description supplies the return field list, conditional field logic, error contract, data-freshness caveat, privacy guarantees, and the account-level prerequisite for the related write action. Nothing an agent needs to call it correctly 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 description coverage is 100% and the parameter's schema entry already specifies provenance, the 64-char format, the listing_id/URL exclusion and the no-fabrication rule, so the description mostly restates it. It adds the surrounding discovery workflow but no new constraint on the parameter itself.

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 ('Read public status for one known JOY auction') plus an explicit scope exclusion ('without bidding'). It also routes the agent away from siblings by naming get_vehicle for specs and search_vehicles for discovery, so it is distinguishable without opening any 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 a concrete acquisition path ('search_vehicles, then get_vehicle, then its non-empty auction_id'), accepts an alternative valid source (buyer-provided public ID), and states an explicit prohibition ('Do not guess an ID when get_vehicle returns no auction_id'). It also names the alternative tool for car specs and asking price.

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