OilPriceAPI

Official

by OilpriceAPI

Overview Schema Related Servers Score Discussions(1)

JavaScript

Remote

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v3.2.0
Disambiguation5/5
Each tool has a clearly distinct purpose. Even tools like opa_get_price, opa_compare_prices, opa_market_overview, and opa_get_market_brief are well-differentiated by descriptions, with unique use cases (single price, comparison, broad overview, brief with narrative). No overlap causes ambiguity.
Naming Consistency5/5
All tools follow a consistent pattern: 'opa_' prefix followed by a verb_noun combination (e.g., compare_prices, create_price_alert, get_diesel_by_state). Naming conventions are uniform throughout, with no mixing of styles.
Tool Count4/5
26 tools is on the higher end, but the domain (energy commodities) requires many distinct data types (spot, futures, history, forecasts, drilling, storage, etc.). Each tool earns its place, though the count could be slightly reduced if some overlap is merged.
Completeness5/5
The tool set comprehensively covers the energy commodity domain: spot prices, comparisons, historical data, futures curves, forecasts, market briefs, alerts, subscriptions, drilling activity, rig counts, well permits, OPEC production, inventories, storage, and marine fuels. No obvious gaps are present for the stated purpose.
Average 4.5/5 across 26 of 26 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 44 commits in the last 12 weeks
- Last stable release on August 11, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the bar is lower. The description adds valuable context: it requires the Reservoir Mastery premium tier and states that it 'Returns current inventory levels with changes,' which goes beyond what the annotations provide.
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?
The description is three sentences with no wasted words. It front-loads the main purpose, then adds usage triggers, return behavior, and access requirement, all efficiently.
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?
For a simple one-parameter read-only tool, the description adequately covers purpose, when to use, return summary, and access requirements. It lacks a detailed return structure, but no output schema exists; still, the sibling overlap suggests more differentiation would improve completeness.
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?
The schema description for the single 'facility' parameter is complete, covering enum values, default, and descriptions. The tool description repeats similar facility information without adding new semantics, so baseline 3 is appropriate.
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?
The description clearly states the tool retrieves oil storage and inventory levels for Cushing and/or the SPR, using a specific verb and resource. However, it does not distinguish itself from the similarly named sibling tool 'opa_get_oil_inventories', which likely serves a similar purpose.
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?
The description provides explicit usage context: 'Use when the user asks about oil inventories, storage levels, Cushing stocks, or the SPR.' This gives clear conditions to invoke the tool, though it does not mention when not to use it or suggest alternatives, especially given the overlapping sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and openWorld annotations, the description reveals that responses include every non-available state-health record and that rankings may be incomplete. This adds meaningful behavioral context about data quality.
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?
Two dense sentences cover main result content and critical data-limitation warnings without redundancy or fluff.
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?
For a single-parameter aggregate tool with no output schema, the description explains main output categories and caveats. It lacks deeper structural detail but is sufficient for basic invocation.
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?
The sole parameter 'days' is fully documented in the schema with 100% coverage, and the description does not add extra semantic detail beyond the schema's description.
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?
The description clearly states the tool returns recent US well-permit activity with enumerated components (counts by state, top operators, formations, permit types, weekly trend). This distinguishes it from siblings like opa_get_well_permits or opa_get_well_production.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for aggregate well-activity overviews but does not explicitly state when to prefer it over alternatives or provide exclusions. It warns about data completeness but lacks explicit alternative-tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, setting a read-only, non-destructive baseline. The description adds meaningful context about the data source (EIA STEO and other sources) and the premium tier access requirement, but it does not detail return format, potential errors, or rate limits. Given annotations cover the safety profile, a 3 is appropriate.
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?
The description is three sentences long, front-loaded with the core action, then usage guidance, then return/access details. Every sentence contributes value without redundancy or fluff, making it highly efficient for an AI agent.
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?
For a zero-parameter, read-only tool with no output schema, the description covers the essential elements: source, trigger, return summary, and access requirement. It is adequate for the tool's simplicity, though it could be slightly more specific about which commodities or the forecast horizon. This does not detract significantly from completeness.
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?
The tool has zero parameters, and the input schema is empty. Schema description coverage is effectively 100% (vacuous). The description does not need to explain parameter meanings since there are none, and the baseline for zero parameters is 4 per the rubric.
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?
The description clearly states the tool retrieves energy price forecasts from EIA STEO and other sources, with a specific verb ('Get') and a resource ('price forecasts'). It distinguishes itself from sibling tools by focusing on forecasts and explicitly mentions the use case of price predictions/outlooks, which is distinct from current prices (e.g., opa_get_price) or futures.
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?
The description provides explicit when-to-use guidance: 'Use when the user asks about price predictions, outlooks, or where oil/gas prices are heading.' It also notes the premium tier requirement as a prerequisite. However, it does not explicitly contrast with alternatives or give when-not-to-use guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds context beyond annotations by mentioning the premium tier requirement and the available return views ('latest weekly figures; optionally a summary view or a breakdown by petroleum product'). No contradictions with annotations.
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?
The description is two sentences, front-loaded with the core purpose. The second sentence efficiently adds usage scenarios and access requirements. No wasteful words.
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?
Given the simple one-parameter schema and no output schema, the description covers the essential context: what the tool returns, when to use it, and access requirements. It could provide more detail about the exact structure of returned data, but the parameter descriptions already explain view-specific outputs, making it reasonably complete.
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?
There is one parameter (view) with 100% schema description coverage; the schema already explains each enum option. The description merely restates the view options without adding extra meaning, so the baseline score of 3 is appropriate.
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?
The description clearly states the tool's purpose: 'Get the latest EIA weekly petroleum inventory (stocks) data.' It uses a specific verb and resource and lists trigger phrases like 'oil inventories, crude stocks, weekly EIA stocks, inventory builds/draws.' While it doesn't explicitly contrast with sibling tools like opa_get_storage, the purpose is unambiguous and sufficiently differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use when the user asks about oil inventories, crude stocks, weekly EIA stocks, inventory builds/draws, or product-level inventory levels,' providing clear when-to-use guidance. It also discloses the prerequisite 'Requires the Reservoir Mastery premium tier,' which is valuable context for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses several behavioral traits beyond the readOnlyHint and openWorldHint annotations: it checks a state-health gate and fails closed for unavailable/attention states, and it always returns freshness, date coverage, source provenance, and staleness/degradation caveats. It also explicitly notes that operator and county searches are separate. This is rich behavioral transparency.
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?
The description is three sentences and each sentence serves a distinct purpose: purpose/scope, behavioral safety/metadata guarantees, and usage constraint. It is front-loaded with the core purpose and avoids any filler, making it highly concise and well-structured.
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?
With no output schema, the description compensates by mentioning that results include freshness, date coverage, provenance, and caveats. It also covers the state-health gate and separate-search constraint. However, it omits pagination details (page/per_page parameters), which is relevant for a search tool. Still, it is sufficiently complete for tool selection.
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 71%, so the schema already documents most parameters. The description adds the 'county or operator' and 'optional permit-date range' context and reinforces that they cannot be combined, but it does not provide substantial new meaning beyond the schema's own parameter descriptions. It meets the baseline but does not elevate it.
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?
The description opens with 'Search well permits in one US state by county or operator and optional permit-date range,' which specifies a clear verb (search), resource (well permits), scope (one US state), and filter dimensions. It distinguishes from siblings like opa_get_well_permits and opa_lookup_well by emphasizing the search-by-county/operator behavior and the single-state constraint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context by stating that operator and county filters cannot be combined and require separate searches. However, it does not explicitly say when to choose this tool over alternatives like opa_get_well_permits or opa_lookup_well, nor does it mention any exclusions. The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond annotations: it requires an API key (OILPRICEAPI_KEY) and explains that the API returns per-alert counters (trigger_count, last_triggered_at) rather than an event feed. This helps the AI agent understand the data model. Annotations already indicate readOnlyHint=true, so the description complements them well.
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?
The description is three sentences: the first states purpose, the second gives usage guidance, and the third provides critical behavioral context. It is concise, front-loaded, and every sentence adds value.
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?
Given the tool has only one optional parameter, no output schema, and annotations are provided, the description covers all necessary aspects: what it does, when to use it, prerequisites (API key), and the nature of the returned data (counters, not events). This is sufficient for an AI agent to invoke it correctly.
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 coverage is 100%, so baseline is 3. The description does not add extra meaning for the 'since' parameter beyond what the schema already provides (ISO 8601 format, filters by last_triggered_at).
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?
The description clearly states the tool retrieves recent trigger activity for the user's price alerts, specifying what data is returned (which alerts fired, counts, last triggered time). This distinguishes it from sibling tool 'opa_list_price_alerts' which likely lists all alerts without trigger history.
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?
The description explicitly says 'Use when the user asks whether any alerts have gone off or about recent alert activity.' This gives clear context for when to invoke the tool, though it does not mention when not to use it or explicitly list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful context beyond the readOnlyHint annotation: it discloses that per-commodity reports require a paid plan and describes the output structure (overall grade/score, dimension scores, or catalogue-wide summary). This goes beyond simply restating the annotation and gives the agent a clearer behavioral model.
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?
The description is three sentences long, front-loaded with the core verb, and every sentence conveys necessary information: what the tool does, the two modes, when to use it, and a cost caveat. No fluff.
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?
For a simple read-only reporting tool with one optional parameter and no output schema, the description covers the operation modes, what the response contains, and access restrictions. It is complete enough for an agent to select and invoke correctly without further guessing.
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 coverage is 100%, and the schema already fully describes the 'commodity' parameter with examples and behavior when omitted. The description reinforces this but doesn't add substantial new semantics, so the baseline of 3 is appropriate.
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?
The description clearly states 'Get OilPriceAPI's own data-quality grades,' a specific verb+resource that distinguishes this tool from price/history siblings. It also explains the two modes of operation (with or without a commodity code), making its purpose unambiguous.
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?
It explicitly says 'Use when the user asks how reliable/complete a series is, or which series carry the highest quality grades.' It also notes the paid-plan requirement for per-commodity reports, which is an important usage constraint. However, it does not name specific alternative tools or when-not-to-use exclusions, though the distinct purpose implies this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true and openWorldHint=true, and the description adds context beyond this by specifying the data source ('AAA-sourced') and coverage ('all 50 states plus DC'), which helps the agent understand reliability and scope. It does not describe potential failure modes, but given the annotations cover the safety profile, this is sufficient.
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?
The description is four sentences, each serving a distinct purpose: what it does, when to use, input format, and output source/coverage. There is no redundant or filler content.
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?
For a simple read-only tool with one fully described parameter and no output schema, the description covers the essential context: function, trigger phrases, input format, output source, and geographic coverage. No significant gaps remain.
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?
The schema already documents the single parameter 'state' with examples, and the description repeats this format ('Accepts state names or 2-letter codes') without adding new semantics beyond the schema's coverage. Since schema coverage is 100%, the description adds marginal value only.
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?
The description clearly states 'Get the current average retail diesel price for a US state,' using a specific verb and resource. It distinguishes itself from siblings like opa_get_price or opa_get_futures by explicitly scoping to diesel and state-level.
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?
It provides explicit usage triggers: 'Use when the user asks about diesel prices in a specific state, diesel fuel costs by state, or state-level fuel prices.' This gives clear when-to-use context, though it does not name exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds valuable context: front-month only, supported commodity aliases, and a Professional plan requirement ($99/mo). This goes beyond the annotations' basic safety profile.
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?
The description is five sentences, front-loaded with the main purpose. Each sentence serves a distinct function: definition, use context, commodity mapping, alternative tool, and access requirement. It is slightly longer than minimal but still concise.
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?
The tool has no output schema, but the description implies the return type (price) and covers supported contracts, the alternative for full curves, and access restrictions. Given the single optional parameter and good annotations, this is sufficient.
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?
The schema fully documents the 'contract' parameter with an enum and detailed descriptions (100% coverage). The tool description repeats the alias mapping but does not add new syntax or format details, so it stays at the baseline.
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?
The description begins with a specific verb-plus-resource statement: 'Get the latest front-month futures contract price for energy commodities.' It clearly distinguishes itself from the sibling tool opa_get_futures_curve by limiting to front-month, avoiding ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use when the user asks about futures, forward prices, or contract prices' and provides an exclusion: 'For the full forward curve across all contract months, use opa_get_futures_curve instead.' This gives clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the agent knows it is safe. The description adds valuable behavioral context: BETA coverage, limited well-level histories, availability of multiple views, and the requirement for an add-on/plan. These details go beyond the annotations and help the agent set expectations, though no rate limits or error behavior are disclosed. No contradiction exists.
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?
The description is moderately long (around 100 words) but every sentence serves a purpose: purpose, coverage caveat, view list, usage scenarios, and access requirements. The use of parentheses and a compact enumeration keeps it structured. It is thoroughly front-loaded with the main verb and resource in the first 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?
For a multi-view tool with no output schema, the description covers the essential ground: data coverage, view semantics, required parameters per view, and plan prerequisites. It doesn't spell out response formats, but the view summaries provide enough for an agent to reason about expected outputs. Minor gaps include lack of error/edge-case behavior, but overall it's complete enough for safe invocation.
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?
The input schema has 100% coverage and already describes each parameter, including the enum values and dependencies. The description reinforces these by explaining what each view returns (e.g., 'monthly history for one state' for the state view, 'highest-output wells' for top_producers). While not adding new parameter syntax, it adds semantic richness beyond the schema, making the baseline 3 become a 4.
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?
The description clearly states the tool's function: 'Get US oil & gas well production data' with explicit scope and a BETA coverage caveat. It enumerates seven distinct views, distinguishing it from sibling tools like opa_get_well_permits or opa_lookup_well. The purpose is specific, verifiable, and not a tautology.
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?
The description provides explicit when-to-use guidance: 'Use when the user asks about oil/gas production volumes by state or well, top producing wells, or drill-to-production cycle times.' It also warns about incomplete US well-level production, implying when it's not suitable, but does not explicitly name alternative tools or provide a clear when-not-to-use list. This is a strong 4, missing only explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is clear. The description adds useful context: returns a 'table of contract months with settlement prices, plus market structure analysis' and reveals the plan requirement. However, it doesn't detail pagination or response size limits, but for a read-only data retrieval tool with good annotations, this is sufficient.
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, all informative: purpose, usage context, supported instruments, and return contents. No fluff, no repetition of schema enum values (the description uses readable commodity names while the schema has codes). Front-loaded with the main purpose.
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?
Given the tool has one optional parameter, a complete enum, and no output schema, the description covers the key aspects: what it returns, when to use it, supported contracts, and a plan restriction. The only minor gap is not mentioning the output format details beyond 'table', but with simple inputs and no nested schema, this is adequately complete.
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 100%, and the enum descriptions are thorough, mapping each code to its commodity. The description adds value by listing supported commodities in prose, but the schema already provides full parameter meaning. Baseline 3 is appropriate because the schema does the heavy lifting.
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?
The description clearly states the tool returns the full futures forward curve across all contract months, with a specific verb ('Get') and resource ('full futures forward curve'). It distinguishes from siblings like opa_get_futures by emphasizing 'forward curve, contango/backwardation, or term structure', which is a unique scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'when the user asks about the forward curve, contango/backwardation, or term structure'. Also lists supported commodities and contract codes, and notes the Professional plan requirement, which helps the agent decide if this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe read (readOnlyHint=true) and open world (openWorldHint=true). The description adds value by clarifying the result is 'fetched live from the API, grouped by category,' providing helpful behavioral context beyond annotations.
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?
The description is extremely concise: two sentences covering purpose, usage, and behavior. Every sentence adds value with no wasted words, and the key information is front-loaded.
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?
Given the lack of an output schema, the description adequately hints at the return format ('full catalog ... grouped by category'). The tool is simple, and no further details (like pagination) are necessary, making it nearly complete.
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?
With zero parameters and 100% schema description coverage, no parameter details are needed. The description adds 'No parameters needed' for clarity, meeting the baseline expectation for a param-free tool.
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?
The description clearly states the tool lists all available commodities for price queries, specifying concrete use cases like when the user asks for commodities, codes, or error handling. It naturally distinguishes from siblings that focus on prices, alerts, or other functionality.
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?
The description explicitly tells when to use the tool (for commodity availability queries, codes, error handling) and notes no parameters needed. It doesn't explicitly state when not to use or list alternatives, but the context is clear enough for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. Description adds value by highlighting that alerts are 'PERSISTENT' and 'account-scoped', informing the agent about state and scope. No contradictions.
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?
Two sentences, both essential: function and usage. No wasted words, front-loaded with core purpose.
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?
For a simple listing tool with no parameters and no output schema, description covers key aspects: what, when, prerequisites. Could include what the response contains, but not necessary given low complexity.
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 has zero parameters, baseline is 4. Description states 'No parameters needed', confirming simplicity. Adds no further parameter details as none exist.
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?
The description explicitly states 'List all PERSISTENT price alerts' using a specific verb and resource, distinguishing it from sibling tools like opa_create_price_alert and opa_delete_price_alert.
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?
Provides clear use cases: 'Use when the user asks what alerts they have set up, or to find an alert's id before deleting it.' Also mentions prerequisite 'REQUIRES an API key (OILPRICEAPI_KEY)'. No explicit alternatives, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint: true, openWorldHint: true) and adds context about grouping by category with 24h changes. No contradictions; extra behavior is non-critical.
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 concise sentences: purpose, usage guidance, and output description. Front-loaded with key information, no wasted words.
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?
Given the tool's simplicity (one optional parameter, no output schema), the description covers purpose, usage, and basic output structure. It omits details like response format limits, but annotations mitigate need for full specification.
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?
The input schema already describes the category parameter (enum values, default, filter purpose). The description merely restates 'Supports filtering by category' and lists categories in output context, adding minimal value beyond the schema.
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?
The description clearly states the tool's purpose: 'Get current prices for all tracked energy commodities in one call.' It specifies the resource (energy commodities) and action (get prices), and distinguishes from the sibling opa_get_price for single commodity queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use: 'when the user wants a broad market snapshot or asks about overall energy prices.' It also provides an alternative: 'For a single commodity, use opa_get_price instead.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint, so the read-only nature is already covered. The description adds valuable context about the required Scale plan and the specific data elements included, which helps the agent understand access constraints and tool scope beyond annotations.
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 with no wasted words: the first states what it returns, the second gives usage guidance, and the third notes the plan requirement. Information is front-loaded and each sentence adds value.
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?
The description is complete for a zero-parameter tool: it lists all key data points in the snapshot, gives usage context, and mentions access prerequisites. No output schema exists, but the description sufficiently conveys what the agent can expect.
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?
The tool has zero parameters, so the baseline is 4. The description adds no parameter-specific semantics but clearly explains the output content, which is helpful for selecting the tool.
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?
The description uses a specific verb ('Get') and resource ('drilling activity snapshot') with detailed contents (rig counts, frac spread, permits, DUCs). It clearly distinguishes from sibling tools that focus on individual data points like rig counts or permits.
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?
Explicitly states when to use: 'Use when the user asks about drilling activity, rigs vs frac spreads, or upstream operations.' It does not mention when-not to use or name alternative tools, but the context is clear and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds behavioral context beyond annotations by explaining how auto mode classifies carriers (UPS/FedEx/DHL as parcel, others as LTL) and that parcel history requires a service_level. No contradictions.
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?
The description is three sentences long, front-loaded with the primary purpose, followed by usage context, then key constraints. Every sentence carries useful information without redundancy or filler.
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?
Given the tool's moderate complexity (5 parameters, no output schema) and the presence of strong annotations, the description covers the main use cases, the auto mode logic, and special requirements for parcel history. The return format is implied by the purpose ('percentages'), so this is sufficient for an agent to select and invoke the tool correctly.
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 the baseline is 3. The description adds meaning beyond the schema by explaining the auto-mode mapping and clarifying the service_level requirement for parcel history, which helps the agent understand how parameters interact.
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?
The description uses a specific verb ('Get') with a specific resource ('carrier-published fuel surcharge percentages') and scope ('LTL freight and parcel carriers'). It clearly distinguishes from all sibling tools, none of which cover fuel surcharges.
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?
The description explicitly states when to use the tool ('Use when the user asks about current or historical fuel surcharge rates') and gives important guidance on auto mode and parcel history requirements. It doesn't name alternatives, but no direct alternative exists among siblings, so the guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds valuable context: it returns a table format, requires a Professional plan ($99/mo) or higher, and implies live/current pricing. No contradictions with annotations.
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: purpose, usage triggers, filter options, return format, and access requirement. Every sentence earns its place with no redundancy or filler.
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?
For a low-complexity read-only tool with two optional params and no output schema, the description is complete. It covers purpose, filters, return type, and a critical access prerequisite (plan level), which is sufficient for selection and invocation.
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 coverage is 100% with both parameters already described. The description adds example port values and clarifies that filters can be used individually or together, but this is largely redundant with the schema, so it does not meaningfully extend the semantics beyond the baseline 3.
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?
The description clearly states the tool fetches latest marine fuel (bunker) prices for major shipping ports, with specific fuel types (VLSFO, MGO, IFO380) and port examples. This distinguishes it from siblings like opa_get_diesel_by_state or opa_get_fuel_surcharge.
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?
Explicitly says 'Use when the user asks about bunker fuel, marine fuel, VLSFO, MGO, IFO380, or shipping fuel costs,' giving clear trigger context. However, it does not explicitly name alternatives or state when not to use this tool, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to repeat safety traits. It adds value by specifying the return format ('country-level production figures') and the access constraint ('Requires Reservoir Mastery premium tier'). This provides behavioral context beyond the structured annotations.
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?
The description is four sentences, each serving a clear purpose: purpose, usage trigger, return format, and access requirement. It is front-loaded with the main verb and object, and there is no redundant or filler content.
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 no output schema, the description correctly explains the return value as 'country-level production figures'. It also covers usage context and premium-tier restriction. For a parameter-less, read-only data retrieval tool, this is complete and self-sufficient.
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?
The tool has zero parameters, so the baseline is 4 per the rubric. The description refers to 'latest' and 'country-level' output, but these describe the data, not parameters. No parameter documentation is needed.
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?
The description starts with 'Get the latest OPEC oil production data', which is a specific verb+resource statement. It further clarifies the scope by mentioning 'country-level production figures'. While it does not explicitly name a sibling tool, the function is clearly distinct from all listed siblings, which focus on prices, inventories, and drilling.
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?
The description gives explicit when-to-use guidance: 'Use when the user asks about OPEC output, production quotas, supply cuts, or OPEC+ compliance.' It also notes the premium tier requirement. However, it does not state when not to use the tool or name an alternative, so it stops short of a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the bar for additional disclosure is lower. The description adds valuable context: 'Live pricing from the API — no key required' indicates real-time data and authentication requirements. It does not mention rate limits or error behavior, but the added auth note justifies a solid score.
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?
The description is three sentences: the first states the core function, the second provides usage context, and the third adds practical notes. Every sentence serves a purpose, with no redundant or unclear phrasing. It is front-loaded with the main purpose.
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?
For a zero-parameter, read-only tool with rich annotations and no output schema, the description fully covers what the tool does, when to use it, and auth requirements. It is complete enough for an agent to select and invoke the tool correctly without further clarification.
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?
The tool has zero parameters, and the input schema is empty. The description therefore has no parameter details to add. Baseline for zero-param tools is 4, and the description does not introduce confusion the schema already documents everything.
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?
The description uses a specific verb ('Get'), names the resource ('OilPriceAPI's current subscription plans'), and enumerates the content (monthly/yearly price, request limits, included features). This clearly distinguishes it from sibling tools like opa_get_price or opa_list_subscriptions, which focus on data or account status.
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?
Provides explicit when-to-use scenarios: 'when the user asks what an upgrade costs, which plan unlocks a gated tool... or how the tiers compare.' It also notes no key is required. However, it does not mention when not to use it or name alternative tools, so it falls short of full explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world hints. The description adds valuable context: the premium tier requirement and the Baker Hughes source. It could mention data freshness or update frequency, but with annotations covering safety, this is sufficient.
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, each with a distinct role: purpose, usage, and return details/constraints. No fluff or redundancy; every sentence earns its place.
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?
For a simple tool with no parameters and no output schema, the description covers purpose, usage, returned data, and access requirements. Annotations handle safety, so the description is complete for the tool's complexity.
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?
No parameters exist, so the baseline is 4. The description explicitly states 'No parameters needed,' which clarifies the tool's invocation and removes any uncertainty.
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?
The description clearly states the tool gets the latest US oil and gas rig count data from Baker Hughes, and explicitly lists the returned fields (oil rigs, gas rigs, total, change). This distinguishes it from siblings like opa_get_drilling by focusing on rig counts and specific data source.
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?
Provides explicit usage context: 'Use when the user asks about drilling activity, rig counts, or oil field operations.' However, it does not mention when not to use or name alternative tools, so it falls short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns the latest permits and supports filtering/aggregation by state or operator. It also reveals an access requirement (add-on/enterprise plan) not covered by annotations. With readOnlyHint already present, the description adds useful functional context, though it doesn't detail response format or pagination.
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 with front-loaded purpose, clear use-case guidance, and a concise summary of return behavior and requirements. Every sentence contributes useful information, and the structure is easy to scan.
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?
For a simple read-only tool with three optional parameters and no output schema, the description covers purpose, usage context, return behavior, and prerequisites. It is complete enough for an agent to select and invoke correctly, especially with the alternative tool reference in the parameter description.
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?
The input schema has 100% description coverage for all parameters, so the baseline is 3. The main description only summarizes parameter behavior ('optionally filtered/aggregated by state or by operator') without adding new detail. The operator parameter description does add guidance about an alternative tool, but that is within the schema, not the tool description, and the main description adds minimal semantic value.
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?
The description clearly states it retrieves US oil & gas well drilling permit data, with a specific verb and resource. It also specifies the scope ('latest') and available filters/aggregations, effectively distinguishing it from other well-related tools like production or activity. The sibling search tool is differentiated via the operator parameter description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides use cases ('when the user asks about well permits, new drilling permits, permitting activity, or upstream permit trends') and a prerequisite (well-permits add-on or enterprise plan). The operator parameter description recommends 'opa_search_well_permits' for richer filters, offering clear when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: subscriptions are 'PERSISTENT', 'recurring', 'account-tied snapshot jobs'. No contradiction with readOnlyHint and openWorldHint.
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 concise sentences, front-loaded with main action. No extraneous words.
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?
For a zero-parameter list tool with no output schema, description covers purpose, usage, and prerequisites adequately.
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?
No parameters; schema coverage 100%. Description confirms 'No parameters needed.' Baseline 4 is appropriate.
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?
Clearly indicates verb 'List' and resource 'PERSISTENT price subscriptions'. Distinguishes from sibling tools like opa_list_price_alerts and opa_list_commodities.
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?
States when to use (when user asks what they're monitoring or to find watch id) and mentions API key requirement. Lacks explicit when-not-to-use, but acceptable for a simple list tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and openWorld annotations, the description discloses that it uses promoted lifecycle summaries, returns specific fields, includes monthly history for 14-digit API numbers when available, and fails closed for unpromoted or ambiguous records. This adds substantial behavioral context without contradicting annotations.
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?
The description is three sentences, front-loaded with the core action, and every sentence contributes useful information without redundancy or filler.
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?
There is no output schema, so the description compensates by listing return fields (operator, county, lifecycle dates, cumulative production, evidence, monthly history) and explaining conditional behavior and fail-closed handling. It is complete for this lookup tool.
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?
Both parameters are fully described in the schema (100% coverage). The description adds a minor nuance about state disambiguation across source contexts, but does not materially exceed the schema's own explanations.
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?
The description uses the specific verb 'Look up', identifies the resource as a well, and specifies the API number formats. It distinguishes from sibling tools by stating it returns promoted lifecycle summaries and conditional monthly production history, making its scope clear.
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?
The description clarifies when to use the tool (to look up a well by API number) and provides context about optional state disambiguation and fail-closed behavior. It does not explicitly name alternative tools or state when not to use it, but the context is sufficiently clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safe, read-only nature is covered. The description adds valuable behavioral context by specifying the Professional plan ($99/mo) requirement and clarifying the semantics of 'basis' as regional price differentials, going beyond the schema.
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 short sentences efficiently cover purpose, usage triggers, and plan restriction. Each sentence adds distinct value with no redundancy or filler.
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?
For a one-parameter tool with full schema coverage and safe annotations, the description is largely complete. It lacks explicit return format details, but this is not critical for a simple list-like lookup, and the openWorldHint annotation covers potential data variability.
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?
The schema already documents the 'type' parameter with enum and descriptions, so the baseline is 3. The description enhances meaning by providing real-world equivalents like '3-2-1 crack' and refining margin proxy, which helps an agent map user intent to the correct enum value.
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?
The description clearly states the tool's function with a specific verb and resource: 'Get refining and trading spreads'. It enumerates the three spread types (crack, basis, margin) and distinguishes itself from sibling price tools by focusing on spreads rather than absolute prices.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit usage guidance is provided: 'Use when the user asks about crack spreads, 3-2-1 crack, refining margins, basis differentials, or blend/transport margins.' This directly tells the agent when to select this tool over alternatives, and the plan requirement adds a clear prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, so the description isn't burdened with safety. It adds valuable context beyond annotations: what data is returned (plan tier, usage, remaining quota, reset date) and that it 'Works on every plan including free.' This enriches the agent's understanding of the tool's behavior and error-handling utility.
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?
The description is two sentences, front-loaded with the primary function in the first sentence and usage guidance in the second. Every sentence provides distinct value: one defines the tool's purpose, the other specifies when to invoke it. No redundant or extraneous content.
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?
For a simple no-parameter tool with strong annotations, the description is complete. It identifies the main return fields, provides concrete use cases, and notes universal availability. The lack of an output schema is adequately compensated by the detailed enumeration of what the tool returns.
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?
The tool has zero parameters, so the baseline is 4 per the rubric. The description adds meaning about the return content but doesn't need to explain parameters since there are none. Schema coverage is 100%, and the description complements the empty schema by clarifying the tool's output focus.
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?
The description explicitly states a specific verb and resource: 'Get the current API account's plan tier, request usage, remaining quota, and reset date.' This clearly distinguishes the tool from the data-retrieval siblings (e.g., opa_get_price, opa_get_diesel_by_state), which focus on market data rather than account status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios: 'Use before calling gated tools, when the user asks about their plan/limits/usage, or after any 402/403/429 to explain what the current plan covers.' This gives clear when-to-use guidance and a rationale, making the tool's role in workflow obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses specific return fields (high, low, average, change, data point count), explains period durations (day=24h, week=7d, etc.), and gives a detailed account of as_of vintage semantics (later rows absent, revisions rolled back, no lookahead bias). It also adds the critical paid-plan restriction for historical data, which is substantial behavioral and operational context.
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?
The description is compact but information-dense: each sentence earns its place, covering purpose, trigger, outputs, periods, as_of behavior, and pricing. It is front-loaded with the core action and avoids repetition or filler.
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?
Given no output schema, the description still lists the return fields and key behavioral nuances, including the vintage feature and plan limitation. For a 3-parameter tool with full schema coverage, this is complete and well-positioned among 32 sibling tools.
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 the baseline is 3. The description enhances this by mapping periods to human-readable durations and reinforcing as_of semantics with backtesting context that goes beyond the schema's description. It doesn't add new syntax details but adds interpretive value, warranting a 4.
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?
The description uses a specific verb and resource: 'Get historical price data for a commodity over a time period.' It clearly differentiates from siblings like opa_get_price by emphasizing 'historical', 'price trends', and 'performed over time', making the tool's niche obvious.
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?
It explicitly states when to use: 'Use when the user asks about price trends, historical prices, or how a commodity has performed over time.' It also notes the paid-plan requirement as a constraint. However, it does not name an alternative tool for current prices (e.g., opa_get_price), so it lacks an explicit 'when not to use' statement, though the context strongly implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the two modes (with/without hub), return contents (basis and history), and adds a critical caveat about varying hub history depth. It also discloses the paid-plan requirement. These details go well beyond the readOnlyHint and openWorldHint annotations, without contradicting them.
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?
The description is efficient and well-structured: it opens with the core purpose, follows with usage guidance and hub enumeration, and then explains behavior and prerequisites. No sentence is wasted, and all necessary information is present.
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?
For a read-only, optional-parameter tool with no output schema, the description fully covers behavior in both call variants, the data depth caveat, and access requirements. It is complete for an agent to select and invoke the tool correctly without additional context.
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?
Although the schema descriptions are complete (100% coverage), the description adds value by clarifying the 'past' parameter's format with examples (30d, 6m, 1y) and reiterating that it only applies when a hub is provided. This enriches the parameter semantics beyond the schema alone.
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?
The description states a specific verb+resource ('Get US physical natural gas hub prices as basis to Henry Hub') and explicitly lists the hub identifiers, clearly distinguishing this tool from siblings like opa_get_price or opa_get_futures. The scope (natural gas hubs) is precise and unambiguous.
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?
It explicitly says 'Use when the user asks about regional gas prices or hub basis' and names the relevant hubs, giving clear context. However, it does not mention when not to use this tool or name alternative tools for non-hub commodities, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and open-world. Description adds that it returns price, currency, change fields, and timestamp, and that values are source-timestamped. Does not contradict annotations.
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 concise, front-loaded sentences cover purpose, usage, input, output, and sibling distinctions with zero wasted words.
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?
For a simple read-only tool with one parameter and no output schema, the description fully covers what the tool does, when to use it, input format, output contents, and when not to use it via sibling references.
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% and includes description for 'commodity'. Description additionally provides examples and clarifies acceptance of natural language or codes, adding value beyond schema.
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?
Description clearly states verb ('Get'), resource ('latest available, source-timestamped value'), and domain ('energy commodity'). Distinguishes from siblings by naming opa_market_overview and opa_get_history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use when the user asks about a single commodity's latest price.' Provides input format guidance and gives alternative tools for multiple commodities or trends.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, indicating safe, read-only behavior. The description adds context about what information is covered (product contract aspects) and that no authentication is needed, adding value beyond annotations.
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?
The description is only two sentences, front-loaded with the core purpose, and every detail earns its place. No unnecessary words.
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?
Given no parameters and no output schema, the description fully conveys what the tool returns (a product contract with specific elements) and when to use it. It is complete for its scope.
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?
There are zero parameters, so schema coverage is 100% by default. The description does not need to explain parameters, and baseline for no parameters is 4.
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?
The description explicitly states it gets the 'reviewed, versioned OilPriceAPI product contract' and lists specific aspects like product scope, pricing URL, authentication, etc. It distinguishes from sibling tools by advising to use it for questions about OilPriceAPI itself instead of model memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use the tool: 'for questions about OilPriceAPI itself' and to use it 'instead of model memory or package prose.' It also notes that no API key or paid-data entitlement is required, setting proper expectations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond annotations. It explains the polling nature ('Events are POLLED, not pushed'), the data content ('Each event carries a price snapshot plus per-code deltas'), cursor lifecycle ('The returned `cursor` is what you pass as `since` next time'), and authentication ('REQUIRES an API key') and quota info ('does NOT count against the monthly request quota').
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?
The description is concise yet comprehensive, using only 5-6 sentences to convey purpose, usage, behavior, parameter details, and constraints. Every sentence adds value, and the information is front-loaded.
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?
Given the single optional parameter (with schema coverage) and no output schema, the description covers all necessary aspects: what the tool does, how to use the cursor, data content, polling behavior, authentication, and quota implications. No gaps remain.
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 description coverage is 100% with a clear description of the `since` parameter. The description reinforces and expands on it: 'pass the `since` cursor (the seq number) returned by the previous call to get only newer events. Omit (or 0) to get the earliest available events.' This adds practical usage guidance.
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?
The description clearly states the tool's purpose: 'Poll for new subscription events — the recurring snapshots recorded by the user's watches.' It uses a specific verb ('poll') and resource ('subscription events'), distinguishing it from sibling tools like opa_get_price or opa_get_history.
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?
The description explains when to use the tool: 'Use this to catch up on what changed since the last poll' and how: 'pass the `since` cursor.' It also notes that events are polled, not pushed, implying periodic calls. However, it does not explicitly mention scenarios where the tool should not be used or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond readOnlyHint and openWorldHint annotations, the description discloses that it returns each commodity's price with 24h changes and the spread if comparing two same-currency commodities, adding valuable behavioral detail.
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?
The description is two sentences (49 words), concise, front-loaded with the main purpose, and every sentence adds value.
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?
For a tool with one parameter and no output schema, the description adequately covers purpose, usage, and return structure. Minor omission: does not mention that schema enforces maxItems=5, but schema already handles that.
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?
With 100% schema coverage, the parameter 'commodities' is well-described in the schema. The description adds the note about accepting natural language, which is not in the schema, providing additional semantic clarity.
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?
The description clearly states the tool compares current prices of 2-5 commodities side by side, distinguishing it from single-commodity tools like opa_get_price and spread tools like opa_get_spread.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when the user asks to compare commodities, gives examples ('Brent vs WTI', 'US gas vs EU gas'), and notes it accepts natural language or codes, providing clear context for when to invoke.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint and openWorldHint, but the description adds substantial behavioral context: it reveals the API key requirement (OILPRICEAPI_KEY), that the call counts as 1 request, and that per-tier code limits apply (free: 3 codes). It also discloses the narrative option's added content, going well beyond the annotations without contradicting them.
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?
The description is four sentences, each earning its place: core purpose, use cases, param behavior, and auth/limits/alternatives. It is front-loaded with the most important information and contains no fluff or repetition of structured fields.
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?
Despite lacking an output schema, the description clearly enumerates what the tool returns (spot prices, 24h changes, forecasts, spreads, optional narrative context) and covers resource constraints (API key, request count, tier limits). For a two-parameter read-only tool, this is comprehensively sufficient.
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% and both parameters are described, but the description adds meaningful nuance: it explicitly states that codes accept natural language ('brent', 'us gas') or API codes, and clarifies that narrative adds a 'plain-English summary plus market context.' This exceeds the schema's basic parameter documentation, earning a score above the baseline.
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?
The description opens with a specific verb and resource: 'Get a multi-commodity market brief' with concrete contents (spot prices, 24h changes, 1-month forecasts, spreads). It clearly distinguishes this from sibling tools by emphasizing 'several commodities in ONE call' and explicitly contrasts with single-price and subscription tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is explicitly stated: 'Use when the user wants a market snapshot, morning brief, or an at-a-glance read across multiple commodities.' It also names two alternatives with clear disambiguation: 'For a single price use opa_get_price; for ongoing recurring monitoring use opa_create_price_subscription.' This is exemplary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-server MCP server](https://glama.ai/mcp/servers/OilpriceAPI/mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/OilpriceAPI/mcp-server)

Score Badge

Copy to your README.md:

[![mcp-server MCP server](https://glama.ai/mcp/servers/OilpriceAPI/mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/OilpriceAPI/mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/OilpriceAPI/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server