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

Annotations already declare the tool is read-only, idempotent, and non-destructive, which covers the main behavioral risks. The description adds value by disclosing what the comparison returns: note pyramids, accords, longevity/sillage/compliment scores, concentration, and price difference.

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, well-structured sentence that fronts the core operation and then lists what the comparison covers. There is no redundant or speculative content.

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 two-parameter, read-only comparison tool, the description is complete enough: it names the output dimensions, and the annotations plus schema cover the safety and input details. There is no output schema, so the explicit field list in the description effectively compensates for that gap.

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?

Both parameters are fully described in the schema as 'slug or name', so schema coverage is 100%. The description confirms that the two inputs are fragrances but does not add any significant parameter-level 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?

The description names a concrete operation with a specific verb and resource: a side-by-side comparison of two fragrances. It also specifies the comparison dimensions, making it clearly distinct from sibling tools like get_fragrance, find_similar, and find_dupes.

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 that the tool is appropriate when the user wants to compare exactly two fragrances. However, it does not explicitly say when not to use it or point to alternatives such as find_similar for one-to-many or find_dupes for duplication-oriented comparisons.

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 read-only, idempotent, non-destructive behavior. The description adds useful context about curatorship and price/match output but does not describe result structure, limits, or fallback behavior, so a middle score 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 front-loaded sentences with no redundancy. The core purpose comes first, and the 'without the price tag' framing adds useful orientation without padding.

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 report-only tool, this is mostly complete. It communicates the return theme (dupes with match percentage and price comparison), though an explicit format or example would make it fully self-contained.

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%: the parameter already states it accepts a fragrance slug or name. The tool description does not add additional parameter-level meaning, so it relies on the schema to carry this dimension.

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 action and resource: finding curated, cheaper smell-alikes for a fragrance. The description clearly separates this from general similar-fragrance lookups by emphasizing documented dupes and price comparison.

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 maps to the use case: 'what smells like X without the price tag.' It does not formally name alternatives or say when not to use the tool, but the context is clear 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 provide the read-only, idempotent, and non-destructive safety profile. The description adds meaningful behavioral context by explicitly stating that results come from a precomputed similarity ranking over notes and accords, implying the response is not dynamically generated.

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, dense sentence that fronts the core behavior and follows with only the essential source detail. Every word earns its place and there is no filler or repetition.

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 tool with complete schema descriptions, the tool's core behavior and data source are adequately described. The only notable gap is the lack of explicit disambiguation against 'find_dupes' and 'get_recommendations', which could matter for tool selection.

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 both 'fragrance' and 'limit' are already documented. The description only reinforces that a single source fragrance is the anchor input. It does not add any extra meaning about the limit behavior or expected input format.

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 returns fragrances most similar to a given one, and adds the distinguishing source ('precomputed similarity ranking over notes and accords'). It does not explicitly contrast with the similarly named sibling 'find_dupes', so it falls just short of full differentiation.

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: provide a given fragrance and get similar fragrances from a precomputed ranking. There is no direct guidance on when to choose this over siblings like 'find_dupes' or 'get_recommendations', and no explicit exclusion criteria.

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 communicate read-only, idempotent, non-destructive behavior. The description goes further by specifying the exact return contents, which compensates for the missing output schema, and it also discloses that names, not only slugs, are acceptable inputs — a behavior an agent could not infer from the schema alone.

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, information-dense sentences front-load the output content before the input format. Every word contributes to operational success; there is no filler, repetition with the schema, or irrelevant formal language.

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 one-parameter read operation with no output schema, the description provides everything needed to call it correctly: what input to supply, what format it accepts, and exactly what fields the returned record will contain. The tool's simple scope means no additional setup, prerequisite, or postcondition disclosure is necessary.

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 names the parameter 'slug_or_name' and describes it, so baseline is 3. The description adds meaningful value by specifying a 'Perfume Picks slug' and giving the concrete example 'Bleu de Chanel', which clarifies formatting, exact-match expectations, and the acceptable vocabulary for the identifier.

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 names a specific resource ('detailed record for one fragrance') and enumerates its distinct content (note pyramid, accords, concentration, community scores, MSRP). It clearly differentiates from sibling tools like search_fragrances by emphasizing lookup-by-slug-or-name of a single item rather than discovery or comparison.

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 for when to use the tool: when you have a specific fragrance slug or name and need the full detailed record. It does not explicitly say when not to use it or name alternatives, but the 'one fragrance' framing combined with the accepted inputs implies it is for bounded lookup operations rather than broader exploration.

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, so the safety profile is covered. The description adds the input scope of recommendation but does not describe response shape, ranking behavior, or side effects, and there is no output schema to fill that gap.

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, front-loaded with the main behavior, and packs parameter semantics through compact examples. Each phrase adds meaning without raw repetition 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 read-only, idempotent recommendation tool with a small required parameter set, this description is mostly complete: it explains the recommendation basis and optional dimensions. Without an output schema, a brief note on the returned list structure would be helpful, but 'fragrance picks' already implies the general shape.

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?

Since schema description coverage is 100%, the schema already owns formal parameter documentation. The description adds useful gloss by giving concrete values for preferences, budget units, and occasion examples, which helps an agent form realistic call payloads.

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 task: returning personalized fragrance picks based on taste preferences, budget, occasion, and gender category. It distinguishes this from the sibling search, dupe, similar, and trending tools by centering on recommendation-style filtering by personal context.

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 use case and names the relevant inputs: notes, budget, occasion, and gender. It does not explicitly tell an agent when not to use this tool or name sibling alternatives, but the personalization angle makes the intended context reasonably obvious.

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 indicate a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds useful behavioral context by naming the catalog size, filterable dimensions, and return content (note pyramids, accords, community wear scores, source attribution), but it does not disclose deeper behavior like matching semantics or edge cases.

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 compact two-sentence structure: an action-oriented opening followed by filter detail and return-value detail. Every sentence adds information 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?

Given 7 optional parameters, full schema coverage, and no output schema, the description provides meaningful context about scope and result content. It is missing some explicit guidance on query behavior when no filters are provided, but it is otherwise complete enough for an agent to decide whether to invoke this search 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?

All 7 parameters have descriptions in the input schema, and schema coverage is 100%. The description briefly restates common filters like brand, fragrance_family, gender, and MSRP, but it neither conflicts with the schema nor adds meaning beyond it, 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 opens with 'Full-text search across 13,000+ fragrances in the Perfume Picks database', naming the exact verb, resource, and scope. It also lists filters and return fields, making it clearly distinct from sibling tools 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 description says this is for full-text search with filters, which implicitly identifies a general search use case. However, it never explicitly states when to prefer this over alternative sibling tools such as find_similar or get_recommendations, leaving some selection burden on the agent.

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 the operation is readOnly, idempotent, and non-destructive. The description adds meaningful behavioral detail beyond those annotations, including the fallback to catalog popularity when live data is unavailable and the fact that the chosen method 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?

The description is a single tight sentence that includes key details with no filler. The sentence reads slightly awkwardly, but it is efficient and front-loaded with the core concept.

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 tool with only one optional parameter, the description covers the data source, time window, fallback behavior, and response labeling. While there is no output schema, the basic return type is clearly implied, and the annotation covers 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 input schema has full coverage for the only parameter, 'limit', including its min, max, default, and description. The tool description adds no additional meaning about the parameter, 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 identifies the resource (fragrances) and the specific ranking signal (fragrance users are adding to their wardrobes over the last 30 days), so an agent can understand what is returned. It doesn't include an explicit verb like 'lists' and does not directly name siblings, but the title and content together make the 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 provides useful context about when the data is available and when it falls back to catalog popularity, but it never explicitly states when to choose this tool over the other fragrance tools. Usage is implied by the word 'trending' and the 30-day framing, not explicitly defined.

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, and non-destructive behavior, so the safety profile is covered. The description adds value by revealing that recommendations are scored with community compliment, office-safety, and versatility data, but it does not explain potential output variations or edge 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?

A single, front-loaded sentence expresses the tool's purpose, decision inputs, and scoring context. It includes helpful examples without lengthy padding, making it easy for an agent to scan.

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 explains the reason for being and the key decision variables, and it notes the data source behind scoring. However, with no output schema, it does not clarify whether the response is a single fragrance, a ranked list, or requires additional follow-up, which would help an agent set expectations.

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 parameters are already documented at the schema level. The tool description reinforces the spirit of occasion and season with examples, but it does not add any required meaning beyond what the schema already states.

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 presents the tool as a time-sensitive fragrance suggestion driven by mood, occasion, and season. It distinguishes itself from search/get/similar siblings by emphasizing 'for right now', but it does not use an explicit verb like 'recommends' and does not name the most similar sibling, 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?

The occasion examples ('date', 'office tomorrow', 'night out', 'cozy evening in') and the 'right now' framing signal when this tool should be used. It does not explicitly state when not to use it or draw a contrast with get_recommendations, but the intended context is clear enough for an agent to spend some time.

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