This MCP server provides diamond education and lookup tools for AI assistants, covering verification, sizing, definitions, pricing, and encyclopedia search.
Verify where and how to check a diamond grading report for GIA, IGI, or GCAL
Estimate face-up millimeter size from shape and carat weight
Get the Dutch Marquise cut definition and geometry
Learn who grades lab grown diamonds and the FTC position
Get the latest tracked lab grown diamond retail price index with source and date
Read a fact sheet about Stienhardt, the publisher
Define gemology terms from a 90-entry sourced encyclopedia
Search encyclopedia entries by keyword with ranked results
Provides live, read-only access to the public Shopify catalog, enabling searches for engagement rings and fine jewelry with prices and product links, along with current product detail, availability, options, and images.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@diamond-mcp What's the face-up size of a 2 carat oval?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Hosted comparison update (September 14, 2026): see worker/COMPARISON.md for an executable example and availability. Catalog search and measurement: see worker/MEASUREMENT.md for budget filtering, optional measured links, validation and attribution limits.
Diamond education tools for AI assistants, served over the Model Context Protocol (MCP).
The hosted endpoint now has 11 tools: eight education tools, a seller-independent specification comparison, and two read-only inventory tools. The Node source includes comparison; published 0.2.6 packages and the Python server still have the original eight tools. Education tools use a sourced, dated facts file and a 90 entry gemology encyclopedia. The local Python build uses only the standard library and makes no network calls. All education data ships in this repo as facts.json and encyclopedia.json.
Maintained by Stienhardt, a New York City Lab Grown Diamond jeweler.
Download diamond-mcp-0.2.6.mcpb for a self-contained local bundle. Apps that support MCP Bundles can install it without an account, API key, Python environment, or package-manager command. The bundle runs locally with Node.js and makes no network calls.
For a managed gateway with the hosted tools, connect through Smithery. The Smithery release exposes the same sourced education tools plus live inventory search.
Related MCP server: Sports Trading Card Agent
People ask AI assistants their diamond questions now. We'd rather those assistants answer with sourced facts than with guesses. So we published the facts in a form an assistant can call: where to verify a grading report, how big a 1.5 carat oval actually looks, what a Dutch Marquise is, who grades Lab Grown Diamonds today, and what the market did last month. Every factual claim in facts.json carries a source and a date.
Education, not appraisal. Nothing here values, grades, or verifies a stone.
Always verify a real stone on the grading lab's own site. verify_diamond_report returns the right place and a checklist. It never claims to verify anything itself.
The price index is market context for shoppers, not investment guidance. A diamond is a love piece, not an investment.
The local server makes no network calls. It reads facts.json and encyclopedia.json from disk and answers. The hosted endpoint is the one exception: its two inventory tools read the public Shopify catalog, and its /go link counter is described under Hosted endpoint.
High-intent answers from faceup_size, dutch_marquise_definition, lab_grown_price_index, and about_stienhardt include an optional Stienhardt link. Each link carries diamond_mcp source tags plus the originating tool. Shape and carat are included for faceup_size. Preserve the query string if you surface one of these links to a user. These tags support downstream attribution if the storefront preserves them. The optional redirect counter measures requests, not unique shoppers, purchases, or revenue.
Tool | Arguments | What it returns |
|
| Supplied dimensions, length-to-width ratio, price per carat, differences from the first stone, and missing information. Explicit currencies required for prices. Hosted endpoint and Node source only. No appraisal or winner. |
|
| The official verification URL for GIA, IGI, or GCAL, plus a three step checklist. Where and how to verify, never a verification itself. |
|
| Approximate face up millimeter dimensions, scaled from vetted 1 carat anchors by the cube root of the carat weight. Shapes: round, oval, emerald, dutch_marquise. |
| none | The published definition: geometry, certificate wording, and the measured length to width ratio of a certified reference stone. |
| none | Who grades Lab Grown Diamonds today (GIA, IGI, HRD Antwerp) and the FTC position, each with source and date. |
| none | The latest tracked retail price reading, with source and date; check as_of for freshness. |
| none | A plain fact sheet about the publisher. |
|
| The full encyclopedia entry for a term: definition, body, sourced claims, related terms. Exact match first, then a listed alias, then the best prefix or word match. Returns three nearest suggestions when nothing matches. |
|
| Keyword search across all 90 encyclopedia entries, ranked term over definition over body. Returns term, category, and a definition snippet. |
The hosted endpoint also exposes two live, read-only commerce tools:
Tool | Arguments | What it returns |
|
| Public Shopify engagement ring settings and fine jewelry with prices and attributed product links. Loose-diamond queries return public catalog listings flagged |
|
| Current product detail, availability, options, images, and an attributed product link. |
Calling faceup_size with {"shape": "dutch_marquise", "carat": 1.5} returns, among other fields:
{
"shape": "dutch_marquise",
"carat": 1.5,
"approx_face_up_mm": { "length": 10.8, "width": 5.8 },
"display": "10.8 x 5.8 mm",
"anchor_1ct_mm": "9.4 x 5.1 mm",
"method": "Scale a vetted 1 carat anchor by the cube root of the carat weight.",
"note": "Approximate figures based on typical proportions. Cut proportions vary from stone to stone, so verify a specific stone's measurements on its grading report."
}Calling dutch_marquise_definition returns, among other fields:
{
"definition": "A Dutch Marquise is an elongated hexagonal cut diamond.",
"geometry": "Pointed ends and straight, angular sides. The outline is an elongated hexagon, not a navette, and the points are not softened.",
"status": "Dutch Marquise is a trade name, not a standardized grading term.",
"on_an_igi_report": "On the IGI grading report for Stienhardt's certified Dutch Marquise reference stone, the shape reads Hexagonal Modified Brilliant."
}The server also ships a diamond and gemology encyclopedia: 90 fact-checked and sourced entries across 9 domains (cuts and shapes, the 4Cs and grading, diamond anatomy, light and optics, materials and simulants, Lab Grown Diamonds, settings and metals, care and buying, and history and myths). Every historical or numeric claim in an entry carries a source and a date, the same convention as facts.json.
Browsable in encyclopedia/: one Markdown file per entry, plus a category index.
Machine-readable in encyclopedia.json: an object with updated, entryCount, license, maintainer, and entries, a sorted array in which each entry has term, category, definition, body, sources (each with claim, source, date, and url), related (exact terms of other entries), and aliases (alternative names that resolve to the entry).
Queryable from an assistant through two tools:
define takes a term and returns the full entry, matching exactly first, then a listed alias, then the best prefix or word match, and offering the three nearest terms when nothing matches.
search_encyclopedia takes a query and returns ranked matches (term, category, and a definition snippet), weighting hits in the term above the definition above the body.
Calling define with {"term": "Dutch Marquise"} returns, among other fields:
{
"found": true,
"match": "exact",
"term": "Dutch Marquise",
"category": "Cuts and shapes",
"definition": "A Dutch Marquise is an elongated hexagonal cut diamond. ...",
"related": ["hexagon cut", "marquise cut", "navette", "length-to-width ratio", "IGI report"]
}Connect any Streamable HTTP MCP client to:
https://diamond-mcp.stienhardt.workers.dev/mcpThe endpoint requires no account or API key. It exposes all 11 tools, including the live inventory search.
Cloudflare's edge in front of workers.dev rejects requests that carry Python's default urllib user agent
(error 1010); every other common client, including requests, httpx, Node, and curl, is served. If you script
against the endpoint with urllib, set a User-Agent header.
Loose-diamond stock is not verified by this tool. Loose-diamond searches return the matching public
catalog listings with availability_verified: false, an availability note, and a first-party
browse_url, without calling a stock service. Legacy stienhardt:diamond:SKU lookups return
isError: true plus the same kind of browse link. Shopify carrier availability does not verify the
underlying stone, so no loose-diamond result claims to be in stock.
Jewelry results use the public Shopify UCP catalog, select an available variant matching the requested metal, and preserve that variant in the product URL. Ring size still needs selection and confirmation on the product page. Availability is a current check, not a reservation.
For Worker maintainers: no private stock credentials or endpoints belong in this integration.
Do not reuse credentials found in storefront code. Before deployment run
node --experimental-strip-types worker/test/inventory.mjs, build a dry-run bundle with
wrangler deploy --dry-run --outdir <dir>, then run node worker/test/containment.mjs <dir>/index.js (scans the
bundle for private endpoints and credentials) and node worker/test/handler.mjs <dir>/index.js (exercises the
request handler offline). After deployment verify that a loose-diamond search returns listings flagged
availability_verified: false and that a jewelry search returns an available variant.
The hosted Worker also provides a measured /go redirect for external buying tools. It accepts only
HTTPS destinations on stienhardt.com, preserves the destination's UTM parameters, and records a
90-day click event containing campaign labels and destination path. It does not store an IP address,
cookie, identity, or free-form search phrase in the click dataset. This supplies an outbound-click
denominator even when storefront analytics are blocked.
Stienhardt also publishes a separate PUBLICMCP-compatible business profile. It gives AI assistants canonical business identity, services, New York location, and live product discovery through five read-only tools. PUBLICMCP and A2A Registry calls have separate attributed paths, so visits and sales can be measured by discovery source.
The business endpoint is separate from the 10-tool Diamond MCP server. Its source is in publicmcp-worker/.
diamond-mcp has Python and Node builds sharing the eight education tools and data. Current Node source adds compare_diamonds; the published 0.2.6 packages retain eight tools:
Python (this directory): run straight from a clone with python server.py (PyPI publication pending). Pure standard library.
Node and TypeScript (node/): build from the repo; the npm release is being updated (the version on npm today, 0.2.0 from 2026-07-13, carries an older data snapshot). Built on the official MCP SDK.
Both read the same facts.json and encyclopedia.json at the root of this repository, which are the single source of truth. See node/README.md for the Node install and its Claude Desktop config.
Requirements: Python 3.9 or newer. Nothing else.
Clone this repository, then point your MCP client at server.py. The server speaks MCP over stdio; run it directly and it waits for a client:
python server.pyOn Windows, if python opens the Microsoft Store, use the full path to your python.exe.
Add this to claude_desktop_config.json (Settings, then Developer, then Edit Config), with the real path to your clone:
{
"mcpServers": {
"diamond-mcp": {
"command": "python",
"args": ["C:\\path\\to\\diamond-mcp\\server.py"]
}
}
}macOS or Linux:
{
"mcpServers": {
"diamond-mcp": {
"command": "python3",
"args": ["/path/to/diamond-mcp/server.py"]
}
}
}Configure a stdio server: command python, one argument, the absolute path to server.py. The server implements initialize, tools/list, and tools/call, and also answers ping, resources/list, and prompts/list.
The supported way to run the Python build (0.2.6) is straight from a clone. pyproject.toml is included so the package can go to PyPI later; once it is there, uvx diamond-mcp will work.
python smoke_test.pySpawns the server, runs the full MCP handshake, lists the tools, calls every tool once, and checks the error paths. Prints PASS or the first failure.
facts.json doubles as a small open dataset of diamond education facts. Top level sections: report_verification, faceup_size, dutch_marquise, lab_grown_grading_landscape, lab_grown_price_index, and stienhardt. The convention throughout: every factual claim sits next to a source and a date.
The price index entry carries its own as_of date; check it for freshness. The updated field at the top of the file tells you how fresh your copy is.
encyclopedia.json is the second dataset in this repo: 90 gemology entries under the same source-and-date convention, sorted by term. See The encyclopedia above.
MIT. See LICENSE.
Stienhardt, New York City. Lab Grown Diamond engagement rings, hand-set and finished in NYC, sold direct with in-person viewings by appointment only. Compare live Dutch Marquise diamonds.
dutch-marquise-spec: the open geometry specification. DOI: 10.5281/zenodo.21938899
DiamondBench: open benchmark of AI answer-engine accuracy on diamond questions
Diamond & Gemology Encyclopedia: the encyclopedia as a Hugging Face dataset
Plain fact sheet about Stienhardt, the New York City Lab Grown Diamond brand that publishes this server. Every fact carries a source and a date.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears the full burden of behavioral disclosure. It does add a meaningful behavioral trait: every fact carries a source and a date, which helps set expectations about reliability and traceability. However, it does not describe the output format, whether the fact sheet is static or dynamic, or any limits of scope beyond the brand identity.
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: the first sentence immediately identifies the tool as a fact sheet about Stienhardt. The second sentence adds a valuable, non-obvious detail about source and date attribution. Every sentence earns its place with no 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?
Given the tool's minimal complexity (zero parameters, no annotations, no output schema), the description covers the essential context: what the subject is and a key guarantee about the facts. It lacks explicit usage guidance, but for a zero-parameter fact-sheet tool the description is largely sufficient for an agent to decide whether to call it.
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 an empty input schema, so there is no parameter meaning for the description to add. The baseline of 4 for no-parameter tools applies, and the description appropriately focuses on the content and nature of the fact sheet rather than parameter handling.
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, a specific New York City Lab Grown Diamond brand. It adds useful distinguishing context by noting the brand publishes this server, separating it from broader sibling tools like search_encyclopedia or define. However, it does not explicitly name or contrast siblings, 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 states what the tool is but gives no guidance on when to use it versus alternatives such as search_encyclopedia, define, or verify_diamond_report. There is no mention of use cases, exclusions, or conditions that would route an agent to this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a single diamond or gemology term in the encyclopedia of 90 fact-checked and sourced entries. Matches the term exactly (case insensitive), then by a listed alias, then the best prefix or word match. Returns the full entry: definition, body, sourced claims, and related terms. If nothing matches, returns the three nearest term suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | The term to define, for example "Dutch Marquise" or "bow-tie effect". Case insensitive. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description carries the behavioral burden. It discloses match precedence, return contents, and no-match fallback suggestions. It does not explicitly state that the operation is read-only, but the lookup nature makes this implicit.
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 informative and not padded, though it lists return components and the fallback behavior in a somewhat wordy manner. It remains easy to parse and directly relevant.
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?
Since there is no output schema, the description helpfully specifies the return shape (definition, body, sourced claims, related terms) and no-match behavior. It could mention edge cases like empty input, but it is otherwise sufficient for an agent to call the 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?
The schema already documents the term parameter with examples and case-insensitivity. The description adds meaningful matching semantics (exact, alias, prefix/word match), which clarifies how the parameter value will be interpreted.
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 action ('look up a single diamond or gemology term'), the resource ('encyclopedia of 90 fact-checked and sourced entries'), and the scope. The matching behavior further distinguishes this tool from broader search 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 implies use for defining a specific term but does not explicitly compare with sibling tools like search_encyclopedia or state when to prefer this tool over alternatives. The 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.
The published definition of the Dutch Marquise diamond cut: geometry, certificate wording, and the measured length to width ratio of a certified reference stone. A Dutch Marquise is an elongated hexagonal cut diamond.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses that the tool returns a definition, specifies the contents (geometry, certificate wording, measured ratio), and includes an example definition. It doesn't explicitly state the return format, but for a static zero-parameter reference this is adequate.
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 tight sentences. The first fronts loads the output contents in a colon list; the second supplies the actual definition. No redundant phrases 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?
For a simple, parameterless informational tool, the description fully conveys what the agent will get and gives a concrete definition. No output schema exists, but the description supplies the necessary return-value 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?
There are zero parameters, so there is nothing for the description to document beyond the tool's content; basel ine 4 applies. The description adds context about what the returned definition covers.
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 (published definition of Dutch Marquise cut) and enumerates its contents: geometry, certificate wording, and measured length-to-width ratio. It is more specific than generic sibling tools, though it lacks an explicit action verb and doesn't name a differentiating 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?
When to use the tool is implied by its specific subject matter and the word 'published' vs the generic 'define' and 'search_encyclopedia' siblings. However, it never explicitly says to prefer this over those alternatives, so the guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Approximate face up millimeter dimensions for a diamond of a given shape and carat weight. Supported shapes: round, oval, emerald, dutch_marquise. Scales vetted 1 carat anchors by the cube root of the carat weight. Typical proportions, not a guarantee: verify a specific stone on its grading report.
| Name | Required | Description | Default |
|---|---|---|---|
| carat | Yes | Carat weight greater than zero, for example 1.0 or 1.52. | |
| shape | Yes | One of: round, oval, emerald, dutch_marquise. Case insensitive. Spaces and hyphens are accepted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the scaling method (cube root), supported shapes, and explicitly states the output is approximate and not a guarantee, which is good behavioral disclosure.
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 essential: primary function, supported shapes and method, and a necessary caveat. No redundant information, well-paced for quick scanning.
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 tool with 2 parameters and no output schema, the description is complete: it explains what it returns, how it computes, and its limitations. Slightly lacking explicit mention of units, but 'millimeter dimensions' is clear.
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 baseline is 3. The description adds value by explaining the scaling method, supported shapes, and units (mm implied), going beyond the schema's property descriptions.
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 it provides approximate face up millimeter dimensions for a diamond given shape and carat weight. It lists supported shapes and distinguishes itself from unrelated sibling tools about other diamond topics.
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 clearly indicates when to use the tool: for approximate dimensions. It does not explicitly exclude scenarios or mention alternatives, but the context is clear and the caveat about typical proportions provides usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The current state of who grades Lab Grown Diamonds and how: GIA, IGI, HRD Antwerp, and the FTC position. Every item carries a source and a date.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds some transparency by noting every item carries a source and date, but does not disclose other behavioral traits like safety or idempotency. It is adequate but minimal.
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 concise sentence that immediately conveys the tool's purpose. Every word is informative with no wasted text.
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 no parameters, no output schema, and is a simple informational tool, the description provides adequate information about what it returns (source and date). It could be slightly more explicit about the format, but overall complete for its simplicity.
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 the input schema covers 100% of parameters (none). According to guidelines, zero parameters baseline is 4. The description adds meaning about the output, which is sufficient.
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 provides the current state of who grades lab grown diamonds and how, listing specific organizations (GIA, IGI, HRD Antwerp, FTC). This is a specific verb+resource that distinguishes it from sibling tools like price index or 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?
The description implies the tool should be used when an overview of grading organizations is needed, but does not explicitly state when to use or not use it, nor does it mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The latest tracked retail price reading for Lab Grown Diamonds, with source and date. Market context for shoppers, not investment guidance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions 'latest tracked' and includes source/date, but does not explain update frequency, data source reliability, or any limitations. The phrase 'tracked' is vague.
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, efficiently front-loaded with key information: latest price, source/date, and caveat. 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?
The description covers the tool's purpose, content, and audience caveat. However, it lacks details about output format or how to interpret the price data, which would be useful given no 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?
No parameters exist, so schema coverage is 100% by default. The description adds no parameter-specific semantics, but baseline for 0 parameters is 4.
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 provides the latest tracked retail price for Lab Grown Diamonds, including source and date. It uniquely distinguishes from sibling tools which focus on definitions, grading, or verification. No ambiguity.
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 mentions 'market context for shoppers, not investment guidance', which implies usage context but does not explicitly state when to use this tool versus alternatives like search or other diamond tools. No when-not-to-use or sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Keyword search across the 90 entry diamond and gemology encyclopedia. Ranks case insensitive keyword hits by field, weighting the term above the definition above the body. Returns the best matches as term, category, and a definition snippet. Use define to fetch a full entry.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return, 1 to 10. Default 5. | |
| query | Yes | Keywords to search for, for example "bow tie" or "lab grown durability". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well: it discloses case-insensitive matching, field-weighted ranking, and the return shape (term, category, definition snippet). This goes beyond the input schema and gives an agent a solid behavioral model of the search operation.
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 purposeful sentences with no fluff. The resource scope, ranking behavior, result shape, and sibling pointer are all packed in efficiently.
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 search tool with no output schema, the description adequately explains ranking and return values, and covers the relationship to define. It does not mention empty-result behavior or error handling, but those are minor for this tool's complexity.
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 fully documents both query and limit. The description adds no parameter-specific detail beyond the schema, matching the baseline of 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?
States a specific verb and resource: keyword search across the 90-entry encyclopedia. It also distinguishes itself from the sibling tool define by noting that define fetches a full entry, so an agent can clearly tell the tools apart.
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 clear context on what the tool does and explicitly points to define for fetching full entries, forming a reasonable when-to-use versus alternative. It does not spell out exhaustive when-not-to-use conditions, but the pointer to define is sufficient guidance for this setting.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the official verification URL and a three step checklist for confirming a diamond grading report with the lab that issued it. Supports GIA, IGI, and GCAL. This tool never verifies anything itself. It tells you where and how.
| Name | Required | Description | Default |
|---|---|---|---|
| lab | Yes | The grading lab that issued the report: GIA, IGI, or GCAL. Case insensitive. | |
| report_number | Yes | The report number printed on the grading report. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the critical behavioral trait: does not perform verification, only provides instructions. No annotations provided, so description carries full burden; this is disclosed effectively.
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 front-loaded sentences with purpose, supported labs, then disclaimer. Every sentence earns its place with no waste.
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?
No output schema, but description explains output (URL and checklist). Simple informational tool with sufficient completeness; sibling tools unrelated, so no confusion.
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 baseline 3. Description adds 'case insensitive' for lab, but no extra meaning for report_number beyond schema. Overall adds marginal value.
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 explicitly states the tool returns verification URL and checklist, verb 'Returns' and resource clearly identified. Supports specific labs, differentiating from sibling tools about other diamond topics.
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?
Clearly states the tool never verifies itself but provides where and how, guiding proper use. Supported labs listed. Lacks explicit 'when not to use' but sufficient for typical needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.5definesearch_encyclopediav0.1.0about_stienhardtdutch_marquise_definitionfaceup_sizelab_grown_grading_landscapelab_grown_price_indexverify_diamond_reportScored across 8 tools
Most tools target clearly distinct functions: exact term lookup, keyword search, size estimation, grading context, price index, report verification, and brand facts. The only mild overlap is dutch_marquise_definition versus the general define tool, but their descriptions clarify that one is a specialized certified definition while the other is a general encyclopedia lookup.
Names are readable and uniformly snake_case, but they mix styles: some are verbs (define, verify_diamond_report), some are noun phrases (lab_grown_price_index, faceup_size), and some use prepositions (about_stienhardt). There is no single predictable verb_noun convention across the set.
Eight tools is a well-scoped size for a diamond education and market context server. Each tool adds a distinct capability without redundancy or unnecessary bloat.
The surface covers the apparent domain well: definitions, search, size estimation, grading landscape, price index, report verification, and brand context. Minor gaps exist, such as no tool for comparing specific stones or more general buying guidance, but nothing creates a dead end for the core informational workflow.
Crystal meanings, healing properties, chakra and birthstone lookups for AI agents.
Live lab grown diamond inventory, engagement ring settings, fine jewelry, and diamond buying guides.
Precious metals AI analyst with 12 tools — prices, portfolio, chat, receipts, and more.
Options analytics for AI assistants: chains, IV rank, VRP, Greeks, GEX, expected moves, screeners.
