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

With readOnlyHint=true, destructiveHint=false and openWorldHint=true already covering the safety profile, the description still adds real behavioral context: pricing is live, refresh re-queries external sellers, and that call takes tens of seconds. This latency/external-call disclosure is exactly the kind of value annotations cannot carry, though caching behavior beyond the refresh flag is unstated.

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?

Two sentences, no waste, front-loaded with the resource and its payload. The parenthetical enumeration is dense but each field listed earns its place because no output schema exists to describe the return shape.

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?

With no output schema, the description fully substitutes by enumerating the per-line fields and totals; required/optional params are covered by the schema and the safety profile by annotations. The latency cost of refresh is disclosed, leaving nothing an agent needs to call 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 schema already documents all three parameters and the baseline is 3. The description adds marginal but genuine semantics by qualifying refresh as a slow external re-query ('tens of seconds'), information absent from the schema's 'Ask the sellers again instead of the stored prices.'

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 gives a specific verb+resource ('live-priced BOM') and enumerates the exact contents of each line (references, value, footprint, offer details, alternatives, totals), so an agent knows what it returns without opening a schema. It does not explicitly contrast itself against nearby siblings such as choose_bom_part or get_order_price, which keeps it short of a 5.

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?

Usage is only implied: the description explains what 'refresh' does and that it costs tens of seconds, which implicitly guides when to set it, but there is no explicit when-to-use vs. alternative guidance or stated conditions for choosing this over get_order_price or choose_bom_part.

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