Skip to main content
Glama

Primary Source Commodities

Compare Sourcing Countries

sourcing.compare
Read-onlyIdempotent

For one commodity and year, compare countries as a source: what the grower was paid (FAOSTAT farm gate) against what it left the country for (UN Comtrade export unit value), plus the share reaching the grower. Ranked cheapest first on a named observable field — there is NO opportunity score, because the weights would be invented. Supply freight_usd / duty_rate_pct to add a landed cost; absent costs are never defaulted, they are listed in missing. Annual data: this supports structural comparison, not an arbitrage claim. Covers the seven crops FAOSTAT prices.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "commodity": "<commodity>"
    },
    "name": "sourcing.compare"
  }
}

Input Schema

NameRequiredDescriptionDefault
yearNoFour-digit year; defaults to the latest available.
currencyNoOptional ISO currency for an additional converted view.
incotermNo
port_usdNo
commodityYesInstrument code. Example: CC for cocoa.
freight_usdNoCaller-supplied freight per tonne.
handling_usdNo
duty_rate_pctNoCaller-supplied duty rate, percent.
insurance_usdNo

Output Schema

NameRequiredDescriptionDefault
yearYes
notesYesRead before presenting any figure from this tool.
missingNoCost fields not supplied, hence excluded
partialNo
availableYesFalse when fewer than two countries could be compared. Served free in that case.
commodityYes
countriesYesCheapest first on the ranked field
ranked_byNoThe observable field the list is sorted by
license_tagNo
unavailableNoSources that could not contribute, each with the reason
sources_usedNo
years_availableNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.1/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral facts: ranking is cheapest-first on a named observable field, there is deliberately no composite 'opportunity score', absent cost inputs are never defaulted but appear in `missing`, and coverage is limited to seven crops. That is exactly the kind of output-shaping and data-handling disclosure annotations cannot carry.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Content is front-loaded with scope and comparison basis, then cost modifiers, then the interpretive caveat, and every clause carries information — the 'no opportunity score' aside explains a design choice that would otherwise confuse. It is dense and em-dash-heavy, marginally longer than needed, but there is no filler sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return formatting need not be explained, and annotations cover the safety profile; what remains is covered well (ranking rule, missing-data policy, annual granularity, crop coverage). The gap is the interaction of the landed-cost parameters (incoterm, port, handling, insurance) with the ones described, which a caller building a CIF/CFR view would want spelled out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 56% across 9 parameters, so several fields (port_usd, handling_usd, insurance_usd, incoterm, currency, year) rely on the schema alone. The description does add real meaning for freight_usd and duty_rate_pct by explaining they combine into a landed cost and that omitting them yields entries in `missing`, but it says nothing about how the other cost/incoterm parameters interact.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource ('compare countries as a source' for one commodity and year) and pins down the two data sources compared (FAOSTAT farm gate vs UN Comtrade export unit value) plus the derived 'share reaching the grower'. That is well beyond a restated title, though it never names the sibling call (e.g. trade.calculate or producer.prices) it should replace, leaving that routing to the agent's inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Sets clear scope ('one commodity and year'), tells the caller to supply freight_usd / duty_rate_pct to obtain a landed cost, and explicitly bounds interpretation with 'annual data: this supports structural comparison, not an arbitrage claim' and 'covers the seven crops FAOSTAT prices'. No explicit alternative tool is named for the cases this tool does not cover, so it stops short of full when/when-not routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources