OilPriceAPI

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

No annotations provided, so description carries full burden. It adds critical context about 'Requires a paid plan with energy intelligence access' (auth/pricing constraint). However, it omits operational details like forecast horizons (how far out), update frequency, data volume/structure, or error handling when access is denied.

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, each earning its place: (1) core functionality and source, (2) usage trigger, (3) return value, (4) access requirements. No redundancy or tautology. Information is front-loaded with the specific action and source.

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 output schema exists and no annotations are present, the description provides conceptual coverage (what it returns generally) but lacks structural details about the forecast data format, commodities covered, or time granularity. Sufficient for tool selection but incomplete for result handling.

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 has zero parameters. Per calibration guidelines, zero parameters establishes a baseline of 4. The description correctly does not fabricate parameters, and the absence of params is implicitly clear from the descriptive focus on retrieval without filtering.

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 explicitly states 'Get energy price forecasts from EIA Short-Term Energy Outlook (STEO)'—specific verb, resource, and authoritative source. It clearly distinguishes from siblings like opa_get_history (past data) and opa_get_futures (market contracts) by emphasizing analytical forecasts/outlooks.

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 trigger: 'Use when the user asks about price predictions, outlooks, or where oil/gas prices are heading.' This clearly signals when to select over alternatives. Lacks explicit 'when not to use' or named sibling alternatives, though the forecast/prediction framing implicitly contrasts with current price tools.

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