List the 11 tracked bullion dealers (name and city): 8 French (Or.fr, Godot & Fils, Pièces-Or, Gold.fr, Maison Joubert, Or & Change, GoldUnion, GoldAvenue, BDOR) and 2 European (GoldSilver.be Brussels, StoneX Bullion Frankfurt). Optional city or name filter.
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | French city name to filter. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It conveys a read-only listing with optional filtering and states that output includes name and city. However, it advertises a 'name filter' that does not exist in the input schema and contains an inaccurate dealer count, which undermines confidence in behavioral accuracy.
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 core sentence is concise and front-loaded, but the exhaustive dealer enumeration is unnecessary and introduces a factual error (8 vs 9 French dealers). The added detail creates confusion without adding reliable value.
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 low-complexity list tool with one optional parameter and no output schema, the description gives the essential return fields (name and city) and the filter option. It is not fully complete because the unsupported name filter and inaccurate count could cause incorrect usage, and it does not explain behavior when no matches are found.
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?
The schema documents the only real parameter (city) with 100% coverage, so the baseline is 3. The description actively detracts from this by adding 'or name filter,' which has no corresponding parameter in the schema. This could mislead the agent into passing a nonexistent `name` argument.
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 clear verb ('List') and resource ('tracked bullion dealers'), and specifies the output fields (name and city), which distinguishes it from the coin/price-focused sibling tools. However, it claims '8 French' while listing nine French dealer names, so the purpose is clear but the counts are inaccurate.
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 provides clear context that this tool is for retrieving dealer data, but it does not explicitly mention when to use it versus alternatives or when not to use it. Usage is implied by the resource and sibling tool names, not stated directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
compare_prices and get_best_price are nearly identical: both accept a coin slug or name and return the same ranked list of all 11 dealer prices with in-stock status. The other tools are distinct, but this clear functional overlap creates real selection ambiguity.
All six tools follow a consistent lowercase snake_case verb_noun pattern: compare_coins, compare_prices, get_best_price, get_coin_specs, list_dealers, search_coins. Verbs are action-oriented and predictable, making the tool surface easy to navigate.
Six tools is a reasonable size for a bullion coin information and price comparison server. The count is not excessive, though one tool is largely redundant with another, so the set is slightly less tight than it could be.
The server covers the apparent domain well: searching the catalog, retrieving full coin specs, comparing dealer prices, doing side-by-side coin comparisons, and listing dealers. Minor gaps like a dedicated spot price tool or dealer detail view exist, but core informational needs are covered.
