petropt/petro-mcp

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

No annotations are provided, so the description carries full burden. It discloses the return value (DLS in specific units) and default behavior for 'course_length_unit', which is helpful. However, it doesn't mention error conditions, precision, or whether the calculation assumes specific survey methods (e.g., minimum curvature vs. tangential), leaving behavioral gaps.

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: a purpose statement, return value clarification, and a parameter list. Every sentence earns its place with no redundant information. It's front-loaded with the core function and appropriately sized for the tool's complexity.

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

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

Given no annotations, 0% schema coverage, but an output schema exists (implied by context signals), the description is mostly complete: it covers purpose, parameters, and return units. However, it lacks details on algorithm assumptions or error handling, which could be relevant for a calculation tool with technical inputs.

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 fully compensates by clearly explaining all 7 parameters: it defines each (e.g., 'md1: Measured depth at station 1') and specifies units (degrees for angles, default 'feet' for course_length_unit). This adds essential meaning beyond the bare schema, making parameters understandable.

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 specific action ('Calculate dogleg severity between two survey stations') and the resource involved (survey stations). It distinguishes from siblings by specifying a unique calculation (dogleg severity) not mentioned in other tool names like 'calculate_wellbore_tortuosity' or 'calculate_vertical_section'.

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

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

The description implies usage when needing to compute dogleg severity from survey data, but provides no explicit guidance on when to use this tool versus alternatives like 'calculate_wellbore_tortuosity' or 'calculate_well_survey'. It mentions the return units but doesn't specify scenarios where this calculation is preferred over other directional drilling metrics.

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