Scento Perfume API (MCP server)

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the source is Scento's own proprietary taxonomy (not a generic standard), and it discloses the payload shape — definition, subfamilies, exemplars, neighbouring families, and the scento.com guide. It doesn't discuss pagination or edge cases like an unknown family name, which keeps it from 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?

Front-loaded with the primary trigger and concrete examples before the return-value detail, which is the right ordering. The synonym parenthetical and the long return sentence are dense but each earns its place; only the synonym list is slightly redundant.

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

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

An output schema exists, so return values need no further explanation, and annotations carry the safety profile. With only two fully documented optional parameters and explicit sibling routing, nothing an agent needs in order 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 both parameters are already documented, including the enum for lang and the 'leave empty for the whole map' default behavior for family. The description restates the family-name examples but adds no syntax or format guidance beyond the schema, 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 resource (Scento's own fragrance family system) and precisely what it returns: the whole tree, or one family with definition, subfamilies, exemplar perfumes and neighbouring families. It also names boundary cases (single-perfume family, term, occasion) so the agent can tell it apart from perfume-portrait, perfumery-lexicon and occasion-edit.

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?

Opens with an explicit trigger ('when the user asks how fragrances are grouped or what a scent family is') plus concrete examples (woody, floral, amber, fresh, citrus) and a second trigger for exemplars of one family. It closes with explicit when-not-to-use routing to three named 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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real context beyond that: the exact payload shape returned and the subtle language behavior (links/labels localized while answers stay in English). It doesn't discuss limits on ambiguous multi-house names beyond the search fallback, 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?

Three sentences, each doing distinct work: trigger, return shape, exclusions plus fallback. The trigger is front-loaded and there is no filler or repetition of the tool title.

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

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

An output schema exists, so return values need no elaboration, and the description still sketches them. Combined with the routing guidance for siblings and the uncertain-name fallback, an agent has everything needed to select and invoke this 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% and the lang parameter's schema text already explains the links-vs-answers language split, so the description's mention of "the user's language" largely restates structured data. Baseline 3 is appropriate when the schema carries the parameter semantics.

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 (profile a perfume house/brand/maison) and enumerates the returned fields: country, founding year, style, signature perfumes with families, and the scento.com house page. It explicitly distinguishes itself from perfume-portrait and material-match, so an agent can route correctly without opening any schema.

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

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

Gives the triggering condition (user asks about a house/brand/maison), two explicit exclusions with the named alternatives (perfume-portrait for one perfume, material-match for listing perfumes by note), and a recovery path when the house name is uncertain (perfume-search with kind "house"). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond them: the exact return payload (title, one-line summary, scento.com link), the localization behavior (links in the user's language, answers in English), and the reader-facing intent. It does not mention pagination, which is the one behavioral 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?

Four sentences, front-loaded with the trigger condition, then return shape, then exclusions. Every clause carries load — the examples, the output fields and the sibling routing all serve selection or 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 3-parameter read-only search with full schema coverage and an output schema, the description supplies everything an agent needs: trigger, exclusions, sibling routing and localization behavior. Return values are already covered by the output schema, so nothing material 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 baseline is 3 and the schema already documents q, lang and continuation thoroughly. The description reinforces the localization nuance ('in the user's language') but adds no syntax, format or constraint detail beyond the schema, so it earns no more than baseline.

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

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

States a specific verb and resource ('search the Scento journal'), names the artifact returned (articles with title, one-line summary and link), and explicitly contrasts itself with three siblings. An agent can distinguish it from perfume-portrait, house-portrait and perfumery-lexicon without opening any schema.

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

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

Gives an explicit when-to-use trigger ('user wants articles, guides or background reading on a perfume, fragrance, cologne, house, note or topic') with concrete examples, plus explicit when-not-to-use routing to three named alternatives. Nothing is left to inference.

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

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

Annotations already cover read-only, idempotent and non-destructive safety, so the bar is lower. The description adds real behavioral detail beyond that: results must contain EVERY material given (conjunction, not union), the payoff fields (house, pyramid position, scento.com links), and that labels/links localize while answers stay English. It stops short of disclosing result count or pagination behavior, hence not 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?

Front-loaded with the trigger, then output, then exclusions — a sensible ordering. The synonym parenthetical is dense but earns its place by catching varied user phrasing. Slightly long overall, but no sentence is wasted.

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 an output schema present, return values need not be re-explained. The description covers trigger, semantics, localization, alternatives and the continuation mechanism, leaving nothing an agent needs in order to call this 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 baseline is 3 and the schema already documents lang, tier, family, materials and continuation. The description nonetheless reinforces the AND semantics of the materials array, pairs it with a concrete tier example ('vanilla and tobacco in the base'), and explains the language split between links and answers, adding usable meaning above the schema text.

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 (find), resource (perfumes/fragrances/colognes) and constraint (containing specific notes or raw materials), plus the optional pyramid tiers. It names and distinguishes itself from three siblings (note-portrait, scent-neighbours, occasion-edit), so an agent can route correctly without opening any schema.

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

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

Gives an explicit trigger ('when the user wants perfumes... that contain specific notes'), a list of natural-language synonyms to match, and explicit negative routing to note-portrait, scent-neighbours and occasion-edit. Nothing about when/when-not is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing the returned payload (smell, family, natural/synthetic, pairings, example perfumes, localized scento.com page) and the language behavior. It does not discuss auth, rate limits, or lookup-miss behavior, which keeps it 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, front-loaded with the use case, then the return contents, then the exclusions. Every clause carries information — the example list, the synonym list, and the two sibling redirects all reduce agent ambiguity 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?

An output schema exists, so return values need not be spelled out, yet the description still summarizes them usefully. Combined with the sibling routing and the language note, an agent has everything needed to select and call this 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 both parameters are already documented, and the baseline of 3 applies. The description's example materials and the 'in the user's language' clause loosely reinforce the schema but add no syntax or constraint detail beyond it (e.g. no guidance on ambiguous or multi-word material names).

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 — explaining what a note or raw material smells like or is — with concrete examples (vetiver, oud, ambroxan). It explicitly names the sibling tools it is not (material-match, perfumery-lexicon), so an agent can distinguish it without opening any schema.

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

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

Gives explicit trigger conditions ('user asks what a note smells like', 'whether it is natural or synthetic', 'what it pairs with'), user-phrasing synonyms, and two named exclusions with the correct alternative for each. This is a complete when/when-not/alternative routing statement.

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 readOnlyIdempotent non-destructive behavior, so the safety profile is covered. The description still adds behavioral context beyond them: the response is a 'short edit' with a per-perfume rationale and a scento.com link, links follow the user's language while answers stay English, and the occasion input is a closed list requiring nearest-value snapping. The return-shape detail overlaps the existing output schema, which keeps this 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?

Front-loaded with the trigger, then constraints, then exclusions, so an agent can stop reading early. It is dense rather than bloated, though the long inline enumeration of occasions partly duplicates the enum values already in 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?

Purpose, trigger, parameter resolution, multi-call behavior, output shape, and sibling routing are all present for a 3-param read-only tool with an output schema. An agent has everything needed to select and invoke it correctly, including the gender_lean omission default.

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% and the schema already documents all three parameters with enums, defaults and examples. The description only adds the closed-list resolution rule ('pick the nearest value') and 'omit gender_lean unless the user states one', both of which largely restate the schema. Baseline 3 is right 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 and resource (pick perfumes for an occasion) and enumerates the exact occasion space it covers. It explicitly names two siblings it is NOT (wardrobe-composer, scent-neighbours), so an agent can route between them without opening any schema.

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

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

Gives explicit trigger conditions ('when the user asks which perfume... to wear for one occasion, season or climate'), exclusion conditions (wardrobe-composer for a collection built around loved perfumes, scent-neighbours for similar scents), and a multi-call rule ('for several occasions call it once per occasion'). Nothing about when to use it is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavioral context beyond that: the comparison dimensions returned, that shared materials are computed, and that scento.com links follow the user's language while answers stay English. Some of the return enumeration overlaps the existing output schema, which slightly dilutes the added value.

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 trigger condition and followed by exclusions. The long enumeration of returned fields ('house, Scento family, top, heart and base notes, shared materials, character, seasons, hours, year and concentration') is heavy and partially redundant given the output schema, but the rest is tight and 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 two-parameter read-only comparison tool with full schema coverage and an output schema, the description supplies everything missing: trigger phrasing, cardinality limits, sibling disambiguation, language behavior and return breadth. An agent has enough to select and invoke it 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%: both `perfumes` (2-4 items, name or slug, with examples) and `lang` (enum values, default, language semantics) are fully documented in the schema. The description corroborates the 2-4 constraint but adds no syntax or format detail beyond it, so the baseline of 3 applies.

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

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

States a specific verb and resource ('compare... two to four named perfumes, fragrances or colognes') and enumerates trigger synonyms (versus, vs, difference between, which one). It also names the sibling tools it is not (scent-neighbours, perfume-search, perfume-portrait), so an agent can distinguish it without opening any schema.

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

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

Explicit when-to-use ('user asks to compare, contrast or choose between two to four named perfumes') and explicit when-not-to-use with the correct alternatives named for each exclusion case. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds useful behavior: it discloses that answers stay in English while the scento.com page and labels follow the lang parameter, and that notes are "verified" — context an agent cannot get from the annotations alone. It stops short of describing pagination or failure behavior when the perfume is ambiguous.

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

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

Front-loaded with the trigger condition, then returns, then exclusions — a sensible ordering. The middle clause is a long enumeration of attributes and synonyms that borders on padding, but each item maps to a real user asking pattern rather than repeating structured fields.

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 an output schema exists, the description need not explain return shapes, yet it still summarises them usefully. Trigger, localization behavior, and sibling disambiguation are all present; nothing an agent needs to call 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 both parameters are fully documented in the schema itself, making 3 the baseline. The description confirms the lang effect ("page in the user's language") and the free-form name-or-slug input, but adds no syntax, disambiguation or matching-behavior detail 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?

States a specific verb and resource (retrieve a perfume's notes and profile) and enumerates the exact attributes covered: notes/pyramid, family, perfumer, year, concentration, occasion. It explicitly names the three siblings it is not and the condition distinguishing each, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use triggers phrased as user utterances ("what does X smell like", synonym list) and explicit when-not-to-use cases mapped to named alternatives: scent-neighbours for similar, perfume-contrast for comparison, perfume-search for mood. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond them by disclosing what a call returns (plain-language meaning, example perfumes, related terms) and the language behavior of the linked guide versus the answer body, though it says nothing about rate limits or fallback behavior for unknown terms.

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

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

Front-loaded with the trigger condition, then the return contract, then the exclusions – a sensible order with no filler sentences. The long inline term list is somewhat heavy but it doubles as disambiguation evidence, so it earns its space; only the sheer length keeps it from a 5.

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

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

An output schema exists, so return-value detail is not strictly required, yet the description still summarizes the response shape. Combined with the 100%-covered input schema and the read-only annotations, an agent has everything needed to select and invoke this 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 coverage is 100%, so the baseline is 3, but the description goes slightly beyond the schema by enumerating representative 'term' values ('sillage', 'drydown', 'chypre', 'EDP vs EDT'), which tells the agent how to phrase multi-word or acronym-style terms. The lang guidance largely mirrors the schema text, so the gain is modest rather than substantial.

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 ('Explain a perfumery term') and enumerates the exact term space it covers (sillage, drydown, chypre, EDP vs EDT, etc.), so an agent knows precisely what class of query belongs here. It also names the siblings it is not (note-portrait, perfume-portrait), making it distinguishable without opening any schema.

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

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

Opens with an explicit trigger ('Use this when the user asks what a perfume or fragrance term means') and closes with explicit exclusions routing to alternatives ('Don't use for a specific note (use note-portrait) or a specific perfume (perfume-portrait)'). Both the when and the when-not plus the named fallbacks are present.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds real behavior: results include house, Scento family and a scento.com link, ten items per page, and pagination is continued via the continuation token. It does not mention rate limits or failure modes, keeping it 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?

Front-loaded with the trigger condition, then result shape, then the disambiguation rule, then exclusions. Dense and largely waste-free, though the parenthetical synonym list is long and slightly crowds the opening sentence.

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

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

An output schema exists, so return values need not be detailed, yet the description still summarizes result composition, page size and pagination. Combined with full schema coverage and clear routing to alternatives, an agent has everything needed to call this 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 q, kind, lang and continuation, including examples and enum meanings. The description reinforces the q scope ('name is uncertain', synonyms) and the language behavior, but adds little syntax or format beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (search/find) and resource (perfumes, houses, notes/materials) and enumerates the trigger inputs: name, house, note, or mood. It is immediately distinguishable from siblings like perfume-portrait or journal-search.

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?

Explicit when-to-use ('user asks to find a perfume... by name, house, note or mood'), an explicit disambiguation rule ('Call this first when a name is ambiguous'), and explicit when-not with named alternatives (perfume-portrait, scent-neighbours, journal-search). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: results share the most notes and structure, shared materials are named, each entry gets a one-line difference note, and links come back in the user's language. It does not cover pagination/continuation behavior, keeping it 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, front-loaded with the trigger and closed with the exclusions, so the routing information appears before the exclusions. The synonym parenthetical and the three named alternatives make it dense, but each clause carries routing value rather than 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?

With an output schema present and annotations covering the safety profile, the description only needs to add routing and intent, which it does fully: trigger phrases, return semantics, and explicit exclusions naming three siblings. Nothing an agent needs to select or call this tool 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 all four parameters are already documented in the schema, including the lang enum and the perfume examples. The description's mention of

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 (find perfumes similar to a given one) with the

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?

Explicit when-to-use with synonyms (

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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds behavioral context by sketching the return shape (roles like daytime/evening/warm weather, each with perfume, house, rationale, and a scento.com link) and the language behavior; it does not discuss limits or failure modes, but little is needed for a safe read tool.

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 primary purpose and trigger lead, followed by the return shape, then the exclusions — good front-loading in two sentences. The parenthetical synonym list is slightly dense but earns its place for retrieval matching.

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 four parameters, an output schema present, and rich annotations, the description supplies everything an agent needs: trigger conditions, synonyms, return structure, and explicit routing to sibling tools. No information gap remains that would cause a wrong 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 description coverage is 100%, so every parameter is already documented in the schema (lang, size 3-5, avoid up to six, loves one to six). The description echoes 'three to five perfumes' and 'perfumes or notes they already love' but adds no syntax or format meaning beyond the schema, 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?

The description states a specific verb and resource ('build a small fragrance wardrobe or collection, three to five perfumes for different moments') and explicitly differentiates itself from siblings occasion-edit and scent-neighbours. An agent can select this tool without opening any schema.

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

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

It gives an explicit trigger ('when the user wants... or asks what to add next'), lists synonyms to catch alternate phrasings, and states the negative case by naming the two sibling tools to use instead. Both when-to-use and when-not-to-use are covered.

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