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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: available_now is true only when the artwork itself can be transacted today, prices are fixed and shipping-inclusive, stock items ship within 48 hours, offer_text must be pasted untouched, and title resolution is surname-guarded with a relevance "score" and a "warning" flag. It also warns that currency follows the strict no-fallback rule of the quotation tools.

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 content is front-loaded and relevant, but it is delivered as one very long em-dash-and-parenthesis-chained sentence covering channels, output fields, availability semantics, triggers, identification strategy, and list mode. The density forces re-reading; splitting into short labeled sentences (channels / when to call / how to identify / list mode) would preserve all information at far lower parsing cost.

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 key returned fields (available_now, available_now_summary, stock_quantity, price, size, buy_url, offer_text) for each channel type. Combined with the trigger conditions and the two operating modes, an agent has everything needed to select and invoke it correctly.

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; the description earns above that by explaining the resolution precedence (pk, then exact title, then surname-guarded search) and the meaning of the returned "score"/"warning" values, which the schema does not convey. It also clarifies that channel narrows offers when pk/title is supplied but switches the tool into list mode when they are absent — a semantic distinction the schema only hints at.

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 states a specific verb and resource — return every purchasable offer for ONE artwork across its sales channels — and enumerates the concrete channel types (ready-made stock, auction lot, owner original, studio collectible, reproduction, print, digital licence). It explicitly separates itself from the made-to-order pricing path by naming get_a_quotation as the tool for size-based print/reproduction prices, so an agent can distinguish it from siblings without opening schemas.

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?

It gives explicit trigger conditions: call whenever a customer asks about availability, stock, ready-to-ship, discount, auction, or real-object price, and specifically before any "yes, it is available". It also defines the alternate invocation mode (no pk or title → list mode by channel) with example utterances, and routes made-to-order pricing to get_a_quotation.

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