oil_api_from_sg

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.

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.

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.

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.

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.

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.