moissanite-tools

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

With no annotations, the description carries the full behavioral burden. It usefully discloses two behavioral facts: the result assumes a round brilliant cut, and density is corrected per stone (with a concrete ~9% error magnitude for diamonds vs moissanite). However, it says nothing about valid carat ranges, rounding, what happens with an unknown stone, or the return shape.

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?

Three short sentences, front-loaded with the output ('Diameter in millimetres') before the assumptions. No filler. The density sentence is densely packed but each clause 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?

For a two-parameter, no-output-schema utility, the description covers the key domain trap (density varies by stone) and the cut assumption, but leaves out the default stone, expected numeric ranges, precision of the returned diameter, and any failure behavior — modest gaps for an otherwise simple converter.

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 coverage is 50%: 'carat' is self-documented ('Carat weight, e.g. 1.0') while 'stone' has only an enum and default. The description adds real semantic value by explaining why stone matters (density correction, ~9% diamond-vs-moissanite error), but it never states the moissanite default or what density table the non-default stones use, so it only partially compensates.

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?

States a concrete verb-equivalent resource: 'Diameter in millimetres for a given carat weight', which tells the agent exactly what is produced. The qualifier 'Round brilliant cut' narrows the domain. It does not explicitly distinguish itself from the sibling mm_to_carat, so an agent must infer the direction from the name.

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?

Usage is only implied: the conversion direction and the 'density-corrected per stone' note suggest it should be called whenever carat → physical size is needed for a specific material. There is no explicit when-to-use statement, no when-not, and no named alternative such as mm_to_carat for the inverse case.

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

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

No annotations exist, so the description must carry the full behavioral burden. It lists data types but omits return format, whether the operation is read-only, and what happens on invocation, leaving significant 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 a single dense sentence with no wasted words. However, it front-loads content rather than a clear action, reducing immediate clarity.

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?

With no annotations and no output schema, the description should explain what is returned. It omits return structure and the role of the optional grade parameter, leaving this lookup tool under-specified for correct invocation.

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 50%: the grade parameter is documented in the schema, but the scale enum has no description. The description loosely maps to scale values (colour/clarity/optical) and grade examples, but never names or explains the parameters, so it only partially compensates.

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 is a noun phrase naming content (GIA colour/clarity scales, optical constants) but lacks a clear verb like 'returns' or 'looks up', so the action is ambiguous. It distinguishes its content from the sibling converters, but does not state what the tool actually does.

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 when-to-use or when-not guidance is provided. The sibling tools are converters, but the description gives no routing condition or alternatives, leaving usage only implied by the named scales.

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

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

No annotations are provided, so the description carries the full disclosure burden and largely drops it. It is silent on the fact that the result depends on material density via the 'stone' parameter (default moissanite), and says nothing about precision, rounding, or applicability limits of the round-brilliant assumption.

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?

Two terse fragments with zero padding and the key quantity front-loaded, which is efficient. However the brevity slides into under-specification rather than tightness — the cut assumption is stated while the material assumption, which matters more, is omitted.

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?

For a two-parameter conversion with no output schema and no annotations, the description should at minimum explain the material dependency and the nature of the returned value. Neither is present, leaving an agent able to call the tool but not to call it correctly for non-default stones.

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 coverage is only 50%: 'mm' is documented in the schema, but the 'stone' enum (moissanite/diamond/cz) has no description anywhere. The description's 'Round brilliant cut' hints at an assumption but does not explain that the stone choice materially changes the returned carat weight, so it fails to compensate for the coverage gap.

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?

States a specific conversion (diameter in mm → carat weight) and pins the cut ('Round brilliant cut'), which implicitly distinguishes it from the reverse-direction sibling carat_to_mm. It never names that sibling, so it stops short of a 5.

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?

Contains no when-to-use guidance, no prerequisites, and no pointer to carat_to_mm for the inverse operation or to ring_size_convert for related sizing tasks. Usage has to be inferred entirely from the one-line purpose.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the nature of the output (a position description plus trade name), which is real value, but says nothing about read-only safety, how category boundaries are determined, or behavior at boundary/extreme lengths.

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?

A single tight sentence with the concept front-loaded and no filler. It is slightly loose in phrasing ('Where ... sits') but 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?

For a simple two-parameter lookup with no output schema, the description conveys what the agent gets back, which is the main thing. It is not complete enough on unit handling and category boundaries, gaps an agent will hit on real calls.

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 0%, so the description must compensate and does not. It gestures at 'a given length' but never mentions the value/unit parameters, the inches-vs-cm distinction, or the inches default that the agent needs to know before calling.

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 states a specific transformation: given a necklace length, report where it sits on the body plus the trade name (choker, princess, matinee). That is a clear verb+resource, and the unexpected domain (jewelry sizing) is distinguishable from siblings like carat_to_mm and ring_size_convert. It stops short of explicitly naming how it differs from those siblings, but the domain is distinct enough.

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?

Usage is only implied: an agent can infer this is the tool for looking up necklace length categories, but there is no statement of when to prefer it, what inputs are valid, or what out-of-range lengths produce. No exclusions or alternatives are named.

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

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

No annotations exist, so the description carries the full behavioral burden, and for a stateless unit conversion the main traits are that it is a pure deterministic mapping with no side effects - which is implied but never stated. The warning that 'A US 6 is a UK M, not a UK 6' is a genuinely useful anti-error disclosure that adds value beyond the schema.

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?

Two short sentences, zero waste. The core capability is front-loaded and the second sentence earns its place by preempting a common US/UK confusion.

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?

With no output schema and no annotations, the description should describe what comes back (a converted value in the target system, its unit/format, and behavior for unmappable input). It never addresses the return shape or error cases, leaving a gap for a tool whose output the agent must interpret.

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?

At 50% schema coverage, the description compensates by explaining what the enum values mean: mm is specifically the 'inner diameter in mm' and UK/EU are named sizing systems, with the US 6 = UK M example implicitly conveying that UK sizes are letters, not numbers. It adds real meaning beyond the bare enum list, though the 'from' default and value formatting beyond the one example remain unstated.

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?

States a specific verb ('Convert') plus resource ('a ring size') and enumerates the exact unit systems it bridges (US, UK, EU ISO 8653, inner diameter mm). This is clearly distinguishable from siblings like carat_to_mm or necklace_length, which deal with different jewelry attributes.

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?

Usage is implied by the narrow domain - any agent needing a ring-size translation will know to use it - but there is no explicit when/when-not guidance, no mention of the default from='us' behavior at call time, and no alternatives named. The second sentence warns about a mapping gotcha rather than routing the agent.

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

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

With no annotations, the description carries full behavioral burden but discloses only that the tool relates diameter to ear appearance. It does not state that the operation is read-only, deterministic, or what kind of output (string, score, image) is produced, leaving key behavioral traits unstated.

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?

A single, front-loaded sentence with no filler. It is appropriately terse for the tool, though the extreme brevity contributes to the specification gaps noted elsewhere.

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?

For a one-parameter tool with no annotations, no output schema, and 0% schema coverage, the description should explain what the tool returns and when to use it. It does neither, leaving the agent without enough context to invoke confidently.

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 single parameter has 0% schema description coverage, so the description must compensate. It clarifies that the input is the stone diameter (not ear or setting), which is a meaningful addition, but omits any range, precision, or expected units beyond what the name 'diameter_mm' implies.

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 identifies the subject (a round stud, given stone diameter, on the ear) but offers no explicit action verb or output type; 'reads on the ear' is metaphorical, so an agent cannot be certain whether it returns a size comparison, text description, or visual estimate. It is distinct from siblings only by domain implication, not explicit differentiation.

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 when-to-use guidance or alternatives are stated. The phrase 'on the ear' implies an earring context but does not tell the agent when to choose this over ring_size_convert, necklace_length, or the mm/carat converters.

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