Energetica — Argentine Oil & Gas Data

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

With no annotations provided, the description properly discloses the read-only nature and allowed statement types. It also mentions tier availability (Professional tier and above). However, it omits potential behavioral details like result size limits, timeouts, or how errors are surfaced, which could catch users off guard.

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 concise sentences, each adding distinct value: what it does, what's allowed, and a prerequisite. No redundant information or fluff exists.

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 one-parameter tool with no output schema, the description covers the core functionality, constraints, and usage prerequisite. It lacks explicit details about return format or performance considerations, but given the arbitrary nature of SQL, these are less critical.

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 fully describes the 'sql' parameter with 'SELECT or WITH only', and coverage is 100%. The description adds minimal extra meaning beyond the schema, merely restating the read-only constraint. This meets the baseline but doesn't enhance parameter understanding.

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 'Execute arbitrary read-only SQL against the DuckDB database' with specific constraints (SELECT/WITH only). This distinguishes it from the sibling query tools (e.g., query_investments, query_prices) which are purpose-built for specific data sets, making the purpose unambiguous.

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 tells users to use get_schema first to understand the schema, and restricts usage to SELECT and WITH statements, preventing misuse. While it doesn't name alternative tools, the mention of 'arbitrary' and the constraint to read-only SQL clearly implies this is for custom queries not covered by the sibling 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?

With no annotations, the description carries the full burden. It discloses what output to expect (per-table freshness metrics) but does not mention any potential limitations, side effects, or performance characteristics. For a simple read-only tool, it is adequate but not rich.

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 concise sentences, front-loaded with the main action and output details, then a clear use case. Every word earns its place, with no redundancy or ambiguity.

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 simplicity (no parameters, no output schema), the description adequately covers what is returned and why to use it. It could be slightly more explicit about result format, but 'each table' and the list of metrics make it sufficient.

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 description cannot add parameter-specific semantics. Per guidelines, the baseline for zero-parameter tools is 4; the description appropriately focuses on output rather than inputs.

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: retrieving the latest available data per table, including last period, date range, and total records. This is specific and distinct from sibling query tools, which focus on specific domains or SQL execution.

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 this to understand how current the data is,' providing clear context for when to use it. It doesn't explicitly compare to alternatives, but the use case is well-defined and differentiates it from data querying 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?

No annotations are provided, so the description must carry the burden. It discloses what is returned (schema and metadata) and implies read-only behavior with 'Get' and 'Returns', but does not explicitly state that it does not modify data or mention any limitations or permission requirements.

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 action, and every sentence adds value: the first explains what it does and returns, the second explains when to use it. No 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 tool with one optional parameter and no output schema, the description adequately covers purpose, return content, and usage context. It could mention operational aspects or edge cases, but the tool is straightforward and the parameter description fills the remaining 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?

The input schema has a single parameter 'tabla' with a clear description ('Specific table name. Omit to get all tables.'). The tool description does not add any additional parameter semantics beyond the schema, so it stays at the baseline for full schema 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 clearly states the tool's purpose: 'Get the database schema and metadata.' It lists specific return content (table names, columns, types, descriptions, units, example values), which distinguishes it from sibling query tools like execute_sql or query_investments.

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 usage context: 'Use this to understand what data is available before querying.' This tells the agent when to use it, though it does not mention when not to use it or name 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?

With no annotations, the description carries the full burden for behavioral disclosure. It adds useful context that values are in millions USD and covers drilling, completion, and infrastructure. However, it does not state the return format, whether results are aggregated, or any effect of leaving all filters empty, which is a moderate gap for a query tool.

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 with no fluff. The first sentence states the action, resource, and filters; the second conveys scope and units. Every word 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?

The tool has 5 optional parameters and no output schema, so the description should clarify what the result set looks like. It gives units and categories but does not mention aggregation, pagination, or whether any filter is required. This is a meaningful gap, but the tool's scope is reasonably clear.

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 covers 100% of parameters with descriptions, so this baseline is adequate. The description adds context about the domain and units but does not add syntax-level details beyond what the schema already provides. It aligns with the 'concepto' examples but does not materially improve parameter understanding.

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 ('Query') and names the exact resource: upstream oil & gas investments in Argentina, with the key filter dimensions (company, basin, year). It clearly distinguishes this from sibling tools by domain (investments vs. prices, production, etc.).

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 implies when this tool should be used (for investment data in Argentina) and sets context by listing included expenditure categories. However, it does not explicitly name alternatives or state when not to use it, though sibling tool names make the distinction implicit.

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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It clarifies the types of data included and mentions frequency defaults (daily for Henry Hub, implied for others), but does not describe return format, pagination, or default date behavior. As a query tool, read-only behavior is implicit but not explicitly stated.

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, front-loaded with the core purpose, followed by a concise list of included series. No redundant or filler content; 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?

The description adequately explains the tool's scope and key series. Given that there is no output schema, it could elaborate on return structure, but the description is sufficient for understanding what data can be queried and the default frequency behavior. It is more complete than a minimal stub.

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%, providing baseline 3. The description adds value by grouping the series list into categories (international, local, exchange rates) and noting that Henry Hub is daily, which complements the schema's enum values. It also reinforces default frequency behavior for local prices.

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 'Query' and clearly defines the resource as 'international and local energy prices'. It enumerates specific series (WTI, Brent, Henry Hub, Argentine crude, exchange rates), distinguishing it clearly from sibling tools like query_production or query_trade.

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 clear context for when to use the tool (when needing energy prices or exchange rates listed) without explicitly naming alternatives. It does not include exclusions or when-not-to-use guidance, but the scope is well-defined enough to guide selection.

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?

No annotations are provided, so the description carries the disclosure burden. It adds useful behavioral context (data coverage 2006-present, ~18M records, supports filtering/grouping), but it does not disclose response format, pagination, or performance characteristics.

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 with clear front-loading: the first names the operation and resource, the second provides scope and capabilities. No filler words 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?

Given the 7-parameter schema and no output schema, the description provides sufficient context for a typical query task: it names the data domain, coverage, and available filters/groupings. It does not state the exact return structure, but that is a minor gap for this type of data query 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?

The input schema has 100% description coverage for all 7 parameters, so the baseline is 3. The description does not add parameter-specific semantics 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 uses a specific verb ('Query') and names the exact resource (monthly production data from Argentine hydrocarbon wells). It clearly distinguishes from sibling query_* tools targeting investments, prices, trade, and wells.

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 conveys clear usage context: this is the tool for production data, with filtering and grouping options. It does not explicitly name alternatives or exclusions, but the context is unambiguous for an agent deciding which tool 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?

With no annotations, the description carries the transparency burden. It adds useful behavioral context: values are in FOB USD, and specific HS codes are covered. However, it does not disclose response shape, default behavior with no filters, or other side effects/requirements, which would be valuable for a tool with no output schema.

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 short sentences, with the main action and resource first. It avoids filler, and every sentence contributes either scope, content coverage, or units. This is 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?

Given there is no output schema and no annotations, the description still provides enough context for selection: resource, product coverage, flow direction, and valuation basis. Optional filters appear in the schema. It lacks explicit return-structure or usage examples, but for a straightforward query tool this is largely adequate.

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%, but the descriptions are minimal. The tool description adds meaningful semantics by mapping 'producto' values to HS codes and clarifying that values are in FOB USD, going beyond what the schema states. This helps the agent understand how to choose parameter values correctly.

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 ('Query') and a clear resource ('Argentina hydrocarbon trade balance'), and enriches it with product scope (crude, refined, gas). This clearly distinguishes it from sibling tools like query_prices or query_production, so an agent can readily identify what this tool does.

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 usage by naming the exact data domain but provides no explicit when-to-use guidance or references to alternative tools. There are no exclusions or conditions stated, so the context is inferred rather than directly explained.

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 no annotations, the description carries the transparency burden. It discloses that the tool returns location, type, status, cumulative production, and technical data, and mentions the dataset size (~50,000 wells). However, it does not explicitly state read-only behavior, pagination, rate limits, or default result limits, which are useful for a query tool.

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 concise sentences: it front-loads the purpose, lists return types, and gives dataset scale. Every sentence provides unique information with no fluff 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?

With 8 optional parameters, no required fields, and no output schema, the description lists return fields and dataset size but omits operational details like default limit behavior, pagination, or whether filters are combinable. It is adequate but leaves room for clarification, especially given the absence of an output schema.

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 description adds some high-level context (e.g., 'cumulative production' relates to con_produccion, dataset size aids limit interpretation) but does not elaborate on individual parameters 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 uses a specific verb ('Search and filter') and a clear resource ('Argentine oil & gas wells'), and distinguishes it from sibling tools that focus on other datasets (investments, prices, production, trade). It also states what data is returned, making the tool's purpose unambiguous.

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 usage for well-related queries but does not explicitly state when to use this tool versus alternatives like query_production or query_investments. No when-not or alternative guidance is provided, though the resource context offers some inference.

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