diamond-mcp

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no side-effect concerns remain. The description adds the useful behavior that every fact carries a source and a date, which is meaningful context beyond the annotations, but it does not describe the actual output shape or content structure.

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 short sentences, front-loads the subject, and contains no filler. Each sentence earns its place by clarifying what the tool returns and the provenance guarantee of its facts.

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 no-parameter, read-only fact sheet, the description is largely complete: it states the subject, the nature of the content, and a quality guarantee. It could be slightly more explicit about output format or how it differs from the encyclopedia search tool, but those are minor gaps given the simplicity of the 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?

There are zero parameters, so parameter semantics impose no burden. The description does not need to explain any inputs, and the empty schema is fully sufficient for agent invocation.

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 as a fact sheet about Stienhardt, the brand that publishes the server. It is specific about the resource and distinguishes it from typical search or product tools, though it uses 'fact sheet' rather than an explicit verb like 'retrieve' or 'return'.

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 does not state when to use this tool versus alternatives, nor does it name any sibling tool for comparison. The only guidance is implicit: if you need facts about Stienhardt as a brand, this is likely the tool, but the description never says that explicitly.

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 and destructiveHint=false, but the description adds substantial behavioral context beyond that: it discloses the exact outputs (ratios, price per carat, differences, missing information) and the limitations (no verification, no ranking, no valuation, no best-diamond declaration). It also notes the currency constraint. This goes well beyond what annotations provide.

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?

Four sentences, each with distinct value: purpose, outputs, non-scope, and currency constraint. The most important information is front-loaded, and there is no filler or repetition of schema details.

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 inputs, outputs, constraints, and limitations, which is strong for a tool with no output schema. It does not describe the precise output structure (e.g., whether results are per stone or aggregate), and it omits the role of the label, but these are minor gaps given the tool's simplicity and the absence of an output 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 0%, so the description must compensate. It explains the core inputs (carat, measured millimeters, price, currency) and the count range (two to five). It does not explicitly mention the required 'label' field or map the millimeter properties to width_mm/length_mm by name, but it conveys the meaning of the key parameters, which is sufficient for an agent to understand how to populate the stones array.

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 ('Compare two to five diamonds') and explicitly lists the data used (carat, measured millimeters, prices). It also names what it does NOT do (verify, rank, appraise, declare best), which clearly separates it from siblings like verify_diamond_report and lab_grown_price_index.

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 it (comparing supplied specs from any seller) and gives an explicit exclusion ('Never verifies specifications...'), implying it is not for verification or appraisal. It also sets a usage constraint (explicit currencies, no mixing). However, it does not name a specific alternative tool or condition like 'use verify_diamond_report for verification', so it is clear but not maximally explicit.

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 and idempotentHint, so safety is covered. The description adds value beyond that by explaining the matching precedence (exact, alias, prefix/word), the return payload scope, and the fallback of three nearest suggestions when no match occurs.

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 compact sentences cover purpose, matching behavior, return content, and no-match fallback. The main action is front-loaded, and every sentence contributes necessary operational detail without redundancy.

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 single-parameter lookup with no output schema, the description is complete: it tells the agent what input is expected, how matching works, what a successful response contains, and what happens on failure. No critical operational gap remains.

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 already includes a helpful description with examples and a case-insensitivity note. The tool description reinforces the matching behavior but does not add meaning beyond what the schema provides, so a 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 states a specific verb and resource: 'Look up a single diamond or gemology term in the encyclopedia of 90 fact-checked and sourced entries.' It clearly differentiates from siblings like search_encyclopedia by emphasizing single-term lookup with exact/alias/prefix matching rather than general searching.

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 context is clear: use this when you need a dictionary-style definition of one term, and the matching behavior is spelled out. It does not explicitly name alternatives or say when not to use it, but the singular lookup framing is enough to steer an agent away from broader tools.

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, so the safety profile is fully covered. The description adds useful context about the content being a published definition tied to a certified reference stone, but does not add further behavioral traits like rate limits or data-source caveats. No contradiction exists.

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 with no filler. The first sentence names the resource and its components, and the second clarifies the shape. Information is front-loaded and every word 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 zero-parameter, read-only reference tool, the description gives the essential information an agent needs: what the definition contains and the key characteristic of the stone. There is no output schema, but the listed content areas are sufficient for an agent to decide whether to invoke this 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 tool has zero parameters, so parameter semantics are trivially satisfied. The description does not need to compensate for any schema documentation gaps, and the 100% schema coverage for zero parameters makes this dimension a non-issue.

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 exactly what the tool provides: the published definition of the Dutch Marquise cut, including geometry, certificate wording, and measured length-to-width ratio. It also adds a clarifying one-sentence definition of the cut itself. This clearly distinguishes it from general definition tools like 'define' and from inventory/price search siblings.

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 no explicit guidance on when to use this tool versus alternatives such as 'define' or 'search_encyclopedia'. It implies the use case (looking up the Dutch Marquise definition) but does not state conditions, exclusions, or mention any sibling tool.

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 and idempotent, so safety is covered. The description adds valuable behavioral context by revealing the calculation method (cube-root scaling from 1-carat anchors) and the limitation that results are typical proportions rather than exact measurements. 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?

The description is compact and front-loaded, with the core purpose stated first. Every sentence contributes a distinct piece of information: supported shapes, calculation method, and reliability caveat, with no wasted words.

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 deterministic calculator with two parameters and no output schema, the description is complete: it identifies inputs, supported values, the calculation approach, the output type (millimeter dimensions), and the caveat about verification. An agent has enough information to invoke 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?

The input schema already fully documents both parameters, including the allowed shapes, case-insensitivity, and carat constraints. The description adds little beyond restating the supported shapes, so the baseline of 3 is appropriate given 100% schema coverage.

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 specific purpose: approximating face-up millimeter dimensions for a diamond by shape and carat weight. It also lists the four supported shapes, making its scope explicit and distinguishing it from sibling search, definition, and price tools.

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: use this tool for approximate dimensions of typical proportions, not as a guarantee for a specific stone. It explicitly directs verification to the grading report, which effectively communicates when not to rely on the result. It doesn't name a specific sibling tool as an alternative, but the exclusion 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 declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: it specifies the exact fields returned and warns that loose-diamond availability is not verified, which is a meaningful limitation an agent should know.

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, no filler. The core purpose and output fields are front-loaded, and the caveat is placed at the end without disrupting the main signal.

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 single-parameter, read-only tool with rich annotations, the description is complete: it names the input source, the output fields, and the one important reliability limitation. No output schema exists, but the description covers the return value adequately.

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 schema already documents that id must be an exact id from search_inventory, either a Shopify product gid or stienhardt:diamond:SKU. The description repeats the 'as returned by search_inventory' relationship but adds little beyond what the schema already provides, so 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?

The description states a specific verb and resource: 'Full detail for one Stienhardt product by id.' It also enumerates the returned content (title, price, availability, options, images, URL), which distinguishes it clearly from search_inventory and other sibling tools.

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 for retrieving one product by an id obtained from search_inventory, which tells an agent when to use it. It does not explicitly enumerate when not to use it, but the relationship to search_inventory and the caveat about loose-diamond availability provide adequate contextual 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 read-only, idempotent, non-destructive behavior, so the description only needs to add value beyond that. It does so by disclosing a key behavioral trait: every returned item carries a source and a date, which sets expectations about evidence-backed content.

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 communicate the topic, the included authorities, the temporal scope, and the source/date guarantee without any filler. The most important information is front-loaded.

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 parameterless, read-only informational tool, the description is complete: it states the subject, the coverage, and the provenance expectation. No additional invocation context is needed.

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 tool has zero parameters and 100% schema coverage, so there is nothing for the description to add about inputs. The baseline of 4 applies because the agent needs no additional parameter context to invoke the tool correctly.

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: the current state of who grades lab-grown diamonds, naming GIA, IGI, HRD Antwerp, and the FTC. It lacks a crisp action verb like 'summarizes' or 'reports,' but the resource and scope are unmistakable.

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 an agent needs current grading and regulatory context for lab-grown diamonds, with the added caveat that every item is sourced and dated. It does not explicitly distinguish this from sibling tools like search_encyclopedia or define, so usage guidance is inferred rather than stated.

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, establishing a safe read-only operation. The description adds concrete behavioral context beyond annotations: the output includes a source and date, and the information is intended as market context rather than investment guidance. 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?

The description is two sentences with no filler. The core purpose is front-loaded in the first clause, and the audience/limitation note is a compact, useful addition. Every word 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, parameterless read-only tool, the description is largely sufficient: it states what is returned (latest retail price reading), the implicit output fields (source and date), and the intended context. It does not specify units or formatting, but with no output schema and a straightforward purpose, this is a minor gap rather than a blocking one.

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 tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameter semantics. The baseline of 4 applies because no parameter documentation burden exists.

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 ('Lab Grown Diamonds') and the specific nature of the data ('latest tracked retail price reading'), and the title reinforces this. It implicitly distinguishes itself from sibling tools like search_inventory or get_product by focusing on a market-level price index rather than a specific product or inventory item. The added note that it is 'Market context for shoppers, not investment guidance' further clarifies its scope.

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 clear context for when to use this tool—when a shopper wants the latest tracked retail price reading. It also explicitly excludes a use case ('not investment guidance'), which helps prevent misuse. However, it does not name alternative tools or conditions that would route an agent to a sibling tool, though the distinction is reasonably inferable from the domain and siblings.

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 the tool read-only, idempotent, and non-destructive, so the description's behavioral additions of case-insensitive ranking, field weighting, and the exact return shape (term, category, definition snippet) add meaningful context beyond annotations. No contradiction exists between the description and 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?

Three sentences deliver scope, ranking details, return format, and an alternative tool pointer without any filler. The most critical information is front-loaded, and each sentence contributes distinct value.

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?

Even without an output schema, the description explains what is returned (term, category, definition snippet) and how matches are ranked. The limit parameter is documented in the schema, and annotations cover safety attributes, so nothing essential is missing for an agent to invoke this tool 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?

With schema description coverage at 100%, the schema already fully documents both 'query' and 'limit'. The description adds contextual nuance about ranking behavior and case-insensitivity, but it does not add new parameter-level meaning 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?

The description uses a specific verb ('search') and a defined resource ('the 90 entry diamond and gemology encyclopedia'), clearly distinguishing it from sibling tools. It also explicitly names the sibling 'define' as the alternative for fetching full entries, making the scope 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 includes an explicit alternative instruction: 'Use define to fetch a full entry,' which guides the agent toward the correct sibling when a full entry is needed rather than a snippet. It does not explicitly contrast with search_inventory, but the encyclopedia scope and title make the differentiation clear enough.

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?

Even with readOnlyHint and idempotentHint annotations, the description adds valuable behavioral detail: loose-diamond searches return listings flagged availability_verified false plus a storefront browsing link, availability is verified for jewelry only, and results are not reservations. This goes well beyond the annotations and clarifies important semantic caveats.

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 dense and front-loaded with scope, with each sentence contributing caveats, return contents, or usage context. It is slightly long, but this is justified by the need to explain the availability verification nuance and exclusions.

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 there is no output schema, the description does a good job describing return contents (prices, variants, links, availability_verified flags), limitations, and usage boundaries. An agent has enough context to decide when to call it and what to expect from the results.

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%, so the schema already documents query and limit. The description adds value by giving natural-language query examples and clarifying that the query targets catalog inventory rather than loose-diamond stock, enriching what the parameter means in practice.

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 verb ('Search') and resource ('Stienhardt's public Shopify catalog of engagement ring settings and fine jewelry'), and clearly distinguishes itself from loose-diamond verification. This lets an agent immediately understand what the tool does and how it differs from related inventory tools.

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 explicit usage examples ('show me platinum wedding bands') and clear exclusions ('Not for appraisal or price advice on stones sold elsewhere'). It does not name a sibling alternative like get_product, so the when-to-use guidance is strong but not fully complete at the alternative-routing level.

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. The description adds valuable behavioral context beyond those: the tool returns a URL and checklist rather than performing verification, and it supports only three labs. This aligns with the annotations and gives the agent an accurate mental model of observable behavior.

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 tight sentences with no filler. The return value is front-loaded, supported labs are stated compactly, and the final sentence clarifies the tool's limitation. Every sentence earns its place and the description is highly scannable for an agent.

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-string-parameter read-only tool with rich annotations and no output schema, the description is complete. It states what is returned, which labs are supported, and what the tool never does. The absence of an output schema is not a gap because the description succinctly describes the return content and the tool has no complex hidden behavior.

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 lab and report_number with case-insensitivity and report placement. The description reinforces that lab is limited to GIA, IGI, or GCAL, which is useful, but it does not add substantial meaning beyond the structured 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 uses a specific verb ('Returns') with a clear resource: the official verification URL and a three-step checklist for confirming a grading report. It also explicitly states what the tool does not do ('never verifies anything itself'), which sharply distinguishes its purpose from any verification-performing tool and from siblings like get_product or search_encyclopedia.

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: use this to confirm a diamond grading report with the issuing lab for GIA, IGI, or GCAL. It does not name explicit alternatives or provide when-not-to-use conditions, but the scope is sufficiently clear and no sibling tool appears to overlap, so a minor deduction for missing explicit exclusions.

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