Perfume Picks

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds the core behavioral context: exactly what dimensions the comparison covers. It does not explain edge cases like missing fragrance data, but for a safe read-only comparison this is strong additional context.

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?

A single, tightly written sentence that front-loads the operation and then uses a colon-separated list to convey the comparison scope. No redundant words 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?

This is a low-complexity two-parameter tool with strong read-only annotations and no output schema. The description adequately conveys what the result will cover and the pair being compared. It lacks explicit alternativ routing, but the operation is clear 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?

The input schema already documents both parameters with 100% coverage, including that each accepts a slug or name. The description does not add parameter-specific details, which is acceptable since the schema carries the burden.

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 operation as a side-by-side comparison and enumerates concrete comparison dimensions: note pyramids, shared/distinct accords, longevity/sillage/compliment scores, concentration, and price difference. This distinguishes it from sibling tools like get_fragrance or find_similar, which are single-fragrance or similarity-focused 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 phrase 'side-by-side comparison' implies the tool should be used when a user wants to compare two fragrances, and the parameter names make the pair explicit. However, it does not mention when to prefer this over siblings like find_similar or find_dupes, nor any when-not conditions.

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 signal read-only, idempotent, non-destructive behavior, so the description adds meaningful context by explaining that results are curated, documented to smell like the original, and include match percentage and price comparison. This goes beyond the structured annotations and clarifies the curated nature of the data.

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 concise sentences deliver the purpose, key output details, and the user-facing trigger phrase with no filler. The main behavior is front-loaded and every word contributes to understanding.

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 one-parameter tool with no output schema, the description adequately explains what the tool returns: curated dupes, match percentage, and price comparison. Combined with the clear input schema and supportive annotations, nothing essential is missing for correct invocation.

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 covers the single parameter fully with a description ('Fragrance slug or name to find dupes for'), and schema coverage is 100%. The description adds no new parameter details beyond reinforcing that the input is a fragrance, so the baseline score of 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 clearly states the tool's function: find curated, cheaper fragrance dupes for a given original, with match percentage and price comparison. It also distinguishes itself from siblings like find_similar by emphasizing 'dupes' and the 'without the price tag' angle, making the intended use 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 gives a clear usage context: use this when someone asks for what smells like a fragrance at a lower price. It does not explicitly name alternatives or exclusion criteria, but the trigger phrase 'the answer to...' effectively routes the agent to this 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 disclose readOnly, idempotent, and not destructive, so the description does not need to restate those. It adds useful context that results come from a precomputed similarity ranking, but it does not describe return shape, pagination, or edge cases such as unknown fragrance slugs.

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 sentence conveys the core behavior and the ranking basis without filler. It is front-loaded with the main action and includes no redundant details.

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

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

For a low-complexity, read-only tool with fully documented parameters and safety annotations, the description is largely sufficient. It lacks only explicit alternative routing and a hint about the return value shape, which are minor for this simple tool.

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

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

The input schema documents both parameters with 100% coverage, so the description adds no additional parameter meaning. The phrase 'given one' matches the fragrance parameter, but the schema already defines slug/name and limit defaults.

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 that the tool returns fragrances most similar to a given fragrance, using a precomputed similarity ranking over notes and accords. This clearly identifies the verb and resource, though it does not explicitly call out sibling distinctions such as find_dupes or get_recommendations.

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: given a fragrance, find similar ones based on precomputed notes/accords similarity. There is no explicit guidance on when to choose this over find_dupes, get_recommendations, or search_fragrances, and no exclusions are 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no safety contradictions exist. The description adds meaningful scoping context by stating it returns a 'detailed record for one fragrance' and listing the output attributes, which clarifies the tool's behavior beyond a generic getter. It does not disclose edge-case behavior (e.g., handling of ambiguous names or not-found errors), but the annotations lower the bar.

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, each earning its place: the first lists the record's contents, the second specifies the input format. No filler or repetition of schema/annotation data.

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 with no output schema, the description covers both invocation (slug or name) and expected return contents (note pyramid, scores, MGRP). No critical information is missing for an agent to successfully call it, and annotations already provide the safety profile.

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 slug_or_name parameter with 100% coverage, so the baseline is 3. The description adds a concrete example ('Bleu de Chaanel') and clarifies that a slug must be a 'Perfume Picks slug', giving the agent a better sense of the accepted format than the schema's generic 'Fragrance slug or name'.

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 'Detailed record for one fragrance', which specifies the verb (get) and resource (fragrance) precisely. Listing the full note pyramid, accords, concentration, community scores, and MSRP distinguishes it from siblings like search_fragrances or compare_fragrances, which operate on lists or multiple items. This makes the tool's purpose 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 makes it clear this is for retrieving a single fragrance's detailed record, so an agent can infer when to use it: when a specific fragrance is already known. It does not explicitly name alternatives or say when not to use it, such as 'for browsing, use search_fragrances'. However, the contextual clue 'one fragrance' versus the sibling names implies the appropriate use case.

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 idempotentHint=true, so the safety profile is covered. The description adds that the result is a curated set of 'picks' rather than a full listing, which is a useful behavioral trait, but it does not disclose return format, ordering, or any limitations. This is modest added context beyond the 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 a single sentence that front-loads the core purpose ('Personalized fragrance picks') and packs examples into parentheticals. It is information-dense but organized and not bloated, though it is slightly long relative to the unique value it adds over 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?

With no output schema and no explicit differentiation from sibling tools, the description leaves gaps: it does not explain what the returned recommendations look like or when to prefer this over find_similar or search_fragrances. Parameter constraints are fully covered by the schema and read-only annotations, so the essential calling contract is present, but the contextual gaps keep this below a 4.

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%, with parameters like preferences, budget, occasion, and gender already described with examples. The description provides some clearer example values for occasion and preferences, but it largely repeats schema information and does not significantly reduce reliance on 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?

The description clearly states a specific verb—'picks' as in recommends—and resource, 'fragrance picks,' while specifying the personalization inputs (preferences, budget, occasion, gender). This distinguishes it from generic search siblings, though it does not explicitly name any alternative.

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 a user has note/accord preferences and optionally budget, occasion, or gender to get personalized fragrance suggestions. However, it offers no explicit when-to-use versus siblings like find_similar or trending_fragrances; the usage context must be inferred from the word 'personalized'.

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. The description adds useful behavioral context beyond that: it searches 13,000+ records and returns note pyramids, accords, and community wear scores with source attribution. It does not disclose ordering, pagination, or default 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?

Two sentences deliver the core purpose, the available filters, and the return contents with no wasted words. The action is front-loaded and every sentence 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 search tool with seven fully documented optional parameters and no output schema, the description sufficiently covers purpose, filters, and return content. Minor gaps like result ordering and default limit behavior are already addressed in the schema, so the description is largely complete.

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. The description lists filter dimensions already present in the schema (brand, family, gender, MSRP) but adds no extra meaning about query semantics, defaults, or filters beyond what the input 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 states a specific verb and resource: full-text search across the Perfume Picks fragrance database. The filter list and mention of returned note pyramids, accords, and wear scores clearly distinguish it from siblings like get_fragrance or find_similar.

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 use case is implied by 'full-text search' and the filter dimensions, but the description gives no explicit when-to-use or when-not-to-use guidance relative to sibling tools such as find_similar or get_recommendations. There are no named alternatives or exclusions.

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=false, covering the safety profile. The description adds valuable behavior beyond that: it discloses the fallback to catalog popularity when live activity data is unavailable and states that the method used is labeled in the response.

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 sentence packs the target resource, time window, fallback behavior, and response cue. It is concise and front-loaded, though the phrasing 'are adding to their wardrobes most over the last 30 days' is awkward, costing a point.

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 tool with zero required parameters and a single optional limit (max 10), the description covers the key runtime nuance—which data source was used—via the response label. Without an output schema, the agent still may not know the exact result shape, but the definition is adequate for correct invocation and interpretation.

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%, with the single 'limit' parameter fully documented (range, default, max). The tool description adds no parameter-specific meaning, but per the rubric baseline 3 applies when the schema handles parameter documentation.

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 a trending fragrances resource based on 30-day user activity, with a fallback to catalog popularity. It is distinct in substance from siblings like search_fragrances or get_recommendations, but the verb is only implied by 'users are adding... most' and no sibling is explicitly named, so it stops 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?

No guidance is given about when to choose this tool over siblings such as get_recommendations, what_to_wear_tonight, or search_fragrances. The fallback explanation describes tool behavior, not selection criteria, so an agent receives no help choosing among alternatives.

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 establish the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context by indicating that the result is a suggestion scored with community compliment, office-safety, and versatility data, which helps an agent set expectations about the output and recommendation logic.

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 front-loaded sentence with no filler, stating the purpose before listing input factors and examples. It is slightly dense with parenthetical examples, but every component contributes to tool selection and invocation.

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, read-only suggestion tool with all parameters optional and well-covered by the schema, the description is sufficient: an agent knows what inputs matter and what kind of output to expect. There is no output schema, but 'a fragrance suggestion' plus the scoring basis covers the essentials for a first call.

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

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

Schema coverage is 100%, and the schema already documents gender and season with useful descriptions. The description reinforces mood, occasion, and season as inputs and adds occasion examples, but it does not add significant semantics beyond what the schema already 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 clearly identifies the resource ('a fragrance suggestion') and the situational basis (mood, occasion, season), so an agent can understand what the tool produces. It does not explicitly differentiate from the sibling get_recommendations, but the 'for right now' framing and scoring criteria provide enough distinction for a 4.

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 a clear context for use: selecting a fragrance for the current moment based on mood, occasion, and season, with concrete occasion examples. It does not name alternatives or exclusions, but the situational trigger is reasonably explicit and actionable.

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