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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already cover read-only and open-world behavior, so the description adds value by disclosing access variability: the summary works on any valid key while per-commodity details vary, and an eligible account entitlement is required. It also notes that the API response is authoritative, which helps set expectations.

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

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

The description is front-loaded with the core purpose and uses a few compact sentences to cover modes, usage signals, and access caveats. Every sentence contributes useful information without repetition or fluff.

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

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

With no output schema, the description adequately describes both return shapes: the per-series quality report with dimension scores and the catalog summary with grade distribution. It also covers eligibility, mode-dependent access, and points to opa_get_plans for entitlements, leaving no critical gap for invocation.

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

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

Schema description coverage is 100% and the only parameter is documented in the schema. The description restates and slightly enriches the parameter's behavior by giving examples and explaining the two modes, but it does not need to carry additional semantic weight.

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

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

The description opens with a specific verb and resource: 'Get OilPriceAPI's own data-quality grades.' It clearly distinguishes the two operation modes (with or without a commodity code) and explains what each returns, making it unique among the sibling data-retrieval tools.

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

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

It explicitly states when to use the tool: 'Use when the user asks how reliable/complete a series is, or which series carry the highest quality grades.' It also routes access/pricing questions to opa_get_plans, giving the agent a clear decision path versus an alternative tool.

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

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.

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.

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.

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.

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.

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.

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

Beyond readOnlyHint/openWorldHint annotations, the description discloses an account-entitlement requirement and states that the API response is authoritative. This adds useful behavioral context without contradicting the read-only annotation.

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

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

Three sentences front-load the data returned, follow with the use case, and end with access guidance. No filler or repetition; every sentence contributes.

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

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

For a zero-parameter snapshot tool with no output schema, the description is complete: it names every data category returned, states when to call it, and flags the entitlement requirement. An agent has enough to decide to invoke it and know what to expect.

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

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

The schema declares zero parameters and the description covers 100% of the (empty) input schema, so parameter-level explanation is unnecessary. The baseline of 4 for zero-parameter tools applies.

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

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

The description begins with a specific verb and resource—'Get a drilling activity snapshot'—and enumerates the exact contents (US/Canada/international rig counts, frac spread count, 30-day permits with by-state breakdown, DUC totals). This distinguishes it from narrower sibling tools such as opa_get_rig_counts or opa_get_well_permits by presenting a combined aggregate snapshot.

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

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

It explicitly says 'Use when the user asks about drilling activity, rigs vs frac spreads, or upstream operations,' giving clear invocation triggers. It also routes entitlement/access questions to opa_get_plans, though it does not state when-not-to-use versus data-focused siblings like opa_get_rig_counts.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the bar for additional disclosure is lower. The description adds useful context beyond annotations: it requires an account entitlement and returns only forecast data available to the account. No contradiction with the annotations exists.

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

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

Three compact sentences front-load the core purpose, then add usage guidance and an entitlement caveat. There is no filler, no repetition of schema data, and every sentence contributes to correct tool selection and invocation.

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

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

For a zero-parameter tool, the description covers the essential context: source, use case, authorization requirement, and a pointer to the current-pricing sibling. It does not elaborate on output format, commodities covered, or time horizons, but the low parameter surface makes those gaps relatively minor.

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

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

The tool has zero parameters and the schema has 100% coverage, so the baseline is 4. There are no parameter semantics for the description to clarify, and the description appropriately does not invent parameter details.

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

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

The description opens with a specific verb and resource: 'Get energy price forecasts from EIA Short-Term Energy Outlook (STEO) and other sources.' It clearly identifies what the tool returns and refers to usage intent ('price predictions, outlooks, or where oil/gas prices are heading'). It distinguishes itself from opa_get_plans but does not explicitly differentiate from price-adjacent siblings like opa_get_futures 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.

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

The description gives an explicit when-to-use condition: 'Use when the user asks about price predictions, outlooks, or where oil/gas prices are heading.' It also points to opa_get_plans as the alternative for current access and pricing. However, it lacks explicit exclusions for other forecast-related siblings, so the guidance is good but not exhaustive.

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

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.

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.

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.

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.

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.

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.

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

Annotations already carry readOnlyHint=true and openWorldHint=true, covering the non-destructive and open-ended input nature. The description adds meaningful context by requiring an eligible account entitlement and clarifying that the API response is authoritative. It does not discuss return format, rate limits, or error handling, but for a simple read-only price tool this is a reasonable augmentation.

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

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

Four sentences with zero waste: the first delivers the core action and scope, the second specifies acceptable inputs, the third routes to the correct alternative, and the fourth provides entitlement and authority context. The most critical information is front-loaded.

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

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

For a single-parameter, read-only price tool, the description covers purpose, input guidance, alternatives, entitlement, and authority. The only notable gap is the lack of an explicit description of the response shape, but the tool's simple purpose and the absence of an output schema make this a minor omission rather than a critical flaw.

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

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

The schema description coverage is 100%, fully documenting the contract parameter with both canonical slugs and legacy compatibility inputs. The prose description repeats these same details without adding significant new meaning, so this dimension settles at the baseline 3 rather than higher.

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

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

The description opens with a specific verb 'Get' and a precise resource: 'the latest front-month futures contract price for energy commodities.' It also lists the canonical instrument slugs, making the tool's scope concrete, and explicitly differentiates itself from the sibling opa_get_futures_curve by naming what that tool does instead.

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

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

Provides clear when-to-use guidance by naming opa_get_futures_curve as the alternative for forward curves and directing users to opa_get_plans for access and pricing confirmation. It also states the prerequisite 'eligible account entitlement' and explains that compatibility inputs are accepted, so an agent knows exactly how to route between the tool and its siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description aligns with those (a 'Get' operation). Beyond annotations, it adds real behavioral context: the account-entitlement requirement, backward-compatibility behavior for 'contract codes and older venue slugs,' the return composition, and the authority caveat that 'the API response is authoritative.' Not quite a 5 because error behavior when entitlement is missing is not disclosed.

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

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

The description is front-loaded with the core purpose and every sentence earns its place: purpose, input guidance, compatibility note, return content, prerequisite, and alternative routing. Minor inefficiencies exist: the canonical-slug sentence duplicates the schema parameter description, and the final sentence packs two distinct ideas (routing to opa_get_plans and API authoritativeness) into one clause.

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

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

For a low-complexity tool (1 optional parameter, no output schema, no nested objects), the description covers purpose, return values, accepted inputs, compatibility behavior, entitlement prerequisite, and an alternative tool. The remaining gaps are minor: what happens if the account lacks entitlement (error vs. empty response) and how many contract months are returned. Overall it is near-complete given the annotations already cover read-only and open-world semantics.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description restates the canonical slugs ('brent, wti, gasoil, natural-gas, ttf-gas, lng-jkm, eu-carbon, or uk-carbon') and compatibility inputs, which largely duplicates the schema's own parameter description ('legacy venue slugs remain accepted for compatibility'). No new syntax, formatting, or behavioral nuance is added beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'Get the futures forward-curve contracts returned for this account.' The 'forward-curve' qualifier and account scoping help distinguish it from generic siblings like opa_get_futures, and the return content ('available contract months with settlement prices plus market-structure analysis') further specifies the purpose. However, it stops short of explicitly contrasting itself with the closest sibling opa_get_futures.

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

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

There is explicit routing: 'Use opa_get_plans for current access and pricing; the API response is authoritative,' which names an alternative and the condition to switch. It also adds the prerequisite 'Requires an eligible account entitlement.' It does not, however, give when-not-to-use guidance relative to the nearest sibling opa_get_futures or data-history alternatives like opa_get_history.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses the returned metrics, supported periods, point-in-time filtering behavior, backfill caveats, entitlement requirements, and authority of the API response. This is substantial, non-obvious behavioral context.

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

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

The description is compact and front-loaded with the primary purpose, followed by usage, return shape, period details, caveats, and alternatives. Every sentence adds relevant information and the text avoids fluff.

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

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

With no output schema, the description still tells the agent what the response contains (high, low, average, change, data point count). It also covers edge cases like backfill timing, account entitlement, and which tool to use for current pricing, making it sufficiently complete for correct invocation.

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

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

The schema already documents all three parameters with descriptions, so the baseline is 3. The description adds value by expanding period meanings (day=24h, week=7d, month=30d, year=365d) and clarifying point-in-time filtering semantics beyond the schema.

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

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

The description opens with a specific verb and resource: 'Get historical price data for a commodity over a time period.' It also frames usage around price trends and historical performance, which clearly separates it from siblings like opa_get_price and opa_get_plans.

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

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

It explicitly says to use this tool when the user asks about price trends, historical prices, or performance over time, and it points to opa_get_plans for current access and pricing. It does not enumerate when-not cases for other price-related siblings, but the guidance is otherwise clear.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description does not contradict them. It adds genuinely useful context beyond annotations: 'Requires an eligible account entitlement' flags an authorization precondition, and 'the API response is authoritative' warns the agent to trust the response over expectations. 'Returns available port prices' reinforces the open-world nature.

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

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

Six sentences with the core purpose front-loaded in the first sentence. Each sentence earns its place: purpose, triggers, filters, return behavior, entitlement, and alternative routing. The filter sentence is slightly redundant with the schema but serves fast scanning.

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

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

For a low-complexity tool (two optional string params, no output schema, no nested objects), the description covers purpose, usage triggers, parameter semantics, return scope, an entitlement prerequisite, and a routing alternative. Error behavior for missing entitlement or empty results is not described, but that is a minor gap given the tool's simplicity.

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

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

Schema description coverage is 100%, so the schema fully documents both parameters. The description's filter sentence largely restates the schema, though 'and/or' does clarify that the two optional filters may be combined. This matches the baseline of 3 for high schema coverage with marginal added meaning.

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

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

The description states a specific verb and resource: 'Get latest marine fuel (bunker) prices returned for the account.' Naming VLSFO, MGO, and IFO380 anchors the domain precisely and differentiates it from siblings like opa_get_diesel_by_state or opa_get_price without needing to inspect their schemas.

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

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

Explicit trigger conditions are given ('Use when the user asks about bunker fuel, marine fuel, VLSFO, MGO, IFO380, or shipping fuel costs'), and an alternative is named with its condition: 'Use opa_get_plans for current access and pricing.' This gives the agent both a clear when-to-use and a clear when-not-to-use.

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

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

Beyond readOnlyHint and openWorldHint annotations, the description discloses API key requirement (OILPRICEAPI_KEY), request counting ('counts as 1 request'), per-account code limits, and that the API response is authoritative. It also explains the narrative option adds plain-English context with disruptions and indicators. No contradiction 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.

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

The description is well-structured, front-loading the purpose and scope, then usage guidance, then the optional narrative parameter, then requirements and alternatives. It is slightly dense, but every sentence contributes valuable routing or invocation information.

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

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

For a tool with no output schema, the description lists what the brief includes (spot prices, 24h changes, forecasts, spreads) and clearly notes the narrative option, API key requirement, request cost, and limits. It is sufficiently complete for an agent to select and call the tool, though exact response structure is not detailed.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds some clarity about natural language vs. API codes and the narrative behavior, but these mostly overlap with the schema's own descriptions. It does not meaningfully extend parameter meaning beyond schema.

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

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

The description opens with a specific verb and resource: 'Get a multi-commodity market brief: latest spot prices, 24h changes, 1-month forecasts... for several commodities in ONE call.' It clearly distinguishes this tool from siblings by explicitly contrasting it with opa_get_price and opa_create_price_subscription.

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

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

It states exactly when to use it: 'Use when the user wants a market snapshot, morning brief, or an at-a-glance read across multiple commodities.' It also gives alternatives — 'For a single price use opa_get_price; for ongoing recurring monitoring use opa_create_price_subscription' — so the agent can route correctly.

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

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

Beyond the readOnlyHint annotation, it explains conditional behavior for both call shapes: omitting hub returns all live hubs, while supplying a hub returns latest price, basis, and basis history. It also discloses that hub series differ in depth, warns to check history_days, and states the entitlement requirement and authoritative API response.

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

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

The description is dense but every sentence earns its place: purpose, use case, hub list, conditional behavior, data-depth caveat, entitlement requirement, and pointer to opa_get_plans. Information is front-loaded and no sentence is filler.

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

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

Despite having no output schema, the description covers what the agent needs: what the tool returns in each mode, which hubs are valid, data depth limitations, account entitlement, and a fallback tool for access/pricing. This makes it self-sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful conditional semantics: omitting hub lists all hubs, and supplying one returns history. It also gives concrete past window examples and warns about depth differences, adding value beyond the raw parameter descriptions.

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

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

The description opens with a specific action and resource: 'Get US physical natural gas hub prices as basis to Henry Hub' with clear units. It then enumerates the exact hubs covered, which separates it from generic price tools like opa_get_price and opa_get_futures.

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

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

It explicitly states 'Use when the user asks about regional gas prices or hub basis' and lists the relevant hubs, giving clear context for selection. It also routes entitlement questions to opa_get_plans, though it does not enumerate exclusions versus every sibling price tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds useful behavioral context: an eligible account entitlement is required, data returned is scoped to what is available to the account, and the API response is authoritative. No contradiction 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.

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

The description is organized and front-loaded: it opens with the core purpose, then gives usage triggers, output options, and access requirements. All four sentences carry useful information without excessive wordiness.

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

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

For a single-parameter, read-only tool with no output schema, the description adequately covers what is returned, optional views, and access requirements. It could specify exact data fields or product list, but the available context is sufficient for correct selection and invocation.

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

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

Schema description coverage is 100%, so the single view parameter is already fully documented with its enum values and default. The description reinforces 'summary view or breakdown by petroleum product,' but does not add meaning beyond the schema.

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

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

The description states a specific action and resource: 'Get the latest EIA weekly petroleum inventory (stocks) data.' It clearly distinguishes the tool from siblings like opa_get_storage or opa_get_opec_production by naming the exact domain (EIA weekly petroleum stocks) and including product-level inventory levels.

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

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

The description gives explicit when-to-use triggers: 'Use when the user asks about oil inventories, crude stocks, weekly EIA stocks, inventory builds/draws, or product-level inventory levels.' It also names opa_get_plans for account access/pricing questions, though it does not explicitly contrast this tool with data-focused alternatives.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful context: an eligible account entitlement is required, results are country-level, and the API response is authoritative. It does not specify units or data availability nuances, but for a zero-parameter read tool this is strong.

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

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

Five short sentences, each earning its place: core purpose, usage triggers, return content, entitlement prerequisite, and fallback guidance. The information is front-loaded and there is no filler.

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

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

For a simple zero-parameter, read-only data lookup, the description covers what the tool returns, when to use it, what precondition exists, and where to route access questions. No output schema exists, but the essential return information is present.

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

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

The tool has zero parameters and the schema coverage is 100%, so the description has no parameter burden. The 0-parameter baseline applies, and the description adds no misleading or unnecessary parameter detail.

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

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

The description opens with a specific verb and resource: 'Get the latest OPEC oil production data.' It clarifies the data product as country-level production figures, which distinguishes it from siblings like opa_get_price or opa_get_rig_counts.

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

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

It explicitly states when to use the tool: 'Use when the user asks about OPEC output, production quotas, supply cuts, or OPEC+ compliance.' It also points to opa_get_plans for access and pricing questions, giving clear routing to an alternative.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already indicate read-only and open-world behavior. The description adds meaningful context: the Baker Hughes source, exact returned metrics, the no-parameter requirement, and the account entitlement caveat. 'The API response is authoritative' complements the openWorldHint. No contradiction 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.

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

Three sentences with no wasted words. The first sentence states purpose and source, the second covers usage triggers and outputs, and the third addresses access and the alternative tool. Information is front-loaded and every sentence earns its place.

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

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

For a zero-parameter read-only tool with no output schema, the description covers the purpose, trigger intents, return fields, and access prerequisites. An agent has enough information to select and invoke the tool correctly. Additional details such as update frequency would be nice but are not necessary.

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

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

The input schema has zero properties and 100% coverage, so the baseline is 4. The description confirms 'No parameters needed,' which is redundant with the schema but harmless given there are no parameters to explain.

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

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

The description clearly states the verb ('Get'), the resource ('latest US oil and gas rig count data'), and the data source (Baker Hughes), and lists the returned fields. It is distinguishable from price, storage, and inventory siblings, though it does not explicitly differentiate from overlapping drilling/well-activity siblings like opa_get_drilling or opa_get_well_activity.

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

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

The description explicitly provides user-intent triggers ('asks about drilling activity, rig counts, or oil field operations') and points to opa_get_plans for access and pricing. It lacks an explicit 'when not to use' statement, but the guidance is sufficient for a simple no-parameter tool.

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

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

The annotations already mark the operation as read-only and open-world, lowering the bar. The description adds meaningful context by warning that an eligible account entitlement is required and that the API response is authoritative, which are non-obvious behavioral traits not visible in the schema or annotations.

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

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

The description is compact: core purpose up front, followed by usage triggers, then access caveat and alternative. Every sentence earns its place and the structure is front-loaded for an agent scanning for relevance.

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

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

For a single-parameter read-only tool, the description covers purpose, semantics, triggers, access requirements, and where to route access/pricing questions. The only minor gap is that it does not describe the response shape, but with no output schema present, the phrase 'API response is authoritative' partially compensates and the scope is clearly bounded.

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

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

Schema description coverage is 100% and the parameter is a single enum with descriptions. The description still adds value by expanding each enum value into more concrete domain meaning: crack as refining margin proxy, basis as regional/grade price differential, and margin as blending/transport margin. This goes beyond merely restating the enum names.

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

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

The description opens with a specific verb-resource pair — 'Get refining and trading spreads' — and then enumerates the exact categories: crack spreads, basis spreads, and blending/transport margins, with clarifying glosses like '3-2-1 crack' and 'regional price differentials.' This makes the tool's scope unmistakable and distinguishes it from price or market-overview siblings.

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

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

It explicitly lists trigger phrasings ('crack spreads, 3-2-1 crack, refining margins, basis differentials, or blend/transport margins') and tells the agent to use opa_get_plans for access/pricing questions, with the API response as the authority. This is clear when-to-use and alternative routing, leaving little to inference.

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

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

Annotations already mark the tool read-only, and the description adds useful context: it returns current levels with changes, requires an eligible account entitlement, and treats the API response as authoritative. Nothing contradicts the annotations, and the added entitlement note is valuable for safe invocation.

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

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

The description is front-loaded with the core purpose and stays compact. Each sentence contributes either scope, trigger conditions, return summary, entitlement requirement, or a pointer to the billing/access tool. No filler.

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

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

For a single-optional-parameter read-only tool, the description covers what, when, and important prerequisites well. The main gap is lack of guidance on how opa_get_storage relates to opa_get_oil_inventories, and the absence of an output schema means return details are only vaguely described.

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

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

Schema description coverage is 100%, so the facility parameter is already fully documented with its enum values and default. The description adds little beyond restating Cushing and SPR, which is acceptable given the schema carries the parameter semantics.

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

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

The description names a specific verb and resource: getting oil storage and inventory levels for Cushing and the SPR. It is clear about scope, but it does not differentiate from the similarly named sibling opa_get_oil_inventories, so an agent may struggle to pick between them.

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

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

The description explicitly says when to use the tool ('Use when the user asks about oil inventories, storage levels, Cushing stocks, or the SPR') and routes access/pricing questions to opa_get_plans. However, it does not mention when not to use it or compare it to the nearby oil inventories sibling.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

With readOnlyHint and openWorldHint already in annotations, the description adds value by flagging the account entitlement requirement and noting that returns are permits with optional aggregation. No contradiction with annotations. It stops short of describing response details or error behavior, but for a simple read-only tool this is acceptable.

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

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

The description is compact and front-loads the core function before usage and entitlement notes. The sentence about opa_get_plans and the authoritative API response is somewhat tangential, but it does not bloat the definition or obscure the main purpose.

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

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

For a read-only tool with three optional parameters and no output schema, the definition covers when to use it, what it returns at a high level, and an important access constraint. The lack of explicit return-field or pagination details is a minor gap given the simple enum-driven views.

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

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

Input schema coverage is 100%, and the view/state/operator properties already carry detailed descriptions, defaults, and enum options. The top-level description only repeats the aggregation concept ('filtered/aggregated by state or by operator'), so it adds little semantic value beyond the schema. Baseline 3 applies.

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

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

The opening sentence pinpoints the resource and operation: 'Get the latest US oil & gas well drilling permit data.' It also specifies the main output shape ('available permits, optionally filtered/aggregated by state or by operator'). However, the top-level description does not explicitly contrast this with the closely related opa_search_well_permits; the distinction is only hinted at in a parameter description.

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

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

It gives clear trigger conditions: 'Use when the user asks about well permits, new drilling permits, permitting activity, or upstream permit trends,' and states the access prerequisite ('Requires an eligible account entitlement'). The description lacks an explicit 'do not use for richer searches' exclusion, though opa_search_well_permits is named in the schema.

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

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

Annotations already mark this as read-only, and the description adds valuable behavioral context: BETA coverage limitations, state-level vs well-level availability, account entitlement requirements, and the API response being authoritative. It does not fully describe response structure or pagination, but with readOnlyHint=true the bar is lower and the coverage caveats are meaningful.

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

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

The description is dense but every sentence contributes: scope, coverage limitations, view enumeration, use cases, and access guidance. It is front-loaded with the core purpose and caveat before listing details, and avoids redundant filler.

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

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

Given three parameters, no output schema, and no required fields, the description provides all essential context: what each view returns, which parameters are needed, when to use the tool, and how to handle account entitlement. An agent can select and invoke this tool correctly without additional information.

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

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

The input schema already provides 100% coverage, describing each parameter and how the view field controls behavior. The description repeats similar information without adding new meaning beyond what the schema already states, 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.

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

The description clearly identifies the tool as retrieving US oil & gas well production data, and distinguishes its scope with a specific BETA caveat about partial coverage. It enumerates the available views, so an agent knows exactly what resource this tool exposes and how it differs from production-adjacent tools like opa_get_well_permits or opa_lookup_well.

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

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

The description explicitly states when to use the tool: for production volumes by state or well, top producers, and cycle times. It also routes users to opa_get_plans for access and pricing, providing clear contextual guidance, though it does not explicitly list exclusions or when to prefer alternative production-data tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable context beyond those: results are grouped by category, visibility varies by account entitlement, and data comes from the live API. No contradiction 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.

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

Four sentences, front-loaded with the core purpose followed by usage triggers and behavior notes. Every sentence earns its place; there is no filler or redundancy.

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

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

The description is thorough for a simple 0-parameter, read-only listing tool, covering purpose, triggers, grouping behavior, and entitlement variance. With no output schema present, the exact return shape is implied but not specified ('grouped by category' partially addresses this), which is a minor gap.

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

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

With zero parameters, the rubric baseline is 4. The description reinforces this with an explicit 'No parameters needed' statement, which removes any doubt for the agent. The schema itself is trivially complete at 100% coverage.

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

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

The description uses a specific verb+resource pair ('List the account-visible commodities returned by the live API') with a clear scope qualifier ('account-visible'). It is easily distinguished from the many sibling data-retrieval tools like opa_get_price and opa_get_history, none of which perform enumeration of commodity codes.

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

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

The description provides three explicit trigger scenarios: asking about available commodities, asking which codes to use, and handling a 'commodity not recognized' error from another tool. This is clear context, though it does not name alternatives or explicit when-not-to-use conditions, which keeps it just below a 5.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: results are account-specific, grouped by category, include 24h changes, support filtering, and 'dataset access varies by account entitlement.' No contradiction with the annotations.

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

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

Five concise sentences, each earning its place: what it returns, when to use it, grouping/changes, filtering, access caveat, and alternative tool. Key information is front-loaded and the text is free of redundancy.

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

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

For a simple tool with one optional enum parameter and no output schema, the description is complete: it explains the return grouping, the 24h change context, the account-entitlement caveat, and routes to the sibling tool when more specific data is needed. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the category parameter is fully documented in the schema. The description only says 'Supports filtering by category,' which adds little beyond the schema. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description states a specific verb and resource: 'Get the current prices returned by the API for this account in one call.' It clearly defines scope (broad market snapshot, grouped by category with 24h changes) and explicitly distinguishes itself from opa_get_price by naming the single-commodity alternative.

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

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

It explicitly says when to use: 'when the user wants a broad market snapshot or asks about overall energy prices.' It also provides the key alternative and condition: 'For a single commodity, use opa_get_price instead.' This gives an agent clear routing guidance.

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

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.

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.

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.

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.

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.

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.