Digital Gemology: gem identification and gemstone properties

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

Annotations already declare readOnly/ idempotent/ closed-world, so the safety profile is covered; the description adds value beyond them by describing what the response contains (line/band positions in nm, causal attribution such as Cr3+ in ruby, visual appearance) and naming its source. It stops short of stating response structure or whether the list can be empty for a given stone.

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?

One front-loaded sentence that describes the output first and attributes the source last; every clause (lines, positions, causes, appearance) carries information.

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, the description usefully characterizes the return content, which is the main thing an agent needs for this simple single-enum lookup. Minor gap: nothing about response shape (list of entries) or behavior for a stone with no diagnostic lines.

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 100% and the single parameter is an enum with a per-value description, so the schema does all the work. The description mentions 'one gemstone' but adds no constraint or semantics beyond what the enum already provides; baseline 3 applies.

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 resource and scope: the absorption spectrum ('each absorption line and band') a hand spectroscope would show for one gemstone, with positions in nm and causes. That is specific enough to distinguish it from gem_properties (property lookup) and identify_gem (identification), even without naming them.

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 by the content ('what a hand spectroscope shows'), which suggests a reference-lookup task, but the description never says when to pick this over gem_properties or identify_gem, nor states any prerequisites or exclusions.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered without prose. The description adds that the result is a set of named tests with the tool that shows each one, but says nothing about error cases such as passing the same gemstone twice.

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?

One sentence, front-loaded with the resource and purpose, then the property list. The parenthetical glosses ('doubling of back facets, polariscope', 'fire') aid interpretation, though the sentence is dense enough that a reader must parse carefully.

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, the description compensates by enumerating the compared properties, so the agent knows what a call returns. For a two-parameter, closed-world, read-only comparison tool this is close to sufficient; only duplicate-input behavior is unaddressed.

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 100% with enumerated slugs for both parameters, so the schema carries the semantics. The phrase 'two gemstones side by side' is consistent with gemstone_a/gemstone_b, but the description adds no format or edge-case guidance beyond what the enum already states.

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 names the resource (two gemstones) and the operation (a side-by-side comparison yielding discriminating tests), and enumerates the exact properties compared: refractive index, birefringence, specific gravity, dispersion, hardness, pleochroism, spectrum. That is specific enough to distinguish it from identify_gem and gem_properties, though it never names a sibling 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 closing sentence gives a concrete triggering question ('how do I tell diamond from moissanite?'), which tells the agent exactly which user intents should route here. It stops short of stating when NOT to use it (e.g. a single unknown stone, which would be identify_gem).

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered by structured data. The description's contribution is the content inventory (which measurements come back), which is useful given there is no output schema, but it says nothing about data source, completeness, or units.

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?

It is a single sentence, front-loaded with the resource, which is efficient in structure. But it is a densely packed run-on list of instruments and measurements that is tiring to parse and could be broken into a purpose clause plus a returned-fields list.

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, the description takes on the job of telling the agent what comes back, and it does that thoroughly — refractive index, birefringence, dispersion, SG, hardness, crystal system, instrument readings, pleochroism and spectrum lines. Grounding details such as units or whether values are ranges are missing, but the essential content inventory is there.

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% and the single parameter is a fully enumerated slug, so the schema carries the semantics by itself. The description only indirectly signals a single-stone scope ('one gemstone') and adds no detail about accepted values or format.

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 names the resource (a single gemstone) and enumerates the measured properties, so the general intent of a property lookup is clear. However, it never states a verb ('returns', 'looks up') and does nothing to separate it from siblings like absorption_spectrum, which its mention of 'lines and bands a hand spectroscope shows' actively overlaps with.

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?

There is no when-to-use guidance at all: nothing tells the agent to pick this over identify_gem (unknown stone) or compare_gemstones (multiple stones), even though the one-gemstone scope would make that distinction trivial to state. Usage is only implied by the phrase 'about one gemstone'.

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?

Annotations already establish that this is a safe, read-only, idempotent, closed-world lookup, so the bar is lower. The description adds real behavioral value beyond that: it returns a ranked list, it flags which readings fit and which do not, and it handles the over-the-limit refractometer case.

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 sentences, front-loaded with the action, then the input menu, then the critical scope caveat. No filler and no repetition of the title or annotations.

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 7-parameter, all-optional, no-output-schema tool, the description covers the input space and describes the shape of the result (ranked stones with fitting/non-fitting readings). A small gap remains: it does not say what happens if no readings are supplied at all, given zero required parameters.

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%, with enum values and examples already documented per parameter, so the schema does the heavy lifting. The description enumerates the same reading types but adds no syntax, ranges, or combination guidance beyond what the 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?

States a specific verb (match/rank) and resource (test readings against seven gemstones), and the sibling context makes the distinction clear: gem_properties looks up data, compare_gemstones compares known stones, this one identifies from raw readings. The scope bound ('seven gemstones Digital Gemology covers') is explicit.

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 'Give any of:' list tells the agent exactly what kinds of input are accepted and that partial data is fine, and the closing caveat ('a lead among seven stones only, not an identification') sets the correct expectation for interpreting results. It doesn't explicitly name when to prefer a sibling tool, so it falls short of a 5.

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