Skip to main content
Glama
gabrielserrao

pyResToolbox MCP Server

by gabrielserrao
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

generate_black_oil_table

Generate comprehensive black oil PVT tables for reservoir simulation and analysis, calculating key properties like solution gas-oil ratio, formation volume factor, and viscosity across pressure ranges.

Instructions

Generate comprehensive black oil PVT table.

COMPREHENSIVE PVT TABLE GENERATOR - Creates complete black oil PVT table with all properties (Rs, Bo, μo, ρo, Co) at pressures from 14.7 psia to specified maximum. This is the most comprehensive PVT tool, generating complete tables for reservoir simulation input or analysis. Optionally exports ECLIPSE-compatible keywords.

Parameters:

  • pi (float, required): Initial reservoir pressure in psia. Must be > 0. Example: 4000.0. Table starts from 14.7 psia and goes up to pmax.

  • api (float, required): Oil API gravity in degrees. Valid: 0-100. Example: 38.0.

  • degf (float, required): Reservoir temperature in °F. Valid: -460 to 1000. Example: 175.0.

  • sg_g (float, required): Gas specific gravity (air=1). Valid: 0-3. Typical: 0.6-1.2. Example: 0.68.

  • pmax (float, optional, default=0.0): Maximum pressure for table in psia. If 0, auto-calculates as pi × 1.5. Must be > pi. Example: 5000.0.

  • pb (float, optional, default=0.0): Bubble point pressure in psia. If 0, will be calculated. Example: 3900.0.

  • rsb (float, optional, default=0.0): Solution GOR at bubble point in scf/stb. If 0, will be calculated. Example: 2300.0.

  • nrows (int, optional, default=50): Number of table rows. Valid: 1-200. More rows = finer resolution. Typical: 20-100. Example: 50.

  • export (bool, optional, default=False): Export ECLIPSE-compatible files. If True, creates PVTO.INC, PVDO.INC, DENSITY.INC files. Example: False.

  • pb_method (str, optional, default="VALMC"): Bubble point method. Options: "STAN", "VALMC", "VELAR". VALMC recommended.

  • rs_method (str, optional, default="VELAR"): Solution GOR method. Options: "VELAR", "STAN", "VALMC". VELAR recommended.

  • bo_method (str, optional, default="MCAIN"): Oil FVF method. Options: "MCAIN", "STAN". MCAIN recommended.

  • uo_method (str, optional, default="BR"): Oil viscosity method. Only "BR" available.

Generated Properties:

  • Rs: Solution gas-oil ratio (scf/stb) - increases with pressure up to pb

  • Bo: Formation volume factor (rb/stb) - peaks at bubble point

  • μo: Oil viscosity (cP) - minimum at bubble point

  • ρo: Oil density (lb/cuft) - calculated from mass balance

  • Co: Oil compressibility (1/psi) - increases near bubble point

Table Structure: Pressure values are logarithmically spaced from 14.7 psia to pmax, with finer spacing near bubble point for accuracy.

ECLIPSE Export: When export=True, generates:

  • PVTO.INC: Pressure-dependent oil properties (for undersaturated oil)

  • PVDO.INC: Dead oil properties (for heavy oils)

  • DENSITY.INC: Oil density table

Returns: Dictionary with:

  • table (list of dicts): PVT table data, each dict contains pressure and all properties

  • summary (dict): Key values (bubble point, rsb, Bob, μob, etc.)

  • columns (list): Column names in table

  • methods (dict): Methods used for each property

  • export_files (dict, optional): File names if export=True

  • inputs (dict): Echo of input parameters

Common Mistakes:

  • Setting pmax too low (should be > pi for complete table)

  • Not providing pb and rsb when known (reduces accuracy)

  • Using wrong correlation methods (use recommended defaults)

  • Too few rows (nrows < 20) causing poor resolution

  • Not understanding table format for simulation input

Example Usage:

{
    "pi": 4000.0,
    "api": 38.0,
    "degf": 175.0,
    "sg_g": 0.68,
    "pmax": 5000.0,
    "pb": 3900.0,
    "rsb": 2300.0,
    "nrows": 50,
    "export": False,
    "pb_method": "VALMC",
    "rs_method": "VELAR",
    "bo_method": "MCAIN",
    "uo_method": "BR"
}

Result: Complete PVT table with 50 rows covering 14.7-5000 psia with all properties.

Note: This is the most comprehensive PVT tool. Use for complete reservoir analysis or simulation input preparation. Always provide pb and rsb when available for best accuracy. For simulation, set export=True to generate ECLIPSE keywords.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
requestYes

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Tool Definition Quality

A4.7/5.0
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.

Install Server

Other Tools

Latest Blog Posts

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