Ada Diamonds

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

Annotations only say readOnly=false and destructive=false; the description adds materially more — no card data touches the agent, links expire after 24 hours, no credential required, and a full disclosure that without a production credential the tool silently degrades to a simulated sandbox link with no Stripe session. That last point is exactly the kind of trap an agent needs warned about.

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?

Front-loaded with the action and outcome, then scoping details. It is dense but nearly every clause carries decision-relevant information; the env explanation partially duplicates the already-thorough schema field description, which is the only real 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?

For an 8-parameter mutation tool with nested objects and a production/sandbox fork, the description covers inputs, prerequisites, degradation behavior, and lifetime. Output schema exists, so return-value detail is correctly omitted.

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 goes beyond the schema by explaining item id namespacing and the ring-composition rule (one setting + one diamond) plus why shipping_address is required (tax and shipping pricing), which the schema only partly conveys.

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?

Opens with a concrete verb and resource: assemble a cart, return a Stripe-hosted checkout URL. It also states the negative scope ('no card data passes through the agent'), which immediately separates it from the search_* siblings and from request_consultation.

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?

Explicitly names where item ids come from (the search tools, with id formats), states that a complete ring is one setting plus one diamond, requires a shipping address, and gives a decision rule for env: 'Pass env: "production" when the customer actually wants to buy.' When-to-use and how-to-choose are both spelled out.

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, so the safety profile is covered. The description adds no additional behavioral context such as rate limits, auth requirements, or side-effect warnings, which is acceptable given the read-only annotation.

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 with zero filler. The content list is front-loaded, and the usage guidance closes the description efficiently 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?

The description covers purpose and usage boundary, the output schema covers return structure, annotations cover read-only behavior, and the schema covers all parameters. Nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully explains context, section, llm_model, and conversation_id. The description adds high-level content domains but does not enrich parameter meaning 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 specific content categories (contact, showroom hours, consultations, what the company sells) and explicitly contrasts with product questions, distinguishing it from sibling search tools. An agent can immediately tell this is the business-information 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 description gives explicit usage direction: use for business questions rather than product questions. It does not name the alternative search_* siblings, but the 'rather than about a product' phrasing clearly implies the boundary.

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 openWorldHint=true, so the safety profile is covered. The description usefully adds the return format (full markdown text), but says nothing about failure behavior for missing/invalid slugs or rate limits. Adequate but not rich beyond structured fields.

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

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

Two sentences, front-loaded with the core action and followed by the alternative-routing guidance. Zero 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?

A simple read tool with an output schema, 100% schema coverage, and annotations covering safety. Purpose, input sourcing, and alternative routing are all present; nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema documents all four parameters including the slug's provenance and the analytics params. The description reinforces that the slug comes from search_knowledge_base, but adds no syntax or format detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (fetch), resource (one Ada Diamonds knowledge base article), scope (by slug), and return format (full markdown text). An agent can distinguish it from search_knowledge_base without opening either schema.

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?

Explicitly names the alternative (search_knowledge_base) and the condition that selects it ("if you don't know the slug"). Nothing about when to call this vs the sibling 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.

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

Beyond the annotations, the description adds critical behavioral context: the tool requires the `appointments:write` scope and cannot be used without the customer's explicit OAuth approval. It does not contradict the annotations, though it could say more about what happens after submission.

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 focused sentences with zero waste. The purpose is front-loaded, followed immediately by the authorization prerequisite.

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 rich schema coverage, annotations, and an output schema, the description provides enough context for correct invocation. Its only meaningful gap is the absence of explicit guidance on when to use this tool versus sibling search or checkout tools.

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 all 10 parameters, including required fields and the enum for `topic`. The description adds no parameter-specific meaning beyond what the schema provides, making the baseline 3 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: 'Submit a consultation request on the customer's behalf.' This clearly identifies the action and object, though it does not explicitly distinguish the tool from siblings such as create_checkout_link or search_jewelry.

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 usage by saying it submits a consultation request on the customer's behalf, and it adds an important OAuth prerequisite. However, it does not state when to choose this tool over alternatives or when not to use it, leaving routing guidance largely implied.

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 openWorldHint, so the safety profile is covered. The description adds genuinely new behavior: it returns live available stones with grading report numbers and product URLs, and it discloses MCP Apps host rendering into an interactive card grid — a trait not visible in any structured field.

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: capability and filters first, return shape second, usage and host-rendering note last. No filler, and the most decision-relevant content 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?

With 13 params, full schema coverage, an output schema, and annotations, the description covers purpose, return content, usage, and UI behavior adequately. It omits any mention of pagination/limit behavior and the analytics-only context/llm_model parameters, but the schema fully documents those, so the gap is minor.

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 all 13 parameters, including enums and limits, are already documented in the schema. The description restates the filter dimensions (shape, carat, price, color, clarity, cut) without adding format, default, or interaction details beyond what the schema 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?

States a specific verb and resource ('search ... live loose lab grown diamond inventory') and enumerates the filterable dimensions, which implicitly separates it from search_jewelry and search_engagement_rings. It stops short of an explicit contrast with those siblings, leaving some ambiguity for a query like 'find a diamond ring under $5k'.

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?

'Use this for any question about what diamond a budget can buy' gives a clear positive usage condition tied to budget-driven browsing. No exclusion is given for when to prefer the ring/jewelry siblings instead, so the routing is clear but not complete.

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?

Goes beyond the readOnly/openWorld annotations by disclosing the price-composition rule (setting only, no center stone) and the rendering behavior on MCP Apps hosts (interactive card grid). Missing items: pagination limits and what conversation_id enables, though the schema covers the latter.

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: purpose first, then the commercial caveat and pairing, then the rendering note. Nothing redundant or padded.

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?

An output schema exists and return values don't need explaining; the description still flags the card-grid rendering, which helps set expectations. Combined with annotations and full schema coverage, an agent has enough to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all ten parameters are self-documented; the description's price-exclusion note largely repeats what min_price/max_price already say. No added meaning for q, type, shape, or style 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?

Names a specific verb and resource ('search engagement ring settings') plus the discovery axes (shape, style, price), which separates it from search_diamonds and the broader search_jewelry. An agent can route to it without opening the schema.

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?

Explicitly states the pairing pattern: setting prices exclude the center diamond, so quote a complete ring via search_diamonds. That is clear context, but there is no explicit 'use this instead of search_jewelry when...' exclusion.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower. The description adds a genuinely non-structured behavioral trait: hosts supporting MCP Apps render results as an interactive card grid, which affects how the agent should present the response. It does not mention result caps/pagination beyond the schema, but the schema already states the 1-50 limit.

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

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

Two sentences, zero filler, and the core purpose plus covered product families are front-loaded before the rendering caveat. Nothing repeats the title or 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?

An output schema exists, so return-value explanation is not needed, and the annotations and 100% schema coverage carry most of the remaining burden. What is missing is disambiguation from sibling search tools and any note on result ordering or empty-result behavior, which matters for a 10-parameter search with openWorld semantics.

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 baseline is 3; every parameter including the unusual context/llm_model/conversation_id contract is fully documented in the schema. The description only echoes the facet names (category, type, diamond shape, price) without adding format or matching semantics beyond what the schema says.

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 ('Search Ada Diamonds' fine jewelry') and enumerates the product families covered plus the filter dimensions. It never distinguishes itself from the close siblings search_diamonds and search_engagement_rings, so the boundary of 'jewelry' versus 'loose stones' or 'engagement rings' is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the listed facets (category, type, shape, price) which tells the agent this is the faceted catalog-search tool. There is no explicit when-to-use/when-not guidance, and with three overlapping search siblings in the tool list, the agent gets no rule for choosing among them.

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 openWorldHint, so safety is covered; the description adds that results are summaries plus markdown URLs rather than full content, which is a real behavioral constraint driving the read_article handoff. It adds nothing about ranking, coverage limits, or empty-result 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 short sentences with zero filler: what it searches, what it returns, and where to go next. The most decision-relevant information (scope of content) 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?

An output schema exists so return values need no explanation, and annotations cover the safety profile; the description still supplies the one thing the structured data cannot — that this is a summaries-only index paired with read_article. Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, including limit bounds and the oddly specific context/llm_model/conversation_id requirements, so the schema carries all parameter meaning. The description only implies that the query is topical, adding no syntax, matching behavior, or query-construction guidance 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?

States a specific verb (search) and a precisely bounded resource (Ada Diamonds' published guides), then enumerates the content domains covered — 4Cs, CVD vs HPHT, shapes, certification, buying advice. This clearly separates it from the product-oriented siblings like search_diamonds and search_jewelry without the agent needing to open schemas.

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?

Gives an explicit next-step rule: use read_article to get an article's full text, which tells the agent when this tool's output is insufficient. It lacks an explicit exclusion statement for the other search_* siblings (diamonds, jewelry, rings), relying on the content-domain wording to imply the split.

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