Skip to main content
Glama

Primary Source Commodities

Trade Calculation

trade.calculate
Read-onlyIdempotent

Deterministic trade arithmetic over numbers you supply: landed cost, trade margin, break-even price, or the effect of a USD move. Nothing is sourced — there is no free source for duty rates, freight or insurance, so an input you omit is excluded from the total and reported in missing, never defaulted to zero. Use price.latest first if you want a benchmark price to pass as unit_price.

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": {
      "calculation": "<calculation>"
    },
    "name": "trade.calculate"
  }
}

Input Schema

NameRequiredDescriptionDefault
amountNofx_impact: amount held in the foreign currency.
fx_rateNolanded_cost: units of quote_currency per USD. fx_impact: the rate to shock.
incotermNolanded_cost: decides which costs your price already carries, so it shapes `missing`. CIF already includes freight and insurance. Example: CIF.
port_usdNolanded_cost: port charges.
quantityNoQuantity. Example: 100.
buy_priceNotrade_margin, break_even: purchase price per unit.
costs_usdNotrade_margin, break_even: other costs.
rate_unitNofx_impact: direction of fx_rate, read not inferred. Example: GHS/USD means cedi per dollar.
price_unitNolanded_cost: unit of unit_price. Example: USD/metric ton.
sell_priceNotrade_margin: sale price per unit.
unit_priceNolanded_cost: price per unit. Example: 1133.13.
calculationYesWhich calculation to run. Example: landed_cost.
freight_usdNolanded_cost: your freight cost. Omit and it is reported missing, not assumed zero.
handling_usdNolanded_cost: handling charges.
usd_move_pctNofx_impact: percent the USD strengthens. Example: 5.
duty_rate_pctNolanded_cost: your import duty rate, percent. Example: 8.
insurance_usdNolanded_cost: your insurance cost.
quantity_unitNolanded_cost: unit of quantity. Example: metric ton.
quote_currencyNolanded_cost: currency for the total. Needs fx_rate — no rate is sourced. Example: GHS.

Output Schema

NameRequiredDescriptionDefault
unitYesUnit of the result
notesNoCaveats, including unmodelled distinctions
valueYesThe result
formulaNoHow it was computed
missingYesInputs not supplied. Their components are excluded from the total, not defaulted.
partialYesTrue when anything is missing
componentsYesEach part of the build-up, with where its number came from
disclaimerNo
assumptionsNoCaller-supplied inputs, echoed
calculationYesWhich calculation ran

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower; the description still adds real value by disclosing that omitted inputs are excluded from the total and surfaced in `missing` rather than defaulted to zero. That is the non-obvious behavior an agent most needs. It does not describe error or validation responses (e.g., quote_currency without fx_rate), which keeps it below a 5.

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

Conciseness5/5

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

Three sentences, front-loaded with the core contract ('nothing is sourced, omissions are reported not zeroed') before the sibling routing hint. No filler or restatement of the title.

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

Completeness5/5

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

With 19 parameters at full schema coverage and an output schema covering the return shape, the description only needs to convey the sourcing model and the `missing` contract — which it does in two sentences. Nothing an agent needs to call it correctly is absent.

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

Parameters4/5

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

Schema coverage is 100%, so baseline would be 3, but the description adds cross-parameter meaning the schema only hints at: omission semantics and the `missing` reporting contract that governs every optional cost field, plus the dependency of quote_currency on fx_rate. That is genuine meaning beyond the per-field descriptions.

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

Purpose5/5

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

Names a specific verb and resource ('Deterministic trade arithmetic over numbers you supply') and enumerates the four supported calculations — landed cost, trade margin, break-even, fx impact — which map directly to the `calculation` enum. It also distinguishes the tool from price-oriented siblings by stating nothing is sourced.

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?

Gives a clear routing instruction: use price.latest first when you need a benchmark to pass as unit_price, and makes explicit that the tool sources nothing so callers must supply inputs. It stops short of stating when-not-to-use cases or which calculation to pick for a given business question, leaving that to the enum.

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