find_commodity

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

With no annotations, the description carries the full disclosure burden and does deliver real behavioral facts beyond schema: data comes from live Spansh market snapshots, results are sorted by stock size then distance, and stock rotates so results can be stale. The notable undisclosed behavior is how 'near you' is resolved when x/y/z, system_name, and journal_dir are all omitted, and what happens if no reference location exists.

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?

Three short sentences, front-loaded with the core purpose and with the parameter semantics immediately after. Slightly awkward line-wrapping and the parenthetical snapshot note interrupt flow, but no sentence is filler.

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?

An output schema exists, so return values need not be described, and the freshness/ordering behavior is covered. However, for a tool with 10 parameters and multiple mutually redundant location inputs, the missing explanation of how location is determined and how min_qty/max_results constrain the ranking leaves a real gap an agent will hit on first call.

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 0% across 10 parameters, so the description must compensate and it only does so for mode (buy vs sell semantics), which is genuinely useful since mode has no enum. Nine other parameters are left entirely unexplained, including the competing location inputs (x/y/z vs system_name vs journal_dir), min_qty, max_results, and large_pad_only, so an agent cannot infer precedence or units from the definition.

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?

"Best stations trading a commodity near you" names a concrete verb (find/rank stations), the resource (commodity market), and the ranking criterion, so the agent knows this is a commodity-to-station lookup rather than a general station search. It does not explicitly distinguish itself from close siblings like find_multi_supply, spansh_find_nearby_stations, or inara_search_nearest, which keeps it out of the top score.

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 supplies the one decision rule that matters most for the mode parameter (buy = supply, sell = demand) and warns to verify in-game before flying, which implies use for planning rather than authoritative trade execution. It never says when to prefer this over find_multi_supply, spansh_find_nearby_stations, or find_local_opportunities, leaving alternative selection to inference.

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