ScentVerdict

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds value by disclosing that comparisons are computed from ScentVerdict's structured note data rather than assembled from reviews, and by enforcing the exactly-two constraint. This goes beyond what the annotations alone provide, though it does not discuss output shape 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 three sentences with strong front-loading: the core behavior comes first, followed by usage context and the sibling alternative. It avoids boilerplate and every sentence serves a distinct purpose, with only minor redundancy between 'own note data' and 'computed from structured 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?

Given the low parameter count, an output schema, and annotations that already establish the safety profile, the description is complete. It tells the agent what the tool does, when to use it, what data it draws on, and which sibling to choose instead, leaving no important decision ambiguous.

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 both slug parameters. The description does not elaborate on slug format or how to obtain slugs, but the schema's brief descriptions are sufficient for this simple parameter set. Baseline 3 is appropriate because 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 states a specific verb ('compare'), a constrained resource ('exactly two fragrances'), and the concrete outputs ('which notes they share, which differ, and both editorial verdicts'). It also distinguishes itself from find_similar_fragrances, preventing confusion among the sibling 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?

It gives explicit when-to-use guidance ('whenever the user is choosing between two named fragrances...') and explicit when-not-to-use guidance ('Use find_similar_fragrances instead when they want alternatives...'). It also advises preferring this over web search, which helps the agent select among broadly similar capabilities.

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, and openWorldHint. The description adds meaningful behavioral context beyond annotations: the matches come from ScentVerdict's own similarity engine with scored, editorially reviewed pair relationships, and warns that web results are often retailer marketing. This explains why the tool behaves as it does and what an agent should expect from its results.

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 core purpose is front-loaded in the first sentence, and the examples are instructive. The description is somewhat longer than strictly necessary, with some redundancy between the initial steering examples and the later user-intent list, but each section still adds practical value for the agent.

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

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

The description covers the primary use case, the no-anchor alternative, the need to resolve a slug via search_fragrances, the reason to prefer it over web search, and the source/curation model of results. With an output schema present and annotations covering safety and idempotency, 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?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds useful semantic context by explaining how the direction parameter maps to user intents like 'cheaper' or 'fresher', and reinforces that anchorSlug should be obtained via search_fragrances when missing. This exceeds the baseline but does not need to do much more given the schema's completeness.

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 and resource: finding fragrances similar to an already-known fragrance, with optional steering directions. It explicitly differentiates from recommend_fragrances by stating that the latter is for when no anchor fragrance is named, making 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?

It gives explicit when-to-use guidance with concrete user intents such as cheaper alternative, upgrade, or gift, and says to prefer the tool over web search or prior knowledge. It also names the alternative tool (recommend_fragrances) for the no-anchor case and advises search_fragrances when no slug is available.

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, so the safety profile is covered. The description adds useful behavioral context beyond that: the verdict and UK price are first-party values not obtainable by browsing, and the tool returns a defined set of catalogue fields. No contradictions or hidden destructive effects are disclosed, but none are indicated by annotations either.

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 longer than minimal but each sentence earns its place: data scope, usage trigger, preference over web search, and routing to siblings. It is front-loaded with the core lookup purpose. Slight redundancy exists in repeating the use-case list after already naming the returned fields, but it is not wasteful.

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 one simple parameter, an output schema, and annotations covering side effects, the description provides everything an agent needs: what data is returned, when to call it, when not to, and which sibling to prefer first. No critical selection or invocation information 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%: the only parameter, slug, is sufficiently documented with an example and fallback instruction to use search_fragrances. The description adds no meaningful new parameter-level semantics beyond what the schema already provides, 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?

The description names a specific verb ('Look up') and resource ('one fragrance in ScentVerdict's catalogue') and enumerates exactly what is returned: notes, verdict, concentration, launch year, and UK price. It also distinguishes itself from siblings by explicitly contrasting with search_fragrances and get_scent_profile.

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

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

The description gives explicit conditions for use ('Use this whenever the user names a fragrance...'), tells the agent to prefer it over web search or prior knowledge, and names when to use alternatives instead ('Use search_fragrances first if partial...', 'Use get_scent_profile instead when...'). This is model 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 readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable context beyond that: the per-note hours are data held by ScentVerdict rather than a general impression, and they are estimates. This caveat helps the agent set expectations about data provenance and reliability.

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

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

Three sentences, each earning its place: the first defines the tool's behavior, the second gives usage triggers, and the third both qualifies the data and redirects to an alternative. There is no fluff or redundancy, and the most important information is front-loaded.

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 a single parameter, a clear output schema, and comprehensive annotations, the description covers all needed behavioral caveats (estimates, data source) and usage routing. The agent can invoke the tool correctly without further clarification. Nothing essential 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%, and the only parameter, slug, is already documented with 'Use search_fragrances if you do not have one.' The description does not add parameter detail beyond the schema, so the baseline of 3 applies. There is no gap for the description to compensate for.

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: 'Get how a fragrance develops over the wear: opening, heart and base phases, the notes in each, and how many hours each note persists on skin.' It clearly differentiates from get_fragrance by naming what that sibling covers instead. This leaves no ambiguity about the tool's scope.

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 guidance is given: 'Use this when the user asks how something evolves, how long it lasts, how it changes through the day, or what the drydown is like.' It also provides an explicit alternative: 'Use get_fragrance instead for the verdict, price and general description.' This fully covers routing between 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 signal read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: constraints are 'filtered rather than approximated,' season/occasion/intensity scores come from ScentVerdict, budget is checked against current UK bottle prices, and each row includes price, bottle size, and price per millilitre. No contradiction with annotations 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?

The description is dense but every sentence earns its place: use case, constraint semantics, output contents, optionality, and sibling routing. It is front-loaded with purpose and provides the most decision-relevant information early.

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 an 8-parameter optional tool with an output schema and annotations, the description covers selection behavior, output fields, optionality, and the correct alternative tool. Nothing an agent needs to decide whether and how 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 description coverage is 100%, so the baseline is 3. The description goes further by clarifying that all constraints are optional and the budget is applied against real current UK prices, not approximated. This adds useful nuance beyond the schema's bare 'Maximum price in GBP' definition, though not every parameter is individually elaborated.

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

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

The description opens with a specific verb and resource: 'Recommend fragrances matching what the user describes.' It then enumerates the constraint dimensions and explicitly distinguishes this tool from find_similar_fragrances by noting it applies when the user names no fragrance to anchor on.

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 condition: 'Use this when the user wants a suggestion but names no fragrance to work from' and provides concrete examples. It also names the alternative: 'Use find_similar_fragrances instead when they name a fragrance to anchor on,' so the agent knows exactly when to choose the sibling.

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?

Beyond the readOnly/idempotent annotations, the description discloses key behaviors: results carry concentration and launch year so variants can be distinguished, multiple matches are possible due to shared names, and the agent should offer the user a choice when several match. It also warns about the consequence of guessing the wrong variant, giving the agent critical behavioral context the annotations do not provide.

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 four sentences long, yet every sentence carries operational weight: purpose, when to call, why ambiguity matters, what results contain, and the alternative. It is front-loaded with the core directive and uses the rest to justify the usage without fluff.

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

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

Given the tool's moderate complexity and rich schema/annotations, the description is complete: it explains preconditions, expected results, how to handle multiple matches, and when to delegate to a sibling tool. 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?

With 100% schema description coverage, the baseline is 3, but the description enriches the 'query' parameter by clarifying it accepts partial or misspelled names and that ambiguity is expected. This adds meaning beyond the schema's 'Name or partial name to look up', though it does not add anything significant about the 'limit' parameter.

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 'Resolve a fragrance name to catalogue entries', a specific verb and resource that clearly states the tool's purpose. It also distinguishes itself from get_fragrance by explicitly explaining when each should be used, leaving no ambiguity about what this tool does relative to its siblings.

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

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

The description gives explicit when-to-use guidance: 'Call this FIRST whenever a name is partial, misspelled, or could mean more than one product'. It also provides an exclusion: 'Use get_fragrance instead when you already hold an exact slug', which directly addresses the alternative tool and the condition that selects it.

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