petropt/petro-mcp

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

With no annotations provided, the description carries the full burden. It explains the calculation methodology (determining regime, applying API formulas) which adds behavioral context beyond just 'calculate'. However, it doesn't disclose performance characteristics, error handling, or output format details that would be helpful for an agent.

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 well-structured with purpose explanation first, then methodology, then parameter details. Every sentence serves a clear purpose, though the parameter explanations could be slightly more concise. The information is front-loaded with the core calculation purpose.

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 existence of an output schema (which handles return values), the description provides adequate context for this calculation tool. It covers the calculation methodology and parameter meanings. However, it could benefit from more behavioral transparency about what the calculation produces or typical use cases.

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 explaining all 4 parameters in the Args section. It clarifies what each parameter represents (e.g., 'Casing outer diameter', 'Minimum yield strength'), provides units, and explains the optional 'grade' parameter is 'for reference', 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.

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 'collapse pressure rating per API 5C3', distinguishing it from siblings like calculate_burst_pressure or calculate_hydrostatic_pressure. It provides technical specificity about determining regime from D/t ratio and yield strength, making the purpose unambiguous.

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

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

No guidance is provided on when to use this tool versus alternatives like calculate_burst_pressure or other pressure-related calculations. The description mentions the API 5C3 standard but doesn't specify scenarios or prerequisites for its application, leaving usage context implicit.

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