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 mark it read-only and idempotent; the description adds the matching order, the full entry contents, and the no-match fallback to nearest suggestions. This is meaningful behavioral context beyond the annotations and reveals no contradiction.

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, and the most important behavioral details are front-loaded. Every sentence contributes either to purpose, matching semantics, or return shape.

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 lookup, the description fully covers invocation and expected return behavior, including the no-match case. The absence of an output schema is compensated by the explicit list of returned fields.

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 100% schema coverage and a single documented `term` parameter, the baseline is 3. The description adds value by explaining the lookup algorithm (exact, then substring/alias) and the fallback behavior, which helps the agent predict what `term` will do.

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-resource pair: 'Look up a single diamond or gemology term in the encyclopedia...' and details what is returned. This clearly distinguishes `define` from broad siblings like `search_encyclopedia` by emphasizing single-term lookup.

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 establishes when to use the tool: for a single exact term, with a deterministic matching fallback to substring or alias. It does not explicitly name alternatives such as `search_encyclopedia` or say when not to use it, so it falls short of a 5.

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

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

The annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds value by specifying the kind of information returned (geometry, certificate wording, typical length-to-width ratio) and by clarifying that a Dutch Marquise is an elongated hexagonal cut, which helps set expectations for the tool's output without weakening the safety profile.

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 carry the core definition, the content details, and the classification example with no filler. The most distinctive identifying phrase is front-loaded and the supporting details are compact.

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 with no output schema, the description gives enough content detail for an agent to decide whether this tool answers a query about Dutch Marquise cut definitions. It is not exhaustive—e.g., it does not mention source publication or format—but nothing essential for invocation 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?

The tool has zero parameters, making detailed parameter documentation unnecessary. The empty input schema is fully consistent with a static definition-lookup tool, and the description does not invent parameters or leave any input ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies a specific resource—the published definition of the Dutch Marquise cut—and lists concrete content: geometry, certificate wording, and length-to-width ratio. It does not use an explicit verb like 'returns' or 'describes,' and its relationship to the sibling 'define' tool is not directly clarified, though the specialist scope is clear.

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 explicit guidance is given about when to call this tool instead of define, search_encyclopedia, or about_stienhardt. The intended use is only implied by the name and content hints, and there is no mention of the conditions that would make a sibling tool preferable.

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, so the safety profile is covered. The description adds the output fields but does not disclose additional behavioral details such as not-found handling or data freshness beyond what openWorldHint already implies.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One tightly written sentence with the core action front-loaded and every phrase earning its place. It avoids redundancy and gives the agent the essential information immediately.

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 retrieval tool, the description is complete: it identifies the id source, names the returned fields, and is backed by strong annotations and sibling context. No critical information needed to invoke the tool 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% and the single id parameter is already well documented with an example. The description confirms the id comes from search_inventory but otherwise adds little beyond the schema.

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') and enumerates the returned fields. It clearly distinguishes itself from search_inventory, which is the list-level sibling tool.

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 phrase 'as returned by search_inventory' tells the agent where the required id originates and implies this tool is the follow-up detail lookup. It does not explicitly state when not to use it, but the usage context is clear and sufficient for this simple retrieval 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 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful context beyond those flags: it emphasizes that results are 'real, in-stock' products from a 'live catalog' and clarifies the tool is not for appraisal or outside pricing. This is useful behavioral scoping, though it doesn't cover pagination or rate limits.

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 carry the full meaning: what the tool searches, what it returns, when to use it, and when not to. There is no filler or redundant restatement of the schema.

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 2-parameter tool with safety annotations and no output schema, the description is complete. It tells the agent the scope, the return payload essentials (products with prices and links), and the boundaries of appropriate use.

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 baseline is 3. The description adds value by giving concrete natural-language examples of how to phrase the query parameter, which helps an agent understand what 'plain words' should look like and what product types are relevant. The limit parameter is already fully documented in the schema, so no repetition is 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 opens with a specific verb and resource: 'Search Stienhardt's live catalog' of diamonds, settings, and fine jewelry. It also states what it returns (real, in-stock products with prices and links), which clearly separates it from siblings like search_encyclopedia and dutch_marquise_definition.

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 ('do you have a 2 carat Dutch Marquise', 'show me tennis bracelets') and an explicit exclusion ('Not for appraisal or price advice on stones sold elsewhere'). It does not name a specific alternative tool, but it provides enough contextual guidance for an agent to know when to invoke it.

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.