pyResToolbox MCP Server

Server Quality Checklist

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

Latest release: v1.0.0
Disambiguation4/5
Most tools have distinct purposes within reservoir engineering, but there is some overlap between gas property tools (e.g., gas_z_factor, gas_critical_properties, gas_compressibility) which could cause confusion if an agent doesn't carefully read descriptions. However, each tool targets a specific calculation, and descriptions are detailed enough to differentiate them.
Naming Consistency5/5
Tool names follow a consistent snake_case pattern with clear verb_noun structure (e.g., calculate_brine_properties, gas_formation_volume_factor, oil_bubble_point). There are no deviations in naming conventions, making the set predictable and easy to parse.
Tool Count2/5
With 45 tools, the count is excessive for a single server, even for a comprehensive reservoir engineering toolkit. This many tools can overwhelm agents and increase selection complexity, suggesting the server should be split into more focused sub-servers (e.g., gas PVT, oil PVT, simulation tools).
Completeness5/5
The tool set provides extensive coverage of reservoir engineering domains, including PVT properties for oil, gas, and brine, flow calculations, heterogeneity analysis, simulation support, and phase behavior. There are no obvious gaps; it supports full workflows from data conversion to simulation input generation.
Average 4.7/5 across 45 of 45 tools scored. Lowest: 3.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under GPL 3.0.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the physics behind the calculation and mentions the return format (dictionary with incremental GOR and guidance), but doesn't specify computational characteristics like performance expectations, error conditions, or validation requirements for the input parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, physics, applications, args, returns) and efficiently conveys necessary information. While comprehensive, every sentence serves a purpose - no redundant or wasted text. The formatting with bold headers enhances readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's specialized engineering purpose, no annotations, and the presence of an output schema, the description provides good context. It explains the physics, applications, and what the tool returns. However, for a calculation tool with specific physical constraints, additional guidance on parameter validation or typical use cases would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% (the schema has no descriptions for individual parameters), but the description provides a high-level overview: 'Separator pressure, temperature, and oil API' in the Args section. However, it doesn't explain the meaning or significance of these parameters beyond their names, nor does it provide guidance on valid ranges beyond what's in the schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific purpose: 'Calculate incremental GOR from separator to stock tank' with the physics explanation of gas evolution between conditions. It distinguishes itself from sibling tools like 'oil_solution_gor' by focusing specifically on the incremental gas between separator and stock tank rather than total solution gas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool through the 'Applications' section (separator optimization, gas recovery calculations, tank venting requirements, VOC emissions estimation). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools for related calculations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully explains what the tool computes (specific gravity of gas liberated at stock tank conditions), describes the return format (dictionary with values, units, and inputs), and clarifies the dimensionless nature of the output (air = 1.0). It doesn't mention error conditions, performance characteristics, or validation requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and front-loaded: purpose first, then context, applications, return format, and parameter/return sections. Every sentence earns its place with no redundancy or wasted words. The bulleted list of applications is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the calculation (5 nested parameters, no schema descriptions) and the existence of an output schema, the description does an adequate job explaining what the tool does and why. However, the complete lack of parameter documentation in both schema and description creates a significant gap for a tool with this level of technical complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for undocumented parameters. While it mentions that the 'request' parameter includes 'oil properties and separator conditions,' this is too vague given the 5 nested parameters (api, degf, sg_g, p, psep) that remain unexplained. The description doesn't provide meaningful guidance on what these parameters represent or how they interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Calculate') and resource ('stock tank gas specific gravity'), and distinguishes it from siblings by focusing on gas liberated at stock tank conditions. It explicitly differentiates from 'evolved_gas_sg' by specifying the context of atmospheric pressure and temperature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool by listing specific applications (sales gas quality, flare gas calculations, VOC emissions, safety assessments). However, it doesn't explicitly state when not to use it or name alternatives among the many sibling tools, particularly 'evolved_gas_sg' which appears closely related.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool performs calculations (not destructive), returns specific properties, and mentions accuracy improvements with optional boiling point and damping factor. However, it lacks details on error handling, performance characteristics, or rate limits, which would be helpful for a computational tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headers and bullet points, making it easy to scan. It's appropriately sized for a specialized tool, though some sections like 'Critical for:' could be more concise. Every sentence adds value, but minor trimming could improve efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (critical property estimation), no annotations, and an output schema present, the description is fairly complete. It covers purpose, method, parameters, returns, and applications. However, it could benefit from more behavioral details (e.g., computational limits) since annotations are absent, and the output schema handles return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaningful context: parameters are 'Molecular weight, specific gravity, optional boiling point, damping' and explains their roles ('Uses molecular weight and specific gravity', 'Optional boiling point for improved accuracy', 'Damping factor for heavy ends'). This clarifies beyond the schema's technical definitions, though it doesn't detail array handling or default values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate critical properties using Twu (1984) correlation.' It specifies the exact method (Twu 1984), the properties calculated (Tc, Pc, Vc), and distinguishes it from siblings like 'gas_critical_properties' by focusing on petroleum fractions and plus fractions with the Twu method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'Most widely used method for estimating Tc, Pc, Vc for petroleum fractions and plus fractions' and 'Critical for: EOS (PR, SRK) fluid characterization, Plus fraction splitting, Compositional simulation, Phase behavior modeling.' It doesn't explicitly state when not to use it or name alternatives, but the context is sufficient for informed selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool 'computes' and 'returns' values, implying a read-only calculation, and mentions that 'evolved gas composition changes with pressure' which adds useful behavioral context. However, it lacks details on error handling, performance, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement, usage contexts, behavioral note, and return details. It is appropriately sized, though the bulleted list of applications could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a physics-based calculation with 1 parameter (a nested object) and an output schema, the description is reasonably complete. It explains the tool's purpose, usage, key behavioral aspect (pressure variation), and return format, though it could benefit from more detail on input constraints or examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It adds significant meaning beyond the schema by explaining that parameters include 'oil properties, pressure(s), and separator conditions', clarifying the purpose of the nested 'request' object and its role in the calculation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Calculate evolved gas specific gravity') and resource ('gas evolved from oil as pressure decreases below bubble point'), distinguishing it from siblings like 'gas_sg_from_composition' or 'weighted_average_gas_sg' by focusing on pressure-dependent evolution from oil.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('for material balance calculations, surface facility design, gas sales forecasting' and 'when pressure decreases below bubble point'), but does not explicitly state when not to use it or name alternative tools among the siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the calculation method (Standing 1947 correlation) and return format (dictionary with Rs, method, units, inputs), which is helpful. However, it doesn't mention error conditions, numerical precision, validation of inputs, or whether the calculation is deterministic - important behavioral aspects for a computational tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with purpose, method, usage context, return format, and parameter explanation in logical order. Every sentence earns its place, though the Args/Returns section could be slightly more integrated with the main description rather than appearing as separate documentation blocks.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a computational tool with no annotations but with an output schema (implied by 'Returns' section), the description provides good coverage. It explains what the tool does, when to use it, the method employed, return format, and parameter meanings. The main gap is lack of error handling or edge case information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0% (no parameter descriptions in schema), so the description must compensate. It successfully explains that parameters represent 'bubble point parameters (API, temperature, bubble point, gas gravity)' and clarifies the purpose of each in the context of the calculation. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'calculate' and resource 'solution GOR at bubble point', explicitly naming the Standing correlation method. It distinguishes from sibling tools like 'oil_bubble_point' (which likely calculates pressure rather than GOR) and 'oil_solution_gor' (which may calculate GOR at other conditions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'when you know the bubble point pressure and need to calculate the corresponding solution GOR.' However, it doesn't explicitly mention when NOT to use it or name specific alternative tools from the sibling list that might be relevant for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the logic (calculations based on inputs) and return format (tuple/dictionary), which is helpful. However, it lacks details on error handling, performance, or side effects (e.g., data mutation), leaving gaps for a tool that performs validation and imputation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (DATA VALIDATION TOOL, Logic, Use Cases, Returns) and front-loaded key information. Every sentence earns its place by clarifying purpose, logic, usage, or output without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (validation and imputation logic), no annotations, and an output schema (implied by 'Returns'), the description does a good job covering purpose, logic, and use cases. However, it could be more complete by addressing potential errors or assumptions in calculations, slightly reducing its adequacy for full contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It adds value by explaining the 'request' parameter contains 'available gas gravities and GORs' and outlines the logic for handling sg_g and sg_sp, providing context beyond the bare schema. However, it does not detail all parameters (e.g., rst, rsp, sg_st), slightly limiting completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('validate', 'impute', 'calculate') and resources ('gas gravities', 'missing values'), distinguishing it from siblings like 'gas_sg_from_composition' or 'weighted_average_gas_sg'. It explicitly defines what the tool does: checking consistency and calculating missing values based on provided inputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool through listed 'Use Cases' (e.g., QC PVT data, fill gaps, validate measurements), which helps guide appropriate usage. However, it does not explicitly state when not to use it or name specific alternatives among siblings, keeping it from a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses the calculation formula and return format (dictionary with weighted average SG and breakdown), which is helpful. However, it doesn't mention error handling, numerical precision, or validation of input ranges beyond what the schema's exclusiveMinimum/minimum hints at.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (purpose, use cases, formula, args, returns). Every sentence earns its place, though the 'Args' and 'Returns' sections slightly duplicate information that could be inferred from the formula and context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a calculation tool with no annotations but an output schema, the description is quite complete. It explains the purpose, use cases, mathematical formula, parameter roles, and return structure. The main gap is lack of explicit error/edge-case handling, but the formula and parameter constraints provide reasonable coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides the exact formula showing how all four parameters (sg_sp, rsp, sg_st, rst) interact, defines units (scf/stb), and explains the weighted averaging logic. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Calculate weighted average gas specific gravity'), identifies the resource ('from separator stages'), and distinguishes from siblings by focusing on a multi-stage separation calculation. Unlike tools like 'gas_sg_from_composition' or 'stock_tank_gas_sg', this explicitly handles weighted averaging across stages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Use Cases' section provides clear context for when to use this tool (multi-stage separation optimization, surface facility design, gas sales allocation, material balance). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools for simpler single-stage calculations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (e.g., scans files, extracts data, reports errors) and the output format. However, it lacks details on error handling, performance characteristics, or any limitations (e.g., file size constraints), which prevents a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (e.g., 'What It Does', 'Applications', 'Workflow'), making it easy to scan. However, it includes some redundancy (e.g., repeating tool purpose in multiple sections) and could be more concise by trimming less critical details without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (simulation diagnostics), no annotations, and an output schema present, the description is mostly complete. It covers purpose, usage, applications, and output format. However, it lacks details on potential errors or edge cases, which would enhance completeness for such a specialized tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'Path to PRT file and output options' in the Args section, which aligns with the 'filename' parameter in the schema. However, it does not detail the 'silent' parameter or provide additional semantic context beyond what is minimally implied, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('extract', 'parse', 'scans', 'identifies') and resources ('convergence problem cells', 'ECLIPSE/Intersect PRT files'). It distinguishes itself from sibling tools by focusing on simulation diagnostics and problem cell extraction, unlike the sibling tools which are primarily for fluid properties, calculations, and validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidelines through sections like 'Applications' (e.g., 'Convergence Debugging', 'Model QC', 'Performance Tuning', 'Numerical Stability') and 'Workflow' (a 5-step process). It clearly indicates when to use this tool—for analyzing simulation output files to debug issues—without needing to specify alternatives, as sibling tools serve different purposes (e.g., fluid property calculations).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it 'Estimates specific gravity' (clarifying it's an estimation), explains the Jacoby aromaticity factor scale, and states the return format ('Returns specific gravity (dimensionless, water=1)' and 'Dictionary with specific gravity, method, and inputs'). It lacks details on error handling or computational limits, but covers core behavioral aspects well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bold headings and bullet points, making it easy to scan. It is appropriately sized, with every sentence adding value (e.g., explaining the tool's purpose, factor scale, applications, and returns). A minor point: the 'Args' and 'Returns' sections slightly repeat information from earlier, but overall it's efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (involving specialized petroleum engineering calculations), no annotations, and an output schema present, the description is complete enough. It covers purpose, parameter semantics, usage context, and behavioral details like the estimation nature and return format. The output schema handles return values, so the description doesn't need to explain them further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It adds significant meaning beyond the schema: it explains that 'mw' is 'Molecular weight (lb/lbmol)' and 'ja' is the 'Jacoby aromaticity factor' with a detailed scale (0.0 to 1.0), including interpretations like '0.0 = Pure paraffinic' and '1.0 = Pure aromatic.' This provides essential context not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate oil specific gravity from molecular weight and Jacoby aromaticity.' It specifies the verb ('Calculate'), resource ('oil specific gravity'), and method ('from molecular weight and Jacoby aromaticity'), distinguishing it from sibling tools like 'oil_sg_from_api' or 'gas_sg_from_composition' that use different inputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool through the 'Applications' section, listing specific scenarios like 'Plus fraction (C7+) characterization' and 'EOS fluid modeling.' However, it does not explicitly state when not to use it or name alternative tools (e.g., 'oil_sg_from_api'), though the context implies it's for undefined petroleum fractions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it performs a mathematical conversion (not destructive), handles input validation (beta must be 0-1), returns a dictionary with specific fields, and notes accuracy limitations (approximate, depends on distribution). However, it lacks details on error handling or performance aspects like rate limits, leaving minor gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (e.g., Parameters, Use Cases, Returns), but it is verbose with extensive background information (e.g., definitions of beta and Lorenz coefficients, typical ranges) that, while informative, could be condensed. Some sentences, like detailed explanations of beta and Lorenz, may not be essential for tool invocation, reducing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mathematical conversion with accuracy caveats), no annotations, and an output schema (implied by the Returns section), the description is highly complete. It covers purpose, usage, parameters, returns, common mistakes, example usage, and notes on assumptions, providing all necessary context for an AI agent to use the tool correctly without relying on structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must fully compensate. It provides extensive parameter semantics: defines 'value' as the Dykstra-Parsons beta coefficient (0-1), explains its calculation (β = (k50 - k84.1) / k50), gives typical ranges (0.3-0.8), and includes an example (0.6). This adds significant meaning beyond the bare schema, fully documenting the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Convert Dykstra-Parsons beta to Lorenz coefficient.' It specifies the exact conversion (beta→Lorenz), distinguishes it from its sibling 'lorenz_to_beta' (reverse conversion), and provides context about heterogeneity metrics, making the purpose specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly outlines when to use this tool in the 'Use Cases' section, including literature conversion, reservoir comparison, simulation input, analog studies, and historical data conversion. It also distinguishes it from alternatives by noting that conversion assumes log-normal permeability distribution and may be less accurate for non-log-normal cases, providing clear guidance on applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (computes comprehensive brine properties), mentions it uses industry-standard correlations, and includes practical details like common mistakes (e.g., unit conversions, temperature types) and effects of dissolved gases. However, it lacks explicit information on rate limits, error handling, or computational constraints, which slightly limits transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections like Parameters, Properties Calculated, Applications, and Returns, but it is overly verbose with redundant details (e.g., extensive lists of properties and applications). Some sentences could be condensed without losing clarity, making it less front-loaded and efficient than ideal for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (calculating multiple brine properties with gas saturation effects), no annotations, and an output schema that documents return values, the description is highly complete. It covers purpose, parameters, behavior, applications, common mistakes, and example usage, providing all necessary context for an agent to use the tool effectively without relying on structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides detailed parameter semantics beyond the schema, including units (psia, °F, wt%), valid ranges (e.g., p > 0, degf -460 to 1000, wt 0-30), typical values, examples, and explanations of effects (e.g., salinity increases density). This adds significant value over the minimal schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool calculates properties of CH4 or CO2 saturated brine, listing specific properties (density, viscosity, compressibility, formation volume factor) and distinguishing it from sibling tools like 'gas_density' or 'oil_density' by focusing on brine with dissolved gases. It uses clear verbs ('calculate', 'computes') and specifies the resource ('brine properties').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool, listing applications such as aquifer analysis, water injection, CO2 sequestration, geothermal reservoirs, pressure maintenance, and material balance calculations. It also distinguishes usage from potential alternatives by specifying it's for brine (not gas or oil) and includes dissolved gas effects, with no misleading or contradictory information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and excels. It details the density formula, behavior (e.g., 'Increases with pressure', 'Decreases with temperature'), typical ranges, and critical notes on units and conditions. It also warns about common mistakes, providing rich context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections like 'Parameters', 'Density Formula', and 'Common Mistakes', but it is lengthy with some redundant information (e.g., repeating parameter details in the example). While informative, it could be more front-loaded and concise, as not all sentences earn their place equally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 0% schema description coverage and no annotations, the description is highly complete. It covers purpose, parameters, formula, behavior, returns (though an output schema exists), common mistakes, and example usage. It provides all necessary context for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description fully compensates by providing detailed parameter semantics. Each parameter is explained with descriptions, valid ranges, typical values, examples, and optionality. It adds meaning beyond the schema, such as the significance of 'zmethod' options and the impact of non-hydrocarbon fractions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Calculate') and resource ('gas density (ρg) at reservoir conditions'), distinguishing it from siblings like 'oil_density' or 'gas_compressibility'. It emphasizes this as a 'CRITICAL GAS PVT PROPERTY' for specific applications like gradient calculations and material balance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (e.g., 'Essential for gradient calculations, well pressure analysis, and material balance') and includes a 'Common Mistakes' section that implicitly guides usage by highlighting pitfalls. However, it does not explicitly compare to alternatives like 'gas_z_factor' or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains what the tool does (creates dimensionless aquifer influence functions), the integration method (numerical integration with Gaussian quadrature), output format (dictionary with specific keys), and practical considerations like common mistakes and scaling requirements. This provides comprehensive behavioral context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Background, Applications, etc.), but it's quite lengthy with multiple paragraphs that could be more streamlined. While all content is relevant, some sections (like extensive background theory) might be more detailed than necessary for tool selection, affecting conciseness despite good organization.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (aquifer modeling with multiple parameters), no annotations, and an output schema that exists but isn't detailed here, the description provides exceptional completeness. It covers purpose, parameters, methodology, outputs, applications, common mistakes, examples, and integration instructions, making it fully self-contained for understanding and using the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage (the schema has only one parameter 'request' with nested properties), the description compensates fully by detailing four key parameters (res, start, end, rows) with their meanings, constraints, typical ranges, examples, and physical interpretations. It also covers additional parameters from the schema (like infl, ei, piston) in the background and application sections, providing substantial semantic value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool generates Van Everdingen & Hurst aquifer influence functions for AQUTAB keyword in ECLIPSE/Intersect, specifying both the action ('generate') and resource ('aquifer influence functions'). It clearly distinguishes this from sibling tools by focusing on aquifer modeling rather than fluid properties or other reservoir engineering calculations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (aquifer modeling, material balance, pressure maintenance, etc.) and mentions integration with ECLIPSE. However, it does not explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the specialized nature implies it's for aquifer-specific calculations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels at behavioral disclosure. It explains the mathematical method (Dykstra-Parsons log-normal distribution), output structure, common mistakes, limitations (idealized properties vs actual reservoir data), and specific constraints like layer sorting and equal thickness assignment.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but lengthy with some redundancy (usage example appears twice). While well-structured with clear sections, it could be more concise by eliminating repetition and tightening some explanations without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, no annotations, and rich output schema, the description provides complete context. It explains the method, output structure, applications, limitations, and practical considerations, making it fully self-contained for an AI agent to understand and use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides extensive parameter documentation including purpose, valid ranges, typical values, examples, and practical guidance. It covers all parameters (lorenz, nlay, k_avg, h) and explains their relationships and constraints beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates layered permeability distributions from a Lorenz coefficient, specifying it creates detailed layer-by-layer permeability and thickness distributions. It distinguishes from siblings by focusing on reservoir simulation model building and waterflood prediction, which none of the sibling tools mention.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (reservoir simulation, waterflood prediction, conformance studies, etc.) and includes a 'Critical for' section with specific applications. However, it doesn't explicitly state when NOT to use it or name specific alternative tools among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does an excellent job explaining what the tool does: generates tables for reservoir simulation, describes the mathematical models (Corey and LET formulas), explains output format, and provides practical guidance. It doesn't mention rate limits, authentication needs, or computational cost, but covers the core behavior thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but quite long with multiple sections (Parameters, Correlation Families, Table Types, etc.). While all content is valuable, it could be more front-loaded with critical information. The structure is logical but not optimally concise for quick scanning by an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (multiple correlation models, table types, and many parameters) and the presence of an output schema, the description is exceptionally complete. It covers purpose, usage, parameters, mathematical background, workflow, return values, common mistakes, and examples. The output schema existence means the description doesn't need to detail return structure, allowing focus on conceptual guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0% (all parameters are in a nested 'request' object with no descriptions at the top level), but the description compensates fully with detailed parameter documentation. Each parameter gets clear explanations, typical ranges, examples, and context about when they're required (e.g., which parameters apply to Corey vs LET, SWOF vs SGOF). This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate relative permeability table for reservoir simulation' with specific details about creating saturation-dependent curves for named simulators (ECLIPSE, Intersect, CMG). It distinguishes from sibling tools by focusing on relative permeability table generation, which is unique among the listed reservoir engineering tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use different correlation families (Corey for quick estimates/standard cases, LET for history matching/complex curves), table types (SWOF for water-oil, SGOF for gas-oil, SGWFN for three-phase), and includes a detailed workflow section. It also lists common mistakes to avoid, giving clear usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels by disclosing key behavioral traits. It details the database source (NIST, API), explains that properties are EOS-specific, warns about common mistakes (e.g., misspellings, wrong EOS), and provides usage guidance (e.g., PR79 recommended). This goes beyond basic functionality to include operational context and limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose but includes extensive sections (e.g., 'Available Components,' 'EOS Models,' 'Applications') that, while informative, could be streamlined. Some sentences, like detailed lists of components, may not all earn their place for conciseness, though the structure is organized with headings for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (database lookup with EOS-specific properties), no annotations, and an output schema present, the description is highly complete. It covers purpose, parameters, returned properties, usage scenarios, common mistakes, examples, and notes, providing all necessary context for an AI agent to use the tool effectively without relying on structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It does so by elaborating on both parameters: for 'component,' it provides examples, notes case-insensitivity, and lists available components; for 'eos,' it explains options, default, and recommendations. This adds significant meaning beyond the bare schema, ensuring parameters are well-understood.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get critical properties for hydrocarbon components from database.' It specifies the verb 'Get' and the resource 'critical properties for hydrocarbon components,' distinguishing it from sibling tools like 'gas_critical_properties' or 'oil_twu_critical_properties' by focusing on a database lookup for compositional analysis rather than calculations or specific fluid types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool, such as for 'compositional analysis, EOS calculations, and phase behavior modeling,' and lists applications like 'Compositional Simulation' and 'Flash Calculations.' However, it does not explicitly state when not to use it or name specific alternatives among sibling tools, though it implies alternatives for components not in the database.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It explains Bg behavior (decreases with pressure, increases with temperature), typical ranges (0.001-0.01 rcf/scf), formula details, return structure, common mistakes, and critical notes about using reservoir conditions. This provides comprehensive behavioral context beyond basic calculation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Bg Behavior, Formula, Returns, Common Mistakes, Example Usage, Note) and every sentence adds value. While comprehensive, it's appropriately sized for a complex tool with many parameters and no annotations, though slightly lengthy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, 7 parameters with 0% schema coverage, no annotations, but with output schema, the description is exceptionally complete. It covers purpose, parameters, behavior, formula, returns, common mistakes, examples, and critical usage notes, providing everything needed for correct tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed parameter information: valid ranges, typical values, examples, optional/default values, and zmethod options. It adds significant meaning beyond the bare schema, including practical guidance like pressure must be absolute (psia) not barg/psig.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates the gas formation volume factor (Bg), specifying it's a critical PVT property that computes the ratio of gas volume at reservoir to standard conditions. It distinguishes from siblings like oil_formation_volume_factor by explicitly mentioning gas-specific behavior and common confusion with oil FVF.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (material balance, reserve calculations, production forecasting) and mentions using the gas_z_factor tool for Z calculations. However, it doesn't explicitly state when NOT to use it or name specific alternative tools among siblings for related calculations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: it performs numerical integration ('The integration is performed numerically'), returns approximate but accurate results, outputs a dictionary with specific keys (value, method, units, inputs), and includes important behavioral notes like 'Always use reservoir conditions' and warnings about common mistakes (e.g., using wrong pressure units or temperature scales).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Pseudopressure Formula, Why Pseudopressure, Applications, Returns, Common Mistakes, Example Usage, Note) and uses bold headings for readability. While comprehensive, it is appropriately sized for a complex 8-parameter tool with no annotations. Some sections like 'Why Pseudopressure' could be slightly condensed, but overall it earns its length with valuable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no annotations, but with output schema), the description is highly complete. It covers purpose, parameters, formula, rationale, applications, return structure, common mistakes, and example usage. The output schema existence means the description doesn't need to detail return values, but it still provides a helpful summary. This addresses all necessary context for accurate tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage (the schema has no descriptions for individual parameters beyond the request model), the description compensates fully by providing detailed parameter information. Each parameter is documented with type, required/optional status, valid ranges, typical values, examples, and semantic meaning (e.g., 'Gas specific gravity (air=1.0)', 'Reservoir temperature in °F'). This adds substantial value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate gas pseudopressure difference (m(p))' with a specific verb ('Calculate') and resource ('gas pseudopressure difference'). It distinguishes from siblings by emphasizing this is a 'CRITICAL GAS ANALYSIS TOOL' for linearizing gas flow equations, unlike other gas property tools like gas_compressibility or gas_viscosity that compute individual properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: 'Essential for accurate gas well performance analysis' and lists specific applications like gas well testing, material balance, and reservoir simulation. However, it does not explicitly state when NOT to use it or name alternative tools for related calculations, though the sibling list includes tools like gas_rate_linear that might be alternatives in some contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It discloses the mathematical method (pseudopressure formulation), explains what the calculation accounts for (Z-factor, viscosity variations), provides the flow formula, describes return format, lists common mistakes, and includes example usage. This gives comprehensive behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, parameters, method, formula, returns, mistakes, example). While comprehensive, some sections like the detailed parameter list and common mistakes are lengthy but necessary for this complex tool. Every sentence adds value, though it could be slightly more front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 12-parameter engineering tool with no annotations, the description provides exceptional completeness. It covers purpose, methodology, parameters, formula, returns, common pitfalls, and examples. The output schema exists but the description still usefully explains return structure. This gives agents everything needed to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides extensive parameter documentation. Each parameter gets: purpose explanation, units, validity ranges, typical values, examples, and practical guidance (e.g., 'must be absolute' for pressure, 'should be well spacing/2' for drainage radius). This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates gas production rate for vertical wells with radial flow geometry using real gas pseudopressure formulation. It distinguishes from sibling tools like 'gas_rate_linear' by specifying radial flow geometry and from 'gas_pseudopressure' by focusing on production rate calculation rather than pseudopressure alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (vertical wells with radial flow geometry, gas systems requiring pressure-dependent property accounting) and mentions it's more accurate than simplified Darcy's law. However, it doesn't explicitly state when NOT to use it or name specific alternative tools beyond the general comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by explaining key behaviors: it generates tables with logarithmic pressure spacing, finer near bubble point; optionally exports ECLIPSE files; calculates missing values (pb, rsb) when not provided; and returns a dictionary with table, summary, columns, etc. It doesn't mention computational cost or rate limits, but covers most operational aspects thoroughly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Generated Properties, Table Structure, etc.) and front-loads the core purpose. While comprehensive, some sections like the detailed parameter documentation are necessarily lengthy given the complexity. Every sentence adds value, though it could be slightly more concise in the 'Common Mistakes' and 'Example Usage' sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, no annotations, but has output schema), the description is remarkably complete. It explains what the tool does, when to use it, all parameters thoroughly, generated properties, table structure, export functionality, return format, common mistakes, and includes a full example. The output schema existence means it doesn't need to exhaustively document return values, which it appropriately references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate - and it does excellently. Each parameter is documented with meaning, units, validity ranges, examples, defaults, and practical notes (e.g., 'If 0, auto-calculates', 'Typical: 0.6-1.2', 'More rows = finer resolution'). It adds significant value beyond what a bare schema would provide, explaining parameter interactions and recommendations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate comprehensive black oil PVT table' with specific properties (Rs, Bo, μo, ρo, Co) and pressure range (14.7 psia to specified maximum). It distinguishes from siblings by emphasizing it's 'the most comprehensive PVT tool' for 'complete tables for reservoir simulation input or analysis', unlike simpler property calculators in the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Use for complete reservoir analysis or simulation input preparation') and provides alternatives by noting it's 'the most comprehensive PVT tool', implying simpler sibling tools like 'oil_bubble_point' or 'oil_solution_gor' might be used for specific calculations. It also includes 'Common Mistakes' section with practical guidance on parameter settings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It explains the correlation method used, viscosity behavior patterns (p < pb, p = pb, p > pb), typical value ranges for different oil types, sensitivity to temperature/gas content, and includes important warnings about common mistakes. This provides comprehensive behavioral context beyond basic parameter documentation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Viscosity Behavior, Typical Ranges, Returns, Common Mistakes, Example Usage, Note). While comprehensive, some sections could be more concise - the 'Common Mistakes' and 'Example Usage' are quite detailed. However, every sentence adds value for understanding this complex calculation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 7-parameter engineering tool with no annotations and 0% schema description coverage, the description provides exceptional completeness. It covers purpose, methodology, parameter semantics, behavioral patterns, typical outputs, common pitfalls, and includes a detailed example. The existence of an output schema reduces the need to explain return format, but the description still helpfully summarizes it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by providing detailed parameter explanations including physical meaning, valid ranges, examples, and relationships between parameters. It explains how api affects viscosity, temperature effects, pressure behavior, and the critical relationship between p, pb, rs, and rsb that isn't apparent from schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates oil viscosity at reservoir conditions using the Beggs-Robinson correlation. It specifies this is a 'CRITICAL PVT PROPERTY' and distinguishes from siblings like oil_density or oil_compressibility by focusing specifically on viscosity behavior and calculation methodology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when this tool is relevant (for reservoir engineering calculations affecting flow rates and recovery) and includes 'Common Mistakes' section that implicitly guides usage. However, it doesn't explicitly state when to use alternatives like gas_viscosity or other oil property tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and does so effectively. It describes the recursive processing behavior, validation of file existence, identification of missing references, optional archiving functionality, and support for various path types (absolute, relative, same directory, nested chains). It also specifies output formats. The only minor gap is lack of explicit mention about whether this is a read-only operation or has side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (What It Does, Applications, Workflow, INCLUDE File Support, Output Formats, Args, Returns) that make it easy to scan. Every sentence adds value, with no redundant information. The bold headers provide excellent visual organization while maintaining efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (recursive file processing, validation, optional archiving) and the presence of an output schema (which handles return values), the description provides complete context. It covers purpose, usage scenarios, workflow, file path support, output formats, and parameter semantics. With no annotations, it successfully conveys the tool's behavior and capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The 'Args' section provides high-level parameter semantics: 'List of DATA files, zip option, console output preference'. The workflow section further clarifies that files2scrape are 'main DATA file(s) to check'. While it doesn't detail every property of the nested ZipSimDeckRequest object, it gives sufficient context for an agent to understand what parameters are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('validate and process', 'recursively process', 'find all INCLUDE files', 'validate references', 'create archive') and resources ('ECLIPSE simulation deck', 'INCLUDE files'). It explicitly distinguishes this deck management tool from all sibling tools, which are exclusively fluid property calculators with no overlap in functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'Applications' section provides explicit guidance on when to use this tool: for deck validation before submission, deck transfer for sharing, version control archiving, and QC checks before cluster runs. It also implicitly suggests when not to use it (for fluid property calculations like all sibling tools). The workflow section further clarifies the typical usage sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits. It explains the calculation method in detail, includes typical values and ranges, describes non-hydrocarbon effects on SG, specifies the return structure, and warns about common mistakes and constraints (e.g., 'Mole fractions must sum to 1.0').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections but is overly verbose for a tool description. While all content is valuable, it includes extensive details like the full formula, typical hydrocarbon MW ranges, and multiple application examples that could be condensed. It's front-loaded with purpose, but later sections add bulk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the calculation, no annotations, and an output schema (implied by the 'Returns' section), the description is highly complete. It covers purpose, usage, parameters, method, outputs, examples, and pitfalls, leaving no gaps for an AI agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate, which it does excellently. It provides detailed parameter semantics: purpose, units, valid ranges, typical values, examples, and contextual meaning (e.g., 'hc_mw' as 'average MW of the hydrocarbon fraction, not individual component MW'). This goes far beyond what a bare schema would offer.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate gas specific gravity from composition' using a specific method ('molecular weight weighted average'). It distinguishes from siblings like 'gas_sg_from_gradient' and 'weighted_average_gas_sg' by emphasizing compositional input rather than gradient or averaging of multiple SG values.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Essential when gas composition is known but SG measurement is unavailable or unreliable.' It also lists specific applications (e.g., 'Compositional Simulation,' 'Gas Plant Feed') and provides guidance on when not to use it via 'Common Mistakes' (e.g., 'Using weight fraction instead of mole fraction').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: it computes comprehensive properties, uses a specific model (Duan & Sun 2003), accounts for mutual solubility, handles unit systems, includes physics effects (pressure, temperature, salinity), and returns a detailed dictionary. It also notes critical applications and common pitfalls, providing rich behavioral context beyond basic functionality.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Properties Calculated, Applications, Returns, Common Mistakes), but it is lengthy with some redundancy (e.g., repeating mutual solubility details). Every sentence adds value, but it could be more front-loaded; the core purpose is stated early, but extensive details follow. It's efficient for a complex tool but slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, no annotations, and an output schema (implied by 'Returns' section), the description is highly complete. It covers purpose, parameters, physics, applications, returns, common mistakes, and example usage. The output schema is described in detail in the 'Returns' section, making it fully adequate for an agent to understand and use the tool effectively in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides detailed parameter semantics: pres (pressure in psia/bar with typical ranges), temp (temperature in °F/°C with typical ranges), ppm (salinity in ppm with conversion examples), metric (unit system flag), and cw_sat (compressibility calculation flag). Each parameter includes units, constraints, examples, and practical guidance, adding significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool calculates CO2-brine mutual solubilities and properties using the Duan & Sun (2003) model, specifying the verb 'calculate' and resource 'CO2-brine mutual solubilities and properties'. It distinguishes from siblings like 'calculate_brine_properties' by focusing specifically on CO2-brine systems with mutual solubility, making it highly specific and differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool for CO2 sequestration, CO2-EOR, geothermal applications, aquifer storage, and material balance calculations. It includes a 'Common Mistakes' section with warnings about unit systems, salinity conversion, and compressibility flags, offering clear when-to-use and when-not-to-use advice without naming specific alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers comprehensive behavioral information. It explains what the tool creates (idealized flow distribution, Lorenz curve with 20 points), curve behavior for different L values, assumptions (log-normal permeability distribution), limitations (may be inaccurate for non-log-normal distributions), and detailed return structure. It also warns about common mistakes like invalid coefficient ranges.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (SYNTHETIC FLOW PROFILE, Parameters, Lorenz Curve Generation, etc.) and front-loads the core purpose. While comprehensive, some sections like 'Applications' with 6 bullet points could be more concise. However, every sentence adds value and there's no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (generating mathematical curves with specific behavior), no annotations, and 0% schema coverage, the description provides exceptional completeness. It covers purpose, usage, parameters, behavior, applications, returns, common mistakes, examples, and limitations. The existence of an output schema means the description doesn't need to fully document return values, but it still provides a helpful summary of the return dictionary structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (schema only has 'value' with type/number and min/max constraints), the description fully compensates by providing rich parameter semantics. It explains the parameter is a 'Target Lorenz coefficient (0-1)', provides typical range (0.2-0.7), gives an example (0.5), explains what different values represent (L=0 perfect conformance, L>0 flow imbalance), and shows example usage. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate flow fractions from Lorenz coefficient' and 'Creates idealized flow distribution matching a specified Lorenz coefficient.' It distinguishes from sibling 'lorenz_from_flow_fractions' by specifying this tool generates synthetic data while that tool works with measured data. The verb 'generate' and resource 'flow fractions' are specific and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It states: 'For actual reservoirs, use `lorenz_from_flow_fractions` with measured production data' and explains this tool is for generating idealized curves. The 'Applications' section further clarifies appropriate use cases like reservoir simulation, waterflood prediction, and sensitivity analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It details behavioral traits: the formula used (Cg = (1/Z) × (∂Z/∂P) - (1/P)), how compressibility decreases with pressure, typical ranges (50-500 × 10⁻⁶ 1/psi), ideal gas behavior at low pressure, and the return format (dictionary with value, method, units, inputs).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Compressibility Behavior, Formula, Returns, Common Mistakes, Example Usage, Note) and front-loads the purpose. While comprehensive, it's appropriately sized for a complex tool, though slightly verbose; every sentence adds value, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, no annotations, and an output schema (which the description aligns with by detailing returns), the description is highly complete. It covers purpose, usage, parameters, behavior, formula, returns, common mistakes, and examples, leaving no gaps for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description fully compensates. It provides detailed semantics for all 7 parameters: purpose (e.g., 'Gas specific gravity'), valid ranges, typical values, examples, optional/default status, and for 'zmethod', it lists options and recommends 'DAK'. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates gas compressibility (Cg), specifying it's a critical PVT property that measures gas volume change with pressure. It distinguishes from sibling tools like 'oil_compressibility' by explicitly contrasting gas vs. oil compressibility ranges (100-1000 × 10⁻⁶ vs 5-50 × 10⁻⁶ 1/psi).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('essential for material balance calculations, pressure transient analysis, and reserve estimation') and when not to use it ('confusing gas compressibility with oil compressibility'). It also lists common mistakes to avoid, effectively guiding usage versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it's a calculation tool (non-destructive, read-only implied), explains effects of parameters (e.g., H2S increases Tc/Pc), provides typical ranges and units, and details return structure. It also notes dependencies (used by gas_z_factor) and accuracy considerations (non-hydrocarbon effects).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (Parameters, Pseudo-Critical Properties, Method Selection, etc.), but slightly verbose (e.g., repeating method details). Every sentence adds value (e.g., explaining non-hydrocarbon effects), though it could be more front-loaded; the core purpose is stated early, but some details are deep in the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and an output schema (which the description aligns with by detailing returns), the description is highly complete: it covers purpose, usage, parameters, behavior, outputs, examples, and common pitfalls. It provides all necessary context for a calculation tool with multiple inputs and specific domain requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates fully: it explains each parameter's purpose (e.g., sg for gas specific gravity), valid ranges, typical values, examples, and impacts on results (e.g., high H2S significantly affects Tc/Pc). It also details method options with recommendations, adding meaning beyond basic schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates pseudo-critical temperature and pressure for gas mixtures, specifying it's for real gases and required for Z-factor calculations. It distinguishes from siblings by focusing on gas properties (unlike oil or brine tools) and explicitly mentions it's used internally by gas_z_factor, avoiding overlap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidelines are provided: use for Z-factor calculations and gas property correlations, with method recommendations (PMC preferred, SUT for compatibility, BUR for specific apps). It warns against common mistakes like not accounting for non-hydrocarbons or using wrong gas gravity, and notes when to use alternatives (e.g., for pure components vs mixtures).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: it uses an 'iterative Newton-Raphson method' to solve for pressure, returns a dictionary with specific keys (value, method, units, inputs), and includes details on convergence ('Converges rapidly for well-posed problems'), error handling (e.g., parameter validity ranges), and consistency requirements (e.g., using the same Z-factor method throughout analysis).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections like Parameters, P/Z Method Applications, Material Balance Principle, Solution Method, Returns, Common Mistakes, and Example Usage, making it easy to navigate. However, it is quite lengthy with extensive theoretical background (e.g., material balance equations), which, while informative, could be trimmed for more front-loaded conciseness without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is highly complete for this complex tool with no annotations and an output schema. It covers purpose, usage, parameters, behavior, return values, examples, and common pitfalls. Given the output schema exists (as per context signals), the description appropriately explains the return structure without redundancy, ensuring the agent has all necessary context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given the schema description coverage is 0% (as indicated by context signals), the description fully compensates by providing detailed parameter semantics. It lists all parameters (pz, sg, degf, h2s, co2, n2, zmethod) with clear explanations, valid ranges, typical values, examples, and optional/default settings, adding significant meaning beyond the bare schema properties and required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate pressure from P/Z value' and 'Solves for pressure given a P/Z (pressure/Z-factor) value.' It specifically distinguishes this as a 'MATERIAL BALANCE TOOL' for gas material balance analysis, differentiating it from sibling tools like gas_z_factor or gas_critical_properties by focusing on iterative pressure calculation from P/Z inputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Essential for gas material balance analysis where P/Z vs cumulative production is plotted.' It details applications such as volumetric gas reserves, aquifer influx detection, drive mechanism identification, and production forecasting, and warns against common mistakes like using separator temperature or wrong Z-factor methods, offering clear context for proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and excels. It explains the pseudopressure method, mathematical formulation, accuracy advantages over simplified Darcy's law, handling of pressure-dependent properties, and detailed return structure. It also covers important behavioral aspects like unit requirements (psia vs psig), typical value ranges, and error prevention through the 'Common Mistakes' section.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Flow Geometry, Pseudopressure Method, etc.) but is quite lengthy. While every section adds value, some information could potentially be more condensed. The front-loaded purpose statement is excellent, but the overall length pushes it slightly below perfect conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, specialized petroleum engineering domain), no annotations, and the presence of an output schema, the description is exceptionally complete. It covers purpose, usage context, mathematical foundation, parameter details, return values, common pitfalls, and example usage. The output schema existence means the description doesn't need to exhaustively document return structure, yet it still provides helpful context about the return dictionary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage (parameters are nested under 'request'), the description provides comprehensive parameter documentation. Each parameter gets detailed explanations including physical meaning, units, validity ranges, typical values, examples, and special considerations (e.g., 'psd' can be scalar or array). This fully compensates for the schema's lack of descriptions and adds substantial value beyond basic parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Calculate gas production rate for linear flow' with specific context about horizontal wells and real gas pseudopressure formulation. It clearly distinguishes from sibling tools like 'gas_rate_radial' by emphasizing linear flow geometry and contrasting with radial flow in the 'Linear vs Radial Flow' section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It specifies that linear flow occurs in horizontal wells, hydraulically fractured vertical wells, channelized gas reservoirs, and edge water drive systems, and contrasts linear flow with radial flow (which would use 'gas_rate_radial'). The 'Common Mistakes' section further reinforces proper usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: it uses a 'Newton-Raphson iterative solver,' is a 'standalone fixed implementation' to avoid bugs, returns a dictionary with specific keys, and details sensitivity to inputs like temperature. It also covers constraints (e.g., gradient must be > 0) and typical use cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections like 'Parameters,' 'Gradient Principle,' and 'Applications,' making it easy to navigate. It is appropriately sized for a complex tool, but some sections (e.g., 'Gradient Principle' formula) are detailed and could be slightly condensed without losing clarity. Overall, it's efficient and front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity, no annotations, and an output schema (implied by 'Returns' section), the description is highly complete. It covers purpose, usage, parameters, behavioral details, applications, examples, and common mistakes. The output schema is described in the 'Returns' section, ensuring the agent understands the response format without redundancy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It provides detailed parameter semantics: 'gradient' as pressure gradient in psi/ft with typical ranges, 'degf' as temperature in °F with valid ranges, 'p' as pressure in psia, and 'method' as Z-factor method with options and recommendations. This adds significant meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate gas specific gravity from pressure gradient.' It specifies the verb 'calculate' and the resource 'gas specific gravity' from 'pressure gradient,' and distinguishes it from sibling tools like 'gas_sg_from_composition' by focusing on gradient-based calculation rather than compositional analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Essential for formation fluid identification and gas property verification when only gradient data is available.' It also provides context in the 'Applications' section, such as 'Formation Fluid ID' and 'Gas Density Verification,' and warns against common mistakes like using wrong units or temperatures, guiding proper usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It explains the correlation method used, typical viscosity ranges (0.01-0.05 cP), how viscosity changes with pressure/temperature, the tool's accuracy advantages over ideal gas assumptions, and detailed return format. It also covers practical considerations like unit requirements and component accounting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Viscosity Behavior, Correlation, Returns, Common Mistakes, Example) but is quite lengthy. While every section adds value, some information could be more condensed. The front-loading is good with purpose and criticality stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex calculation tool with 7 parameters, 0% schema coverage, and no annotations, the description provides exceptional completeness. It covers purpose, usage, parameters, behavior, methodology, return format, common mistakes, and examples. The output schema exists but the description still usefully explains the return structure and units.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides comprehensive parameter documentation: valid ranges, typical values, examples, optional/default values, and practical explanations for each parameter. It adds significant meaning beyond the bare schema, including the 'zmethod' options with recommendation and clarification that 'p' can be scalar or array.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates gas viscosity using the Lee, Gonzalez & Eakin correlation, specifying it's for natural gas at reservoir conditions. It distinguishes itself from sibling tools like 'oil_viscosity' by explicitly contrasting gas vs. oil viscosity behavior and mentioning it's a critical PVT property for flow rates and pressure drops.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs. alternatives: it specifies it's for gas (not oil), at reservoir conditions (not separator conditions), and uses real gas behavior (not ideal gas). It also warns against common mistakes like using wrong temperature units or pressure types, which implicitly defines when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and excels by disclosing behavioral traits: it explains the correlation method (McCain 1990), valid ranges, typical outputs (5-200 lb/MMSCF), critical applications, common mistakes, and return structure. It also details how water content behaves with pressure and temperature changes, providing comprehensive operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Water Content Behavior, Applications, Returns, etc.), but it is lengthy. Every sentence adds value, such as explaining hydrate formation and common mistakes, but it could be more front-loaded; the core purpose is stated early, but some details might be condensed for better conciseness without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (engineering calculation with critical safety implications), no annotations, and an output schema that documents return values, the description is complete. It covers purpose, usage, parameters, behavior, applications, returns, and common pitfalls, providing all necessary context for an AI agent to invoke the tool correctly and understand its significance in gas processing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It adds extensive meaning beyond the bare schema: defines each parameter (sg, degf, p) with units, valid ranges, typical values, examples, and behavioral effects (e.g., water content decreases with increasing pressure). This thoroughly documents all parameters, making the tool's inputs clear and actionable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific purpose: 'Calculate water content of natural gas' with the verb 'calculate' and resource 'water content of natural gas'. It distinguishes from siblings by focusing on water content calculation specifically for hydrate prevention and dehydration design, unlike other tools that handle properties like compressibility, density, or viscosity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided on when to use this tool: 'Essential for hydrate prevention, dehydration unit design, and pipeline operation.' It also specifies alternatives implicitly by mentioning related concepts (e.g., water dew point) and contexts where it's critical, such as pipeline operation vs. LNG processes, helping differentiate from sibling tools that might calculate other gas properties.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: 'Z-Factor Behavior' section describes how Z varies with pressure, 'Non-Hydrocarbon Effects' explains how inputs affect results, 'Returns' details the output structure, and 'Common Mistakes' lists critical usage pitfalls. This covers behavioral aspects like input validation, output format, and error-prone scenarios.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Z-Factor Behavior, Method Selection, etc.), making it easy to navigate. However, it is quite lengthy (over 500 words), which may be excessive for some contexts. Every sentence adds value, but it could be more front-loaded by moving the 'Returns' section earlier. The efficiency is high, but the overall size slightly impacts conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameters, no annotations, 0% schema coverage), the description is exceptionally complete. It covers purpose, usage, parameters, behavior, method selection, output format, common mistakes, and examples. The presence of an output schema (implied by 'Has output schema: true') is complemented by the detailed 'Returns' section. No gaps remain for effective tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It provides extensive parameter semantics: each parameter is documented with purpose, valid ranges, typical values, examples, and effects on calculation (e.g., 'H2S and CO2 increase Z-factor'). The 'Parameters' section adds meaning beyond basic schema types, including practical guidance like 'must be absolute' for pressure and 'separator gas gravity' for sg.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Calculate gas compressibility factor (Z-factor).' It distinguishes this tool from siblings by specifying it's for gas (not oil/brine) and focuses on a specific PVT property, unlike general calculation tools in the list. The opening section emphasizes its critical role in gas reservoir calculations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs. alternatives. It states: 'Essential for all gas reservoir calculations including material balance, reserve estimation, and flow calculations,' and includes a 'Method Selection' section with recommendations (e.g., 'DAK recommended,' 'Use for: All applications, high accuracy requirements'). It also warns about limitations: 'For sour gas (H2S > 5%), use Wichert-Aziz correction (not included here).'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It details the calculation algorithm step-by-step, provides interpretation guidelines (L < 0.3: high conformance, etc.), lists common mistakes with specific validation requirements (sum to 1.0, length match), and explains what the tool returns. This gives the agent comprehensive behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Input Data Sources, Calculation, Interpretation, Applications, Returns, Common Mistakes, Example Usage, Note). While comprehensive, some sections like 'Applications' and 'Common Mistakes' are quite detailed, making it longer than minimal. However, every sentence adds value, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema description coverage, but with an output schema, the description provides exceptional completeness. It covers purpose, usage, algorithm, interpretation, applications, parameters, returns (though output schema exists, it adds interpretation guidance), common mistakes, and examples. This fully compensates for the lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides extensive parameter semantics. It defines flow_frac and perm_frac with clear units (0-1 fractions), requirements (must sum to 1.0, length match), examples, and explains their physical meaning (flow fractions from production allocation, permeability-thickness fractions). It also clarifies common pitfalls like using weight fractions instead of flow fractions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates Lorenz coefficient from flow and permeability fractions, specifying it's for analyzing production data and quantifying vertical conformance. It distinguishes from sibling 'flow_fractions_from_lorenz' by being the inverse operation, and from 'beta_to_lorenz' and 'lorenz_to_beta' by using different input types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('most direct way to calculate Lorenz from actual production data') and provides extensive context through 'Input Data Sources' (PLT, tracer tests, etc.) and 'Applications' sections. It also implicitly contrasts with siblings by focusing on measured production allocation rather than theoretical distributions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: it converts between two heterogeneity measures, details the mathematical and statistical basis (log-normal distribution), includes typical ranges and interpretations, notes assumptions and limitations ('conversion is approximate'), and describes the return structure. This covers operational context, accuracy constraints, and output format comprehensively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (e.g., Parameters, Applications, Returns) and uses bullet points for readability. However, it is lengthy with detailed explanations (e.g., mathematical definitions, typical ranges) that, while informative, could be condensed for brevity. Every sentence adds value, but it borders on being overly verbose for a tool description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the conversion (involving statistical assumptions and reservoir engineering context), no annotations, and an output schema (implied by the Returns section), the description is highly complete. It covers purpose, usage, parameters, behavioral traits, limitations, examples, and return values, leaving no gaps for effective tool invocation by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It adds extensive meaning beyond the schema: defines the 'value' parameter as a Lorenz coefficient (float, 0-1), explains its typical range (0.2-0.7), provides an example (0.5), and details its derivation and interpretation (e.g., based on cumulative flow vs. storage, geometric meaning). This fully documents the parameter's semantics and usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: 'Convert Lorenz coefficient to Dykstra-Parsons beta parameter.' This is a specific verb ('Convert') with clear resources (Lorenz coefficient to Dykstra-Parsons beta), and it distinguishes from its sibling 'beta_to_lorenz' by specifying the direction of conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Essential for comparing reservoirs using different heterogeneity metrics and for literature data conversion.' It also lists specific applications (e.g., waterflood sweep efficiency, reservoir characterization) and mentions an alternative ('beta_to_lorenz' as the inverse conversion), with clear context on its role in heterogeneity quantification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It comprehensively describes the tool's behavior: it explains the conversion formula, valid input ranges (0.1-1.5), typical values (0.8-1.0), that inputs can be scalar or array, the return format (dictionary with specific fields), and includes practical context like API gravity ranges for oil classification. This goes well beyond basic parameter documentation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (UNIT CONVERSION TOOL, Parameters, Conversion Formula, etc.) and front-loads the core purpose. While comprehensive, some sections like 'Common Mistakes' and detailed API ranges could be considered slightly verbose, though they add value. Overall, it's efficiently organized with minimal wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (unit conversion with formula and industry context), no annotations, and an output schema that exists, the description is remarkably complete. It explains the conversion physics, provides the formula, input constraints, return format, usage context, common pitfalls, and example usage. The output schema handles return structure documentation, allowing the description to focus on semantic context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must fully compensate. It provides extensive parameter semantics: defines 'sg' as oil specific gravity with water=1.0, specifies it can be float or list, provides valid range (0.1-1.5), typical range (0.8-1.0), and gives examples (0.85 or [0.80, 0.85, 0.90]). This adds substantial meaning beyond what the bare schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Convert oil specific gravity to API gravity.' It specifies the exact transformation (conversion), the input (oil specific gravity), and the output (API gravity). It distinguishes itself from siblings by focusing on this specific conversion, unlike tools like 'oil_sg_from_api' which performs the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this conversion when you have specific gravity but need API gravity for correlations or reporting.' It also provides 'Common Mistakes' section that implicitly guides when not to use it (e.g., for gas specific gravity or density instead of oil specific gravity), helping differentiate from sibling tools like 'gas_sg_from_composition' or 'oil_density'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: it explains the calculation's significance, lists parameter valid ranges and typical values, details method options with recommendations, describes the return dictionary structure, and warns of common errors. This covers all necessary aspects like input validation and output format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Method Selection, Returns, etc.), but it is somewhat lengthy. Every sentence adds value (e.g., the 'Common Mistakes' and 'Note' sections are highly informative), though it could be more front-loaded by moving key usage guidelines earlier.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameters with specific ranges, method choices) and no annotations, the description is complete: it explains the tool's purpose, parameters, methods, return values (though an output schema exists, it still clarifies the dictionary structure), usage context, and common pitfalls. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage (parameters are nested under 'request' with minimal schema descriptions), the description comprehensively documents all parameters: it defines each with units, valid ranges, typical values, examples, and practical notes (e.g., distinguishing rsb from separator GOR). This fully compensates for the schema's lack of detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates oil bubble point pressure (Pb), specifying it's a critical PVT property with a precise definition. It distinguishes itself from siblings like 'oil_rs_at_bubble_point' or 'oil_solution_gor' by focusing on pressure calculation rather than gas-oil ratio or other properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use each correlation method (VALMC for wide applicability, STAN for standard conditions, VELAR for regional studies) and includes a 'Common Mistakes' section warning against misusing parameters like temperature units or GOR values. The note on Pb vs. reservoir pressure clarifies practical application contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it explains compressibility trends (p < pb, p = pb, p > pb), typical ranges, criticality of pb, and output structure. It adds context on numerical scale (micro-1/psi) and method used ('McCain'), which aren't in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections (CRITICAL PVT PROPERTY, Parameters, Compressibility Behavior, etc.), but slightly verbose. Every sentence adds value (e.g., typical ranges, common mistakes), though some redundancy exists (e.g., repeating pb importance). It's front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and an output schema, the description is highly complete: it covers purpose, usage, parameters, behavior, returns, examples, and pitfalls. The output schema handles return values, so the description appropriately focuses on context and semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates fully: it details each parameter (p, api, degf, pb, sg_g, rs, rsb) with meanings, valid ranges, examples, and interactions (e.g., rs matching p shape, rsb required if pb provided). This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates oil compressibility (Co), specifying it's a critical PVT property that measures volume change with pressure. It distinguishes from siblings like gas_compressibility by focusing on oil and mentions specific applications (material balance, pressure transient analysis).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: it states when to use (essential for material balance calculations, etc.), distinguishes from gas compressibility, and warns against common mistakes like using wrong pressure types. It also references sibling tools (e.g., oil_bubble_point for pb) implicitly through parameter context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits. It explains the calculation method, typical ranges, return format, and critical notes like parameter matching requirements. It adds context on prerequisites (calculating Bo first) and validation rules (e.g., p > 0), which are not in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Calculation Method, Returns, etc.), but it is lengthy. Every sentence earns its place by providing essential information, though it could be more front-loaded; the critical purpose is stated early, but detailed sections follow, which is acceptable given the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no annotations, 0% schema coverage, but with an output schema), the description is highly complete. It covers purpose, usage, parameters, method, returns, examples, and common mistakes. The output schema exists, so the description appropriately focuses on input semantics and behavioral context without needing to explain return values in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description compensates fully. Each parameter is detailed with meaning, units, valid ranges, examples, and constraints (e.g., 'Must match p shape'). It explains relationships between parameters (e.g., rs and bo must match p) and provides the underlying formula, adding significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates oil density at reservoir conditions using a mass balance approach, specifying it's for PVT properties. It distinguishes from siblings like 'gas_density' and 'oil_formation_volume_factor' by focusing specifically on oil density calculation, not gas properties or volume factors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Always calculate Bo first using oil_formation_volume_factor tool, then use matching rs and bo values.' It also lists common mistakes to avoid, such as using stock tank density instead of reservoir density, which helps differentiate when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It explains critical behavioral aspects: pressure behavior (how Bo changes with p relative to pb), method differences (accuracy ranges), return format (dictionary structure), common mistakes (e.g., unit confusion), and accuracy implications (providing rs improves results). This goes far beyond basic parameter documentation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Pressure Behavior, Method Selection, Returns, Common Mistakes, Example Usage) and uses bold headings effectively. While lengthy, every sentence adds value—no fluff. It could be slightly more front-loaded by moving the example earlier, but overall it's efficiently organized for a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, nuanced physics), no annotations, but with an output schema, the description is exceptionally complete. It covers purpose, usage, parameters, behavior, method selection, returns, common pitfalls, and includes a detailed example. The output schema handles return structure, allowing the description to focus on conceptual and practical aspects without redundancy.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description comprehensively documents all 8 parameters. It adds essential semantics: validity ranges, examples, default values, shape matching requirements (rs must match p), and practical guidance (e.g., 'Required for accurate calculation' for pb). This fully compensates for the schema gap and provides rich context for each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate oil formation volume factor (Bo)' and elaborates on its definition and importance. It distinguishes from siblings like gas_formation_volume_factor by specifying it's for oil, not gas, and from oil_density or oil_viscosity by focusing on volume ratio calculations for reservoir engineering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives. It distinguishes from gas FVF (Bg) in 'Common Mistakes', mentions method selection (MCAIN vs. STAN), and advises on providing rs for pressures below bubble point. It also implicitly positions it among sibling PVT tools by specifying its role in material balance and production forecasting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and excels. It discloses that the tool automatically calculates PVT properties internally, explains the Darcy's law formula used, describes the return format in detail, and warns about common implementation errors like pressure unit requirements and geometry misunderstandings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Flow Geometry, Formula, Returns, Common Mistakes, Example) but is quite lengthy. While every section adds value, some information could be more condensed. It's front-loaded with the core purpose, but the detailed parameter explanations make it longer than ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex tool with 11 parameters, no annotations, and 0% schema coverage, the description is exceptionally complete. It covers purpose, usage context, mathematical basis, parameter details, return format, common pitfalls, and includes a working example. The output schema exists, so the description appropriately focuses on behavioral context rather than repeating return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides comprehensive parameter documentation. Each parameter gets a clear explanation with units, validity ranges, typical values, examples, and contextual notes (e.g., 'If pi < pb, reservoir is saturated'). This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool calculates oil production rate for linear flow using Darcy's law, specifying it's for horizontal wells or wells with linear flow geometry. It distinguishes from sibling tools like 'oil_rate_radial' by explicitly contrasting linear vs radial flow in a dedicated section.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool (horizontal wells, hydraulically fractured wells, channelized reservoirs, edge water drive systems) and when not to use it (radial flow for vertical wells). It includes a 'Common Mistakes' section that helps avoid misuse, such as confusing linear with radial flow or using wrong pressure units.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and delivers comprehensive behavioral information. It discloses that the tool automatically calculates PVT properties, explains the mathematical formula used, describes return format, provides example usage, and details flow regime behaviors. No contradictions exist since annotations are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Flow Regime, Formula, Returns, Common Mistakes, Example Usage, Note) but could be more concise. Some information is repeated (e.g., Vogel usage mentioned multiple times), and the length is substantial though justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (13 parameters, engineering calculations) and absence of annotations, the description provides complete context. It covers purpose, usage, parameters, behavior, formula, return format, common mistakes, and examples. The output schema exists, so return values needn't be fully explained in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description provides extensive parameter semantics beyond what the schema offers. Each parameter gets detailed explanations including physical meaning, units, valid ranges, typical values, examples, and practical implications (e.g., 'If pi < pb, reservoir is saturated'). This fully compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool calculates oil production rate for vertical wells with radial flow geometry using Darcy's law, distinguishing it from sibling tools like 'oil_rate_linear' and specifying it's for 'vertical well' scenarios. It clearly identifies the verb ('calculate'), resource ('oil production rate'), and specific application context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus alternatives, including flow regime conditions (undersaturated vs saturated reservoirs), when to apply the Vogel IPR model, and common mistakes to avoid. It distinguishes usage from other tools by specifying radial flow geometry for vertical wells.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: the conversion formula, valid input ranges (0-100), typical ranges (20-50), support for scalar or array inputs, return structure (dictionary with value, method, units, inputs), and specific gravity ranges with oil classifications. It also covers common mistakes and the inverse relationship between API and SG.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (UNIT CONVERSION TOOL, Parameters, Conversion Formula, etc.) and front-loads the core purpose. However, it includes some redundant information (e.g., repeating the inverse relationship in multiple places) and the 'Common Mistakes' section, while helpful, adds length. Every sentence earns its place, but minor trimming could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (unit conversion with mathematical formula), no annotations, and 0% schema coverage, the description provides complete context. It explains the conversion physics, provides the formula, input constraints, return format, usage examples, and common pitfalls. The presence of an output schema reduces the need to explain return values, but the description still thoroughly documents the tool's behavior and context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage (the schema only says 'API gravity (degrees) - scalar or array'), the description fully compensates by providing rich parameter semantics. It explains the 'api' parameter as 'Oil API gravity in degrees,' specifies valid range (0-100), typical range (20-50), shows examples (35.0 or [30, 35, 40]), and clarifies it can be scalar or array. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Convert API gravity to oil specific gravity.' It specifies the exact conversion (API degrees to specific gravity dimensionless) and distinguishes it from sibling tools like 'oil_api_from_sg' (inverse conversion) and 'oil_sg_from_jacoby' (different method). The description explicitly mentions this is for oil, not gas, further differentiating from gas-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Essential for calculations requiring specific gravity' and 'Use this conversion when needed.' It also warns against common mistakes like using gas API gravity instead of oil, and notes that 'Most PVT correlations use API gravity directly, but some require specific gravity.' This gives clear context for when this conversion is necessary versus when to use API gravity directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the tool's behavior: how Rs changes with pressure (increases up to bubble point then constant), method options and their characteristics, return format, accuracy considerations, and critical implementation details like pressure units and parameter dependencies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (Parameters, Pressure Behavior, Method Selection, Returns, Common Mistakes, Example Usage, Note) but is quite lengthy. While every section adds value, some redundancy exists (e.g., parameter details are repeated in example). It could be more concise while maintaining clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is exceptionally complete for this complex tool. It covers purpose, parameters, behavior, method selection, return format, common pitfalls, and usage examples. Despite having an output schema, the description usefully explains the return structure. No significant gaps exist given the tool's complexity and lack of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema description coverage, the description fully compensates by providing detailed parameter documentation. Each parameter is explained with purpose, valid ranges, examples, default values, and practical guidance. The description adds significant meaning beyond what the bare schema provides, including parameter interactions and calculation implications.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Calculate solution gas-oil ratio (Rs) at specified pressure.' It specifies the verb ('calculate'), resource ('solution gas-oil ratio'), and scope ('at specified pressure'), distinguishing it from sibling tools like 'oil_rs_at_bubble_point' which focuses only on bubble point conditions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool, including method selection recommendations (e.g., 'VELAR... Use for most cases'), pressure behavior rules ('p < pb' vs 'p ≥ pb'), and common mistakes to avoid. It also distinguishes usage from related tools by explaining the pressure-dependent behavior of Rs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits. It explains the solution method (Newton-Raphson with bounds checking), convergence behavior (3-10 iterations), assumptions (ideal mixing), and dependencies (K-values from EOS or correlations). It also details the return structure and includes interpretation guidance for phase behavior (e.g., β=0 means all liquid).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (e.g., Parameters, Rachford-Rice Equation, Applications), but it is lengthy with some redundancy (e.g., repeating parameter details in multiple sections). However, every sentence adds value, such as explaining phase behavior or common mistakes, making it efficient despite its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (solving an equation with iterative methods), no annotations, and an output schema present, the description is highly complete. It covers purpose, usage, parameters, equation details, solution method, applications, returns, common mistakes, and example usage, providing all necessary context for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It provides detailed semantics for both parameters: zis as 'Overall mole fractions of components (0-1)' with examples and constraints, and Kis as 'Equilibrium ratios (K-values) for components' with definitions and behavior explanations (e.g., K>1 for light components). This adds significant value beyond the minimal schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Solve Rachford-Rice equation for vapor-liquid equilibrium.' It specifies the verb ('solve') and resource ('Rachford-Rice equation'), and distinguishes it from siblings by focusing on flash calculations for compositional analysis, unlike tools for gas properties or oil rates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Essential for compositional analysis, separator design, and phase behavior calculations.' It lists specific applications (e.g., gas-oil separator design, phase envelope calculations) and includes a 'Common Mistakes' section with warnings about when not to use it (e.g., mole fractions not summing to 1.0, K-values at wrong conditions).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

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

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

Card Badge

Copy to your README.md:

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

Score Badge

Copy to your README.md:

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

Latest Blog Posts

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

MCP directory API

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

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gabrielserrao/pyrestoolbox-mcp'

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