petropt/petro-mcp

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a calculation tool but doesn't describe what happens with invalid inputs, whether it performs unit validation, error conditions, or typical response format. The description mentions 'just use consistent units' which hints at a requirement but doesn't specify consequences of unit mismatches.

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

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

The description is efficiently structured with formula first, usage note second, and parameter explanations in a clear Args section. Every sentence adds value: the formula defines the calculation, the oil/gas note clarifies scope, and parameter descriptions compensate for the schema's lack of descriptions. No redundant or unnecessary information is included.

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

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

Given the tool's simple calculation nature (2 parameters, no annotations, but has output schema), the description is reasonably complete. It explains the calculation, parameters, and unit consistency requirement. With an output schema presumably handling return values, the description focuses appropriately on the calculation logic. For a straightforward mathematical tool, this provides adequate context despite lacking behavioral details.

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

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

With 0% schema description coverage, the description adds significant value by explaining both parameters: 'ooip_or_ogip: Original oil or gas in place' and 'cumulative_production: Cumulative production (same units).' This clarifies what each parameter represents and their relationship. The 'same units' note provides important context not in the schema. However, it doesn't specify acceptable ranges or typical values.

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

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

The description clearly states the tool calculates recovery factor with the formula RF = Np/N or Gp/G, specifying it works for both oil and gas. It distinguishes itself from siblings by focusing on this specific petroleum engineering calculation rather than trend analysis, decline curves, or other reservoir metrics. However, it doesn't explicitly differentiate from all 70+ siblings beyond the calculation type.

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

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

The description provides minimal usage guidance - only stating 'Works for both oil and gas -- just use consistent units.' It doesn't indicate when to use this versus alternative calculations like EUR, volumetric calculations, or economic metrics. No context about typical scenarios, prerequisites, or comparisons to sibling tools is provided.

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