cad_reference_calibration

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. 'Calculates' correctly implies a read-only, computational operation and the fixed reference dimensions add useful context. However, it does not describe output shape/return values, how the fit-clearance mode is triggered, or behavior around optional inputs like customRefMm.

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 only two sentences and front-loads the core conversion first. The second sentence adds the secondary capability without unnecessary detail. Every sentence earns its place.

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?

There is no output schema, so the description should ideally explain what the tool returns; it only says it 'calculates' millimeters. The primary inputs are covered clearly, and the optional measuredPixels list is documented in the schema, but the fit-clearance feature is introduced without enough connection to the input schema.

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?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that pixelSpan is measured from a photo and by supplying concrete reference constants (US Quarter 24.26mm, Penny 19.05mm), which clarify the enum values. It does not repeat schema text, though it could have mapped the fit-clearance mention to specific parameters.

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 first sentence names a specific verb, resource, and conversion type: 'Calculates real-world millimeters from photo pixel measurements using a reference object.' This clearly distinguishes it from the sibling CAD-generation and inspection tools, which do different work. The secondary fit-clearance capability is also stated explicitly.

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 gives a clear usage context: use it when a photo contains a reference object and pixel measurements need to become millimeters, or when 3D printing clearances are needed. It does not explicitly list when not to use it, but the sibling tools are so different that ambiguity is unlikely.

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