Ada Diamonds

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

Discloses several non-obvious behaviors beyond the annotations: no card data passes through the agent, the link expires after 24 hours, no credential is needed, and sandbox mode simulates the link without creating a Stripe session. These are meaningful side-effect and environment semantics that annotations (readOnlyHint=false, destructiveHint=false) do not cover.

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?

Five sentences, front-loaded with the core purpose, and each subsequent sentence adds a distinct fact (item source, cart rule, shipping need, expiry, sandbox/production behavior). No 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?

Covers everything an agent needs to call correctly: item id source and composition, required shipping input, env flag semantics, expiry, credential requirements, and the safety note about card data. The output schema handles return-value documentation, so nothing is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds mild reinforcement: "a complete ring is one setting plus one diamond" and "Needs the shipping address (prices tax and shipping into the link)", clarifying the relationship between items and shipping_address. Most param detail already lives in the schema, so the added value is limited but present.

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: "Assemble a cart and get a Stripe-hosted checkout URL the customer opens to pay." It clarifies scope (hosted checkout, no card data through the agent) and distinguishes itself from the search siblings by noting item ids come from them.

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 clear context for when to call: build a cart from search tool ids, require a complete ring as one setting plus one diamond, and provide the shipping address for tax/shipping pricing. It also specifies the env condition (pass "production" only when the customer actually wants to buy). It does not name an explicit alternative or when-not-to-use, though the purpose is sufficiently distinct from 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 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, covering the safety profile and open-world nature. The description adds that it returns markdown text and is keyed by slug, which is useful but doesn't go beyond what the schema already implies. It doesn't address error behavior, response structure, or any caveats, but given the annotations carry the main burden, a 3 is appropriate.

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

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

Two sentences, no filler. The core action and the routing hint are both front-loaded. 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?

The tool has a declared output schema, so the return format is handled. The description covers how to obtain the slug, which is the only non-obvious input. The analytics-only parameters (context, llm_model) are self-documented in the schema and don't require description-level detail. Nothing an agent needs to invoke this 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 all four parameters have detailed descriptions in the input schema. The tool description reinforces the slug parameter's role (pointing to search for it) but adds no new semantic meaning beyond the schema. Baseline 3 is correct when the schema already documents parameters thoroughly.

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 ('Fetch'), a precise resource ('full markdown text of one Ada Diamonds knowledge base article'), and the key discriminator ('by slug'). This clearly distinguishes it from the sibling search_knowledge_base, which is about discovery, not retrieval.

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 instructs the agent to 'Use search_knowledge_base first if you don't know the slug', providing clear routing to the appropriate sibling when the slug is unknown. This is direct and actionable guidance on when to use this tool versus the alternative.

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 indicate this is a non-read, non-destructive operation. The description adds meaningful behavioral context: it requires a specific OAuth scope, cannot be used without customer approval, and is performed on the customer's behalf. It also implicitly warns about authorization failure. It does not describe side effects (e.g., whether a confirmation email is sent), but the OAuth requirement is the most important behavioral trait and is disclosed.

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 and front-loads the core action and the critical authorization requirement. It is concise and every sentence earns its place. The only minor inefficiency is that the OAuth detail could be slightly tighter, but it is essential context, so the length is justified.

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 complexity (10 params, 1 enum, output schema present), the description covers the most critical operational constraints: authorization, the analytics-only nature of `context` and `llm_model`, and the `conversation_id` sequencing rule. The output schema exists, so return values need not be described. A small gap is that it doesn't mention what happens after submission (e.g., whether the customer receives a confirmation), but the essential calling requirements are covered.

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

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

Schema coverage is 100%, so the schema already documents all 10 parameters. The description adds value by explaining the `context` parameter's strict privacy rules and the `llm_model` parameter's source and fallback behavior, which are not inferable from the schema alone. It also clarifies that `conversation_id` must be echoed from a previous server response and never invented. This goes beyond the schema's basic 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 states a specific verb ('Submit'), a clear resource ('a consultation request'), and the actor ('on the customer's behalf'). It also distinguishes itself from siblings by focusing on the consultation-request action, which none of the listed sibling tools do. The title reinforces the purpose without being a tautology.

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 states a prerequisite (the `appointments:write` scope via OAuth) and that the tool cannot be used without explicit customer approval. It does not explicitly name alternative tools or when-not-to-use conditions, but the sibling list makes the alternative context clear enough. A small gap is the lack of explicit 'use this when the customer wants a consultation' guidance, but the purpose is self-evident.

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 adds value by disclosing that results are 'currently available stones' (live inventory), that it returns grading report numbers and product URLs, and that MCP Apps hosts render results as an interactive card grid. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences and front-loads the core purpose and scope. The first sentence is dense but efficient. The second sentence gives a clear usage cue. The third sentence about MCP Apps is useful but slightly tangential to the core invocation logic; it earns its place as behavioral context but could be trimmed. Overall, 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 search tool with 13 parameters, 100% schema coverage, an output schema, and read-only annotations, the description covers the essential invocation context: what is searched, what filters apply, what results contain, and when to use it. The only minor gap is that it doesn't explain the default sort behavior beyond what the schema already states, but the schema covers that. The description is complete enough for an agent to select and 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?

Schema description coverage is 100%, so the schema already documents all 13 parameters. The description adds a little context by naming the filter dimensions (shape, carat, price, color, clarity, cut) and noting the sort default ('price_asc (default relevance)'), but it doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Search'), a specific resource ('Ada Diamonds' live loose lab grown diamond inventory'), and enumerates the filter dimensions (shape, carat, price, color, clarity, cut). It also distinguishes itself from siblings by focusing on loose lab-grown diamonds and budget-based queries, which separates it from search_engagement_rings and 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 explicitly says 'Use this for any question about what diamond a budget can buy,' which gives clear context for when to invoke it. It doesn't explicitly name alternatives or exclusions, but the sibling list and the phrase 'loose lab grown diamond inventory' imply when other tools (e.g., search_engagement_rings, search_jewelry) would be more appropriate. A clear when-to-use is present, but no explicit when-not-to-use.

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 useful private behavior: results are setting-only with prices excluding diamonds, and rendering may become an interactive card grid in MCP Apps-enabled hosts. 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?

Three sentences, each earning its place: purpose and filters, price-scope caveat with sibling pairing, and the MCP Apps rendering note. The core action is front-loaded with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter tool, the description covers the key domain decision logic (settings vs. complete ring, pairing with search_diamonds) while the full schema documents every parameter and an output schema exists. The only minor gap is no guidance on the analytics-only parameters (context, llm_model), but those are fully described in the schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description additionally clarifies that min_price and max_price values exclude the center diamond, which is meaningful domain semantics beyond the raw schema text, and it ties shape/style/price to the search behavior.

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 Ada Diamonds' engagement ring settings," and enumerates the filter dimensions (shape, style, price), immediately distinguishing it from sibling tools like search_diamonds and search_jewelry. It clearly identifies this as the settings-specific search, not a general jewelry query.

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 concrete usage context: settings prices exclude the center diamond and should be paired with search_diamonds for a complete ring quote. It does not explicitly state when not to use this tool or name alternative searches by condition, but the pairing guidance and scope are enough for an agent to route correctly.

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, covering safety and dynamic results. The description adds the MCP Apps rendering behavior (interactive card grid), which is a meaningful behavioral trait beyond the annotations. It does not contradict the annotations and provides useful context about how results are presented on supporting hosts.

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 front-loads the core purpose and filter scope, the second adds a value-added rendering note. No wasted words or redundancy. The description earns its space 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?

The tool has an output schema, so return format is already defined. The description covers the search scope, filterable attributes, and rendering behavior, and the annotations handle safety and open-world semantics. It does not explicitly explain pagination via conversation_id, but that is documented in the schema; overall it is complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description adds a summary of the main filter dimensions (category, type, diamond shape, price) that map to existing schema fields, but it does not add syntax, formatting, or behavioral nuance beyond what the schema provides. This meets the baseline but adds little extra meaning.

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' with a clear resource ('Ada Diamonds' fine jewelry') and enumerates the item types (wedding bands, earrings, necklaces, bracelets, fashion rings) plus the filtering dimensions (category, type, diamond shape, price). This makes its scope distinct from siblings like search_diamonds (loose diamonds) and search_engagement_rings (a subset), even though it doesn't name them explicitly.

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 is for finished fine jewelry pieces rather than loose diamonds or specific subsets, but it does not explicitly state when to use it versus siblings such as search_diamonds or search_engagement_rings. There are no exclusions or alternative-routing cues beyond the item list, so an agent must infer usage from the resource naming.

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 agent knows this is a safe, non-mutating search. The description adds that it returns article summaries and markdown URLs, which is useful behavioral context beyond the annotations. However, it doesn't disclose pagination behavior, result ordering, or what happens with no results. With annotations covering the safety profile, a 3 is appropriate.

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 waste. The first sentence front-loads the tool's purpose and scope, and the second provides a clear pointer to the sibling tool for the next step. 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?

The description is complete for a search tool: it states what it searches, what it returns (summaries and markdown URLs), and how to get full text. The output schema exists, so return values don't need explanation. Minor gaps like result ordering and pagination are not critical for an agent to invoke this tool correctly. The only slight gap is not explicitly distinguishing from search_diamonds, but the topic scope makes it 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 description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds context about what 'query' matches against (article titles, summaries, and slugs) and that results include summaries and URLs, which slightly enriches the schema. But the description doesn't add meaning beyond what the schema provides for the other parameters (context, llm_model, conversation_id, limit). Baseline 3 is correct when schema does the heavy lifting.

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 ('Search'), a specific resource ('Ada Diamonds' published guides on lab grown diamonds'), and enumerates the covered topics (4Cs, CVD vs HPHT, shape guides, certification, buying advice). It also distinguishes itself from read_article by noting it returns summaries and URLs while read_article provides full text. This clearly differentiates it from siblings like search_diamonds and search_engagement_rings.

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

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

The description explicitly says to use read_article to get an article's full text, which provides a clear alternative for a follow-up action. It implies this tool is for finding/summarizing articles rather than reading them fully. However, it doesn't explicitly state when NOT to use this tool versus other search siblings (e.g., search_diamonds for product searches), though the topic scope makes this reasonably clear.

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