Perfume Picks

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so safety is covered. The description adds real value beyond that by disclosing the comparison output surface (note pyramids, shared/distinct accords, performance scores, concentration, price delta), which matters since there is no output schema.

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 that names the operation first and then the comparison dimensions. No filler, no repetition of the title, every clause 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?

With no output schema, the description usefully enumerates what the comparison returns and the parameters are fully documented, so an agent can call it correctly. Minor gaps: behavior on unresolvable or identical inputs is unspecified.

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%: both parameters are documented as 'slug or name'. The description adds nothing about how inputs are resolved (e.g., ambiguous names, invalid slugs), so the 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 and resource ('side-by-side comparison' of two fragrances) and enumerates the compared facets, so the agent knows exactly what it produces. It does not explicitly distinguish itself from close siblings like find_similar or find_dupes, leaving that differentiation to inference.

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 never states when to choose this tool over find_similar, find_dupes, or get_fragrance. A user asking 'how do these two stack up' is implied, but no alternatives or conditions are named, so the agent gets no routing guidance.

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 readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuinely new behavior: results are a curated set, each with a match percentage and price comparison, which tells the agent what kind of data to expect. It does not cover coverage limits (how many dupes, curation criteria), so it stops short of a 5.

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 first defines the resource and payload, the second delivers the usage trigger. Front-loaded and every clause 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 one-parameter, no-output-schema tool, the description carries the burden of explaining the return shape (dupes, match percentage, price comparison) and does so. Nothing an agent needs 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 coverage is 100% and the single 'fragrance' parameter is fully documented as a slug or name. The description adds no format or matching guidance beyond what the schema already supplies, so the 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+resource ('dupes for a fragrance') and describes the payload — cheaper smell-alikes with match percentage and price comparison. It implicitly distinguishes itself from find_similar by emphasizing 'cheaper' and 'documented to smell like', but never names the sibling explicitly, so an agent must infer the boundary.

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 user-intent trigger: "Use for 'what smells like X but costs less' questions." That is clear when-to-use guidance, but there is no when-not guidance and no pointer to find_similar or compare_fragrances for the adjacent cases.

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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is fully covered elsewhere. The description adds real value by revealing that results come from a precomputed note/accord similarity ranking (implying deterministic, non-generative output), but says nothing about result format, ordering guarantees, or what happens for an unknown slug.

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 tight sentence with the core purpose front-loaded and the methodological qualifier trailing it. Nothing is redundant and nothing needs trimming.

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, the description should say what a result looks like (slugs, names, similarity scores, whether the source fragrance is included), and it does not. The core intent and the similarity basis are present, so it is adequate but leaves an agent guessing about the response 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?

Schema description coverage is 100%, so both 'fragrance' and 'limit' are already documented, including the default of 5 and the cap of 10. The description adds no parameter meaning beyond that, which is the baseline case for fully-covered schemas.

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 resource ('fragrances most similar to a given one') and even the mechanism ('precomputed similarity ranking over notes and accords'), which is more than most siblings offer. It stops short of contrasting with near-neighbors like find_dupes or get_recommendations, so an agent must still infer the boundary itself.

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?

There is no when-to-use or when-not-to-use guidance and no named alternative, despite three plausible siblings (find_dupes, get_recommendations, compare_fragrances) that an agent could confuse this with. The one differentiating clue, 'similar by notes and accords', is buried as a methodology note rather than routing advice.

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 and repeatability profile is fully covered by structured fields. The description adds useful scope context by enumerating the record's contents, but does not go beyond that with auth needs, rate limits, or failure behavior (e.g., what happens if the slug is unknown).

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 that leads with the return payload and follows with acceptable inputs. Every clause earns its place, with no filler or redundant restatement.

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

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

For a single-parameter read-only lookup with a rich return payload, the description is nearly complete: it scopes the resource and enumerates the record contents. It lacks only explicit when-to-use-vs-siblings guidance and failure-mode documentation, which are minor for such a straightforward 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?

Schema description coverage is 100%, so the single parameter 'slug_or_name' is already documented in the schema. The description does add a concrete example ('Bleu de Chanel') and clarifies the two accepted formats, which marginally exceeds the schema's terse 'Fragrance slug or name', but the baseline of 3 is appropriate when the 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?

States a specific verb (get) and resource (fragrance) and enumerates the payload returned: note pyramid, accords, concentration, community scores, MSRP. This crisply distinguishes it from siblings like search_fragrances and compare_fragrances, which operate on sets rather than fetching one record.

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 a single-record lookup and even explains accepted input forms (slug or name like 'Bleu de Chanel'), which helps callers know what to feed it. However, it never explicitly states when to use this versus alternatives such as search_fragrances for discovery or compare_fragrances for side-by-side comparisons, so the agent must infer the routing.

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 readOnly, idempotent, non-destructive and closed-world behavior, so safety is covered. The description adds no behavioral context beyond that: it does not say how results are ranked, what happens when preferences match nothing, whether the result set is capped, or whether the catalog is limited to what is in stock.

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 that names the resource first, then the driving inputs. No filler sentences, though the inline enumeration of examples makes it denser than necessary when the schema already contains examples.

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 five-parameter, one-required, read-only recommendation tool with full annotation coverage and no output schema, the description covers the semantics of four of five inputs and conveys the return shape ('picks'). Missing only any statement about how many or what kind of results come back.

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 five parameters with types, enums, ranges and defaults. The description's examples ('vanilla', 'oud', 'citrus') clarify intent for preferences but roughly duplicate the schema's own examples, and it omits the limit parameter entirely; with the schema doing the heavy lifting, baseline 3 is correct.

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 verb (get/pick) and resource (fragrance recommendations) and enumerates the signals that drive personalization. It is clearly distinguishable from generic search_fragrances, but never names a sibling or explains the boundary against find_similar, trending_fragrances, or what_to_wear_tonight.

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 only implied: the listed inputs (preferences, budget, occasion, gender) suggest this is the tool for taste-driven discovery rather than lookup or comparison. There is no explicit when-to-use, when-not-to-use, or routing to the sibling tools that also surface fragrances.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real value beyond that: it discloses the return payload (note pyramids, accords, community wear scores with source attribution) and states that MSRP is USD, which nothing in the structured fields supplies.

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 catalog scope, followed by filters and return content. No filler, no 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?

With no output schema, the description usefully covers return contents, and annotations cover safety, so an agent can call it informed. Minor gaps remain — no ranking/relevance behavior and no mention of the hard 10-result cap's effect on result 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%, so all seven parameters are already documented in the schema, and the description only restates the filter set (brand, family, gender, MSRP). Baseline 3 is appropriate; no format or matching-behavior detail is added.

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 ("Full-text search across 10,000+ fragrances") plus the catalog scope, so the agent knows exactly what it retrieves. It does not, however, contrast itself against near-neighbors like find_similar or get_fragrance, whose purposes overlap at a glance.

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 lists available filters but gives no when-to-use guidance and names no alternatives, despite several siblings (find_similar, find_dupes, get_recommendations, trending_fragrances) that could plausibly be chosen instead. The agent has to infer that this is the keyword-search entry point.

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 readOnly, idempotent, non-destructive, and closed-world. The description adds genuinely new behavioral context: it discloses the fallback to catalog popularity when live activity data is unavailable, and that the method used is labeled in the response. That is real disclosure 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?

A single sentence, front-loaded with the core behavior and the fallback qualifier appended only where needed. No filler or restated field names.

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-only list tool with no output schema, the description covers what the list is, how it is derived, and the fallback behavior. It is essentially complete, with only the ranking/order and result shape left implicit.

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

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

There is only one parameter (limit) and schema description coverage is 100%, so the schema fully documents it. The description adds nothing about the limit or its default/cap, which is the expected baseline when the 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 names a specific resource (fragrances trending among Perfume Picks users) and a concrete scope (last 30 days, add-to-wardrobe activity), so the agent knows exactly what this returns. It stops short of naming which sibling it replaces (e.g. get_recommendations), so it is clear but not fully differentiated.

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?

There is no statement of when to prefer this over get_recommendations, search_fragrances, or what_to_wear_tonight. The usage context is only implied by the word 'trending', leaving the agent to infer routing on its own.

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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is settled. The description adds real behavioral value by disclosing that results are scored against community compliment, office-safety, and versatility data, which is the only signal about what the output contains since no output schema exists.

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 with the core purpose front-loaded and no filler. It runs long, but each clause (inputs, examples, scoring source) carries information rather than 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 read-only, all-optional suggestion tool with no output schema, the description covers the inputs, gives occasion examples, and explains how the pick is scored. The remaining gap is routing relative to sibling recommendation tools, which the agent cannot resolve from this text alone.

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 four parameters are already documented, and the enum values for gender and season are self-explanatory. The description adds richer occasion examples ('date', 'office tomorrow', 'night out') than the schema's bare 'The setting', but it never mentions the gender parameter at all, so it is a marginal net gain.

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 concrete verb+resource: a fragrance suggestion for right now, driven by mood, occasion, and season. It is clearly distinguishable from data-lookup siblings like get_fragrance or search_fragrances, though it never contrasts itself with the similarly-shaped 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 phrase 'for right now' implies a situational use, but there is no explicit when-to-use guidance, no exclusions, and no mention of when an agent should prefer this over get_recommendations or trending_fragrances. The agent must infer the boundary itself.

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