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

Beyond the readOnly and idempotent annotations, the description discloses important behaviors: the price is approximate and bucket-based, independent of mint, dependent only on metal/type/weight, and not a binding offer. It also provides legal and informational limitations, which is valuable context an agent should know before presenting results to a user.

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 description is front-loaded with the core purpose and then the key behavioral caveat, followed by legal disclaimers. The legal and disclaimer sentences add some length, but they are relevant for a financial pricing tool and do not obscure the operational content. Overall, it earns its place without excessive redundancy.

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 tool with three optional parameters, clear annotations, and no output schema, the description is complete: it explains what the tool returns, how to invoke it with and without parameters, how the price model works, and what caveats apply. An agent has enough information to decide when and how to call it and what expectations to set with the user.

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 only 33%, so the description must compensate, and it does: it explains that metal, form, and weight drive the estimate, clarifies that all parameters are optional with no-parameter behavior returning the full price list, and describes how weight/type affect pricing. It does not enumerate the exact enum options, but those are self-descriptive from 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?

The description states the specific purpose: it returns the buyback price IDFMETALE pays for gold or silver, and explicitly contrasts this with the sale price retrievable via get_live_price. It names the resource and the pricing perspective clearly, so an agent can distinguish it from sibling tools without inspecting the 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?

The description gives explicit usage guidance: provide metal, form, and weight to get an estimated valuation, or call with no parameters to receive the full buyback price list. It also names the alternative tool get_live_price for sale prices and explains when the tool's result is not binding, making selection straightforward.

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