Ministry of Gems — Gemmology & Gemstones

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating lookup. The description adds useful context about the source (FGAA-reviewed table) and the additional link to The Birthstone Handbook, which explains history and buying guidance. However, it does not disclose potential edge cases (e.g., invalid month handling, return format details) beyond what's in the schema. It adds moderate value without contradicting annotations.

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 concise: two sentences, with the core purpose front-loaded in the first sentence and the input flexibility in the second. Every word contributes to the agent's understanding of what the tool does and how to invoke it. No redundant jargon or filler.

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 simplicity (one parameter, 100% schema coverage, and an output schema), the description covers the essential purpose. It mentions the source (FGAA table) and the linked handbook for further detail. It doesn't explicitly describe the return value structure, but the presence of an output schema likely covers that. The only minor gap is not specifying behavior for invalid months, but that's a minor edge case given the input examples.

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 describes the parameter 'month' with examples like 'September', 'sep', or '9', and it has 100% coverage. The description adds minimal semantic value by saying 'Accepts a month name or number.', which rephrases the schema's examples without providing additional format details (e.g., case-insensitivity, locale). Since the schema already documents the parameter thoroughly, the description's contribution is baseline-level.

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: it provides the modern and traditional birthstones for a month, based on a specific authoritative table (FGAA-reviewed), and includes a link for further information. It explicitly distinguishes its scope (month-based birthstone query) from sibling tools, even though it doesn't mention a sibling by name; the verb 'accepts' and the mention of month input clarify its function.

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 indicates when to use the tool: when you need birthstone information for a month. It does not explicitly exclude use cases or mention alternatives, but the context signals (e.g., sibling tools like 'gem_properties' or 'define_gem_term') imply that this is the dedicated birthstone tool. The lack of explicit 'when not to use' is a minor gap, but the specificity of the purpose provides sufficient guidance.

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, and destructiveHint=false, covering safety and side-effect-free behavior. The description adds value beyond this by specifying the output style: a 'plain verdict' on hardness and a 'note on toughness', plus the side-by-side layout. This informs the agent about the nature of the result without contradicting annotations.

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 two sentences, front-loaded with the core purpose and outcome, and includes a relevant example. No filler or redundancy—every sentence contributes to understanding the tool's function and typical use.

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 has an output schema (not provided in detail) and only two simple parameters, the description covers the essential aspects: what it does, the type of output (verdict, toughness note), and a use case. It does not mention error handling or edge cases (e.g., invalid gem names), but these are not critical for a read-only comparison tool with an output schema. The description is sufficiently complete for an agent to call it correctly.

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. It says 'two gem species' and gives an example with 'sapphire or diamond', implying the parameters are gem names. However, it does not specify acceptable formats (e.g., common names vs. chemical formulas) or any validation requirements. For simple string parameters, this is a minor gap, but the description could be more explicit about what gem_a and gem_b should contain.

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 compares two gem species side-by-side, with a specific verb ('compare') and resource ('gems'), and adds a concrete use-case example ('sapphire or diamond for an everyday ring'). This distinguishes it from sibling tools like gem_properties (likely single-gem lookup) and search_gem_inventory (inventory search).

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 provides a clear use-case example indicating when to use this tool (choosing between two gems for durability). It does not explicitly mention when not to use it or name alternatives, but the example and focus on hardness/toughness imply it is for comparing two specific gem species, not for general property lookups. This is adequate context without explicit 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, and destructiveHint=false, covering the safety profile. The description adds value beyond that by disclosing provenance ('verified by an FGAA-qualified gemmologist') and the exact return shape ('definition, its subject section, and a citable anchor URL'). It does not disclose behavior for unknown terms, but that gap is minor given the presence of an output 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 sentences, zero filler. The first sentence front-loads the action, source, verification status, and returns; the second delivers usage examples. Every clause earns its place and nothing is repeated from the schema 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?

With a single required parameter, 100% schema coverage, an output schema present, and safety annotations covering read-only/idempotent behavior, the description is nearly complete. The only absent detail is behavior on unrecognized terms (e.g., error vs. empty result), which is a small gap for a simple lookup tool. The example list adds enough input guidance that an agent can invoke it correctly without further 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?

Schema coverage is 100% with the term parameter already described as 'The gemmological term to define,' so the baseline is 3. The description exceeds that baseline by supplying five concrete example values (padparadscha, corundum, parti sapphire, unheated, asterism), which teach the agent what constitutes a valid term — ranging from mineral names to treatments to phenomena — something the schema alone does not convey.

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 opens with a specific verb and resource: 'Look up a gemmological term in The Gem Lexicon of Ministry of Gems.' It states the returns (definition, subject section, citable anchor URL) and gives concrete example terms (padparadscha, corundum, asterism) that bound the scope. The examples and the phrase '215 definitions' clearly differentiate this curated-lexicon lookup from siblings like search_gem_knowledge or list_gem_terms.

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 clear when-to-use context: 'Use for terms such as...' with five example terms spanning mineral names, color varieties, and phenomena. It does not explicitly name alternatives or exclusion conditions, so an agent must infer from sibling names (e.g., list_gem_terms for browsing, gem_properties for physical data) rather than being told. Clear context but no explicit exclusions earns a 4.

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 declare readOnlyHint, idempotentHint, and destructiveHint false, which already convey the safety profile. The description adds the behavioral detail that it corrects for specific gravity, a meaningful calculation behavior. However, it does not mention other behavioral traits like output format or error handling, which are partially covered by the output 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?

The description is a single sentence with a clear main clause and a list of shapes. It is front-loaded with the purpose and the correction factor. It's concise enough, though it could be slightly trimmed, but it's well-structured and informative.

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 that an output schema exists, the description doesn't need to explain return values. It covers the key parameters (carat, shape, species) and the distinguishing feature (SG correction). It is clear enough for an agent to call the tool correctly. It doesn't mention edge cases, but they aren't critical for a simple estimation tool.

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 describes shape and species with default values, but the description lists the allowed shapes explicitly (round, oval, cushion, etc.) and gives examples for species (sapphire, diamond, spinel, emerald, opal), adding clarity beyond the schema. The carat parameter is self-explanatory. With 67% schema coverage, the description adds value by enumerating options.

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 uses a specific verb 'Approximate' and a clear resource 'face-up millimetre dimensions'. It also distinguishes from 'diamond-only calculators' by correcting for specific gravity, making it clear what this tool does that others don't. This is a specific and unambiguous purpose.

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 implies when to use this tool: whenever you need face-up size for any gem species, unlike diamond-only calculators. It explicitly mentions the alternative (diamond-only calculators) and why this one is different, providing clear context. However, it does not explicitly state exclusions or when not to use it beyond the contrast.

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 convey readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety. It adds value by mentioning the source (FGAA-reviewed) and coverage scope (specific gemstones), which hints at behavior for unsupported stones. No contradiction with annotations.

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 sentences, front-loaded with the core question, then coverage examples. There is no filler, and every phrase adds relevant context.

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 one-parameter read-only tool with an output schema and safety annotations, the description covers the essential scope and source. It could explicitly state what the tool returns for a gem not in the list, but the 'and more' phrase and output schema mitigate that gap.

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 must compensate. It identifies the 'gemstone' parameter as the target and provides concrete examples (sapphire, ruby, diamond, etc.). However, it does not specify exact accepted values, format, or edge cases, 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 clearly identifies the tool's subject (cleaning and wearing gemstones) and its resource (FGAA-reviewed care table), listing specific gems covered. It lacks an explicit action verb like 'retrieve' or 'list', but the content is specific enough to distinguish it from sibling tools such as gem_properties or compare_gems.

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 given on when to use this tool versus alternatives like gem_properties or search_gem_knowledge. The description only implies its purpose; it does not state situations where it should be preferred or avoided.

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 carry readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds value beyond these by identifying the authoritative data source (FGAA-reviewed Gem Data Tables) and the trade-name resolution behavior. No contradiction with annotations; 'and more' is consistent with openWorldHint=false.

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 tightly-written sentences with zero filler. The property list is front-loaded first, followed by the source authority and trade-name behavior. Every 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?

A single parameter with 100% schema coverage, rich read-only annotations, and an output schema present. The description fully equips an agent to call it correctly — what to pass in and what properties come back. Nothing an agent needs is missing.

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% — the species parameter is fully described with examples in the schema. The description adds genuine extra value by documenting the trade-name resolution behavior (sapphire→corundum, tsavorite→garnet) that isn't in the schema, raising it above the baseline 3.

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 a specific resource (physical properties) and enumerates exactly which properties are returned (Mohs hardness, refractive index, specific gravity, birefringence, crystal system), plus example species. This clearly distinguishes it from siblings like define_gem_term (definitions) and faceup_size_estimate (size).

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 enumerated property list makes the use case clear — this is for physical data, not definitions or care. It explicitly states it accepts trade names and how they resolve ('sapphire' to corundum, 'tsavorite' to garnet). It doesn't name alternative tools or when-not-to-use, but the scope is evident from the properties listed.

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, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by specifying the exact content returned (including the Digital Gemstone Passport link and checkout link), which goes beyond the annotations and helps the agent predict the outcome without needing to inspect the output 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?

The description is two sentences: the first packs all relevant return fields into a single list, and the second gives a clear usage directive. Every word earns its place; there is no fluff or redundancy. The information is front-loaded and immediately actionable.

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?

The tool is a simple read-only detail endpoint with an output schema and one clear parameter. The description fully covers what the tool does, what it returns, and when it should be used. No additional edge cases or prerequisites are necessary for an agent to call it correctly.

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?

There is only one parameter ('handle') and the schema description already explains it accepts a handle or full URL. The tool description repeats this but adds no new meaning beyond what the schema provides. With 100% schema coverage, a baseline of 3 is appropriate; no extra parameter semantics are needed.

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 clear verb-resource action ('Full detail for one Ministry of Gems product') and enumerates the exact fields returned (specifications, description, price, availability, variants, images, passport link, checkout link). It also distinguishes itself from sibling search_gem_inventory by noting it is a follow-up step, making the purpose specific and 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?

The description explicitly instructs 'Use after search_gem_inventory,' which tells the agent exactly when to invoke this tool. Though it doesn't list when not to use it, the directive is sufficient for a single-purpose detail fetcher, and the relationship to its predecessor is clear.

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 mark the tool as read-only, idempotent, and non-destructive, so the bar is lower. The description adds useful behavior beyond those hints: it does not perform verification itself, it flags unrecognized lab names, and it explains what 'FGAA' means.

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 front-loads the main purpose and ends with a crisp boundary statement. The enumerated lab list is useful but makes the first sentence denser than necessary; still, each 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?

With an output schema and read-only annotations present, the description does not need to explain return values or safety. It covers the routing behavior, no-verification caveat, lab coverage, and unrecognized-lab handling, but the unexplained report_number parameter is a notable completeness gap.

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 documents 'lab' but leaves 'report_number' completely undescribed, and the description never explains how report_number is used or whether it is needed for the verification page or checklist. The list of lab names adds some context for the 'lab' parameter, but it does not compensate for the missing report_number semantics.

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 action: return the issuing laboratory's verification page plus a four-step checklist for confirming a grading report. It also explicitly clarifies that the tool routes to the lab and does not verify the report itself, which clearly separates it from siblings like verify_gem_passport.

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 clear context on scope — it covers named labs including coloured-stone laboratories and flags unrecognized lab names. The final sentence, 'Routes to the lab; does not verify the report itself,' is an effective when-not-to-use boundary, though it does not explicitly name sibling alternatives.

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 cover read-only, idempotent, and non-destructive behavior. The description adds the useful detail that listed terms are valid targets for definition, but it does not disclose additional behavioral context such as pagination or availability limits. Output schema softens that gap.

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 compact sentences deliver the core behavior, scope, and sibling relationship with no unnecessary detail. The most important usage guidance is placed at the end of the second sentence and remains effective.

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?

This is a simple listing tool with one optional parameter, a complete schema, an output schema, and strong annotations. The description gives enough context for an agent to invoke it appropriately without missing information.

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 section parameter already has a clear description and example. The tool description does not add meaning beyond the schema, so the schema-heavy baseline of 3 is appropriate.

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?

Description states a specific action (list), a specific resource (gemmological terms in The Gem Lexicon), and a scoping option (filter by subject section). It also positions the tool as a discovery precursor to define_gem_term, helping distinguish it from the nearest sibling.

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?

It explicitly tells an agent to use this tool to discover what can be defined before calling define_gem_term, providing a clear when-to-use. However, it does not mention search_gem_knowledge or explain when to choose that sibling instead, leaving a small gap.

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 this as read-only, idempotent, and non-destructive. The description adds useful behavioral context: the data comes from a published source, is banded by origin/size, includes stone counts and a computation date, and is a house guide rather than a market index. No contradiction with annotations.

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 dense sentences, front-loaded with the core subject—what costs per carat in AUD—followed by provenance and a concrete usage example. Every sentence contributes.

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-optional-parameter lookup with an output schema and complete annotations, the description is complete: it names the source, the banding dimensions, the computed date, the stone-count context, and the caveat that this is a house guide. Nothing needed to invoke it correctly is missing.

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 schema already documents carat and origin. The description reinforces that carat selects a size band and origin is Australian or Ceylon, but does not add meaning beyond the schema; baseline 3 is appropriate.

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 identifies the resource—natural sapphire price per carat in AUD from Ministry of Gems' price guide—and the main question it answers. It does not use a strong imperative verb and does not explicitly distinguish itself from sibling knowledge/property tools, so it falls just 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?

The description gives a concrete use case ('Answers how much is a 2 carat sapphire') and frames the result as a house guide rather than a market index, which tells an agent how to interpret it. It does not explicitly list when not to use the tool or name alternatives.

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, and destructiveHint false. The description adds meaningful behavioral context beyond that: it searches a "live" catalogue, returns availability and a buy link, and guarantees every loose gem carries a verifiable Digital Gemstone Passport.

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 that front-loads the core search action and resource before adding details. It contains valuable scoping information (currency, product types, passport guarantee) with little waste, though it is slightly brochure-like.

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 output schema, annotations, and no required parameters, the description supplies enough context for an agent to select and call the tool successfully. It does not need to restate return values, and the filter categories plus examples in the schema complete the picture.

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% and the description partially compensates by mentioning carat range and price range filters, which map to the undocumented min/max numeric parameters. However, it does not name those parameters or explain the default in_stock_only and limit behavior, so the numerical filter semantics remain somewhat implicit.

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 opens with a specific verb and resource: "Search the live Ministry of Gems catalogue," and enumerates loose gemstones and jewellery, availability, prices, and buy links. This clearly distinguishes it from knowledge-base siblings like search_gem_knowledge or gem_properties.

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 makes clear this is the tool for searching current stock and filtering commercial inventory, which strongly implies its use case. It does not explicitly name alternatives or state when not to use it, so it misses the highest bar for exclusionary guidance.

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 cover readOnlyHint, destructiveHint, and idempotentHint, so the safety profile is clear. The description adds valuable behavioral context: it returns ranked results with matched passages and citable URLs, and specifies full-text search across every section. This goes beyond the annotation declarations without contradicting them.

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, information-dense sentence that front-loads the purpose and then adds scope and return details. No extraneous words, but it is slightly long. Still, every part 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?

The description covers what is searched, what is returned (ranked results, passages, URLs), and the scope of the search. An output schema exists to detail result fields, so the description doesn't need to explain return structure. It is complete for an agent to decide when to call it and what to expect.

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% for both parameters (query and limit), so the schema already documents their purpose. The description does not add parameter-specific details like query syntax or formatting, so it provides no value beyond the schema. Baseline 3 is appropriate.

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 verb 'search' and the resource 'Ministry of Gems gemmological reference library', specifying contents (215 lexicon definitions, 25 handbooks) and full-text scope. It distinguishes from siblings like search_gem_inventory (product search) and define_gem_term (specific definition lookup) by focusing on full-text search across reference material.

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 implies when to use it (searching the reference library) but does not explicitly mention when not to use it or direct to alternatives. Sibling names like search_gem_inventory suggest different use cases, but the description doesn't articulate these boundaries.

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, and destructiveHint=false. The description adds behavioral detail beyond these: it explains the cryptographic process (recomputing SHA-256, verifying Ed25519 signature against the house public key) and enumerates the returned attested record. This is meaningful context, though failure behavior for invalid signatures or unknown IDs is not described.

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, each earning its place: the first states the core action, the second explains the verification mechanism and output, the third gives usage guidance. The most critical information is front-loaded with no fluff.

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 read-only, idempotent verification tool with a single well-documented parameter and an output schema, the description covers purpose, method, returned fields, and usage context. Nothing essential for an agent to invoke it correctly is missing.

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 stone_id is fully documented with format and examples. The description primarily repeats 'by stone ID' and does not add new parameter-level semantic detail, so the baseline of 3 is appropriate.

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 ('verify'), a precise resource ('Digital Gemstone Passport by stone ID'), and the method (SHA-256 recomputation, Ed25519 signature check). Clearly differentiates from siblings like get_gem_product or lab_report_check, which do not claim cryptographic authenticity verification.

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?

Provides explicit when-to-use triggers: when a buyer asks if a stone/passport is genuine, or before quoting any fact about a specific stone. It does not explicitly list exclusions or alternatives, but the context is clear enough for an agent to select this tool over similar ones.

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