01Safety
30.0 / 30
What changed in the harness
Selection accuracy 96→100, token cost up 3%, unconfirmed writes 100%→100%.
Category breakdown
Where the score comes from.
Earned points across the four signals Gradable measures. Safety and Legibility are scored out of 30; Economics and Discoverability are scored out of 20.
02Legibility
24.2 / 30
03Economics
17.3 / 20
04Discoverability
14.8 / 20
Highest-impact fix
Estimated gain +1 pointRewrite 8 underspecified tool descriptions
State each tool's behavior, explain every parameter, and declare return semantics, prioritizing tools exercised by failed selection tasks.
Description evidence
Defects and rewrites.
8 defects found across the exposed tool descriptions. Suggested rewrites make purpose, inputs, boundaries, and returns easier for an agent to understand.
| Tool | Defect types | Suggested rewrite |
|---|---|---|
opa_get_product_facts |
no_return_description |
Get the reviewed, versioned OilPriceAPI product contract covering product scope, evaluation offer, pricing URL, freshness policy, catalog and entitlement wording, authentication, canonical first request, keyless demo, and data-rights boundaries. Use this instead of model memory or package prose for questions about OilPriceAPI itself. Returns the current contract as structured text/JSON addressing each of those topics, along with its version identifier. No API key or paid-data entitlement is required. |
opa_get_futures |
no_return_description |
Get the latest front-month futures contract price for energy commodities. Use when the user asks about futures, forward prices, or contract prices. Supports crude oil (BZ/ice-brent = Brent, CL/ice-wti = WTI), ICE Gasoil (ice-gasoil), natural gas (natural-gas), European TTF gas (ttf-gas), LNG JKM (lng-jkm), EUA carbon (eua-carbon), and UK carbon (uk-carbon). Returns the settlement price, currency, contract/expiry month, and timestamp for the selected instrument. For the full forward curve across all contract months, use opa_get_futures_curve instead. |
opa_get_drilling |
no_return_description |
Get a drilling activity snapshot. Use when the user asks about drilling activity, rigs vs frac spreads, or upstream operations. Returns US, Canada, and international rig counts, frac spread count, well permits issued in the last 30 days (with a by-state breakdown), and DUC (drilled-uncompleted) well totals. Requires a paid plan with energy intelligence access. |
opa_get_fuel_surcharge |
no_return_description |
Get carrier-published fuel surcharge percentages for LTL freight and parcel carriers. Use when the user asks about current or historical fuel surcharge rates for carriers like ODFL, Saia, Estes, XPO, ABF, TForce, Averitt, Southeastern Freight, UPS, FedEx, or DHL. Auto mode treats UPS/FedEx/DHL as parcel carriers and other carrier slugs as LTL. Parcel history requires a service_level such as ground, air, or international_air_export. Returns the current surcharge percentage and effective date for the requested carrier (or a list of available carriers if none is given); when history is true, returns up to per_page historical surcharge rows instead. |
opa_get_spread |
no_return_description |
Get refining and trading spreads: crack spreads (refining margin proxy), basis spreads (regional price differentials), and blending/transport margins. Use when the user asks about crack spreads, 3-2-1 crack, refining margins, basis differentials, or blend/transport margins. Returns the current spread value with its unit (e.g., $/barrel for crack spreads, $/unit differential for basis, or margin percentage), along with the associated commodities or locations being compared. Requires a paid plan with energy intelligence access. |
opa_list_price_alerts |
no_return_description |
List all PERSISTENT price alerts on the user's OilPriceAPI account. Use when the user asks what alerts they have set up, or to find an alert's id before deleting it. Returns a list of alert objects, each with its id, monitored commodity, threshold/condition, and current status. REQUIRES an API key (OILPRICEAPI_KEY) — alerts are account-scoped. No parameters needed. |
opa_get_market_brief |
no_return_description |
Get a multi-commodity market brief for several commodities in ONE call. Use when the user wants a market snapshot, morning brief, or an at-a-glance read across multiple commodities. Accepts natural language ('brent', 'us gas') or API codes. Returns, per commodity, the latest spot price, 24h change, 1-month forecast (for Brent/WTI/Natural Gas), and notable spreads; set `narrative: true` to also receive a plain-English summary plus market context (active supply disruptions, key economic indicators). REQUIRES an API key (OILPRICEAPI_KEY); counts as 1 request. Per-tier code limits apply (free: 3 codes). For a single price use opa_get_price; for ongoing recurring monitoring use opa_create_price_subscription. |
opa_list_subscriptions |
no_return_description |
List all PERSISTENT price subscriptions ('watches') on the user's OilPriceAPI account. Use when the user asks what they're monitoring, or to find a watch's id before deleting it. Each watch is a recurring, account-tied snapshot job. Returns a list of subscription objects, each with its id, monitored commodity codes, and snapshot schedule/frequency. REQUIRES an API key (OILPRICEAPI_KEY). No parameters needed. |
Selection evidence
Confusable tool pairs.
11 pairs where similar names or overlapping descriptions may send an agent toward the wrong tool.
| Tool A | Tool B | Confidence | Why they collide |
|---|---|---|---|
opa_get_futures |
opa_get_futures_curve |
high | Both handle 'futures'/'contract price' queries for the same commodity set; a request like 'what's the brent futures price' doesn't clearly indicate whether the user wants the single front-month quote or the full multi-month curve, and the tools differ only in that scope. |
opa_market_overview |
opa_get_market_brief |
high | Both are 'snapshot across multiple commodities' tools with overlapping language ('market snapshot', 'at-a-glance'). A generic ask like 'give me a market overview' or 'market brief' could route to either, though brief needs explicit codes/API key and adds forecasts. |
opa_get_futures |
opa_get_forecasts |
medium | Both answer 'where are oil prices headed' style questions — futures reflect market-implied forward prices while forecasts are EIA STEO predictions; a vague 'what will oil prices be next month' could plausibly trigger either. |
opa_list_price_alerts |
opa_list_subscriptions |
medium | Both list persistent, account-scoped, API-key-gated user configurations ('alerts' vs 'watches/subscriptions'); a task like 'what monitoring do I have set up' doesn't distinguish threshold alerts from recurring snapshot subscriptions. |
opa_list_subscriptions |
opa_get_subscription_events |
medium | Both concern the same 'subscription/watch' concept; a request like 'show my subscription activity' is ambiguous between listing the configured watches versus polling recorded events from them. |
opa_get_alert_triggers |
opa_get_subscription_events |
medium | Both are polling-style 'what happened recently' tools gated on an API key; 'any updates on my alerts/watches' could be misrouted since one reports alert firings and the other reports subscription snapshot deltas. |
opa_get_opec_production |
opa_get_well_production |
medium | Both are literally 'production' data tools; a vague 'get oil production data' doesn't indicate whether the user wants country-level OPEC output or US well-level production volumes. |
opa_get_well_permits |
opa_get_well_production |
medium | Both are well-focused, paid, US oil & gas tools with similar parameter shapes (state filters); a request like 'well data for Texas' is ambiguous between permitting activity and production volumes. |
opa_get_rig_counts |
opa_get_well_permits |
medium | Both descriptions explicitly mention 'drilling activity' and 'permitting activity'; a query like 'latest drilling activity in the US' could plausibly be served by either rig counts or new well permits. |
opa_get_diesel_by_state |
opa_get_fuel_surcharge |
low | Both concern diesel/fuel cost data, so a logistics-flavored question like 'current diesel fuel costs for shipping' could be misdirected toward carrier fuel surcharges instead of state retail diesel prices, despite serving different domains. |
opa_get_rig_counts |
opa_get_well_production |
low | Both are generic 'US oil and gas data' tools with heavy shared terminology; an unspecific 'oil and gas activity data' request could be misrouted between rig counts and production volumes. |
Compare the field