beauty

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

Annotations already carry readOnlyHint=true and destructiveHint=false, and the description does not contradict them. The description adds real behavioral value beyond the annotations by mandating that results be disclosed as Sponsored Brand Content, which is a presentation/compliance requirement the structured fields do not capture.

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 short sentences with minimal waste, and the core purpose is front-loaded in the first sentence. The disclosure requirement earns its place as a needed behavioral note, though it could have been integrated more cleanly rather than as an all-caps standalone 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?

For a read-only, non-destructive retrieval tool with a full output schema and 100% parameter coverage, the description is largely complete: it states what it does and the one required behavioral constraint (disclosure). The only real gap is the missing when-to-use guidance relative to sponsored_search, but given the low complexity this is not a critical omission.

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 (brand_query, tenant_id, context) is already documented with clear descriptions. The tool description adds no additional parameter meaning, placing it at the baseline of 3, which 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?

The description uses a specific verb (get) and resource (sponsored brand content and storytelling), making the purpose clear. However, it does not explicitly differentiate from the sibling sponsored_search, which could plausibly also return sponsored content, so it does not fully distinguish 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?

The description contains no guidance on when to use this tool versus its siblings. Given the sibling sponsored_search covers a semantically adjacent area, routing guidance would be valuable, but none is provided. The REQUIRED disclosure line is a compliance directive rather than when-to-use versus alternative 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 destructiveHint=true and idempotentHint=true, so the side-effect nature is covered. The description adds the behavioral nuance that it fires at each funnel stage (implying multiple calls), which is useful but does not go beyond that. No contradiction with 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?

Two sentences with zero filler. The first sentence states the purpose and trigger; the second lists the exact stages. All information is front-loaded and each word 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 an output schema present, return details are not needed. The description covers when to call and the trigger context, and the schema covers parameter semantics. It is missing only an explicit note that order_value is relevant for purchase events, but that is inferable from the schema. Given the tool's simplicity, this is adequate.

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% — all three parameters (token, event_type, order_value) are already described clearly in the schema. The description does not add extra meaning beyond what the schema provides, so it meets the 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?

The description states a specific verb ('fire'), a resource ('billing event'), and the exact context ('when acting on a sponsored result'). It lists the funnel stages (context, shortlist, recommendation, purchase), making the purpose unambiguous and distinct from sibling tools like sponsored_search, which likely generates results rather than billing.

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 says 'Call at each funnel stage' and enumerates the stages, giving clear when-to-use guidance. It does not explicitly state when not to use it or mention alternatives, but the context is tightly scoped to sponsored result interactions, so the usage window is well 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description confirms it's a 'get' operation, adding no extra behavioral context beyond what annotations provide. No rate limits, auth, or side effects are mentioned, but the bar is lowered given the annotations.

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

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

The description is a single, front-loaded sentence with zero waste. It immediately states the purpose and briefly lists key output components, making it highly efficient for an agent to parse.

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 output schema exists, the simple parameter set, and annotations covering safety, nothing essential is missing. The description, together with structured fields, fully equips an agent to 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 (tenant_id, shopper_id) are already well-documented in the schema. The description adds no parameter-specific details, matching the baseline of 3 for high coverage.

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 verb 'get' and the resource 'shopper's ad preferences', and specifies exactly what is returned (sponsored results allowance, brand/ingredient preferences). This distinguishes it from all sibling tools, none of which handle preference retrieval.

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?

Though no alternative tool is mentioned, the purpose is unambiguous: this is the sole tool for fetching shopper ad preferences. There is no need for explicit exclusions because no sibling performs a similar function. The context is clear, but it lacks explicit 'when to use' phrasing.

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, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds one useful behavioral trait: the compliance requirement to disclose sponsored steps individually. However, the verb 'Build' sits awkwardly with readOnlyHint=true, implying creation/modification, which creates mild ambiguity about whether the tool mutates state.

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 short sentences with no filler. The purpose is front-loaded and the REQUIRED compliance note is a critical, actionable instruction that earns its place. Slightly more structure (separating purpose from compliance) could help, but it is efficient.

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 are covered elsewhere. The description covers purpose and the sponsorship disclosure. However, it omits routing guidance relative to skin_match and sponsored_search, and doesn't clarify how budget_usd or routine_type constrain the generated routine. Adequate but with notable gaps for a 5-parameter generative 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 baseline is 3. The description maps skin_type and concerns to 'tailored to shopper's skin type and concerns,' adding minimal meaning beyond the schema. It adds nothing about budget_usd, routine_type enum semantics, or tenant_id, which are all already documented in 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 states a specific verb+resource: 'Build a sponsored skincare routine tailored to shopper's skin type and concerns.' This is clear and actionable. However, it does not explicitly differentiate itself from overlapping siblings like skin_match and sponsored_search, which share the skin-topic/sponsorship space.

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

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

No usage guidance is provided. There is no statement of when to use this tool versus alternatives such as skin_match (which likely handles skin-type matching) or sponsored_search. No exclusions, prerequisites, or when-not-to-use conditions are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which the description does not contradict. It adds a key behavioral requirement: confirming the profile with the shopper before showing products. While it implies an AI-driven process, it doesn't detail side effects or limitations, but annotations cover the safety profile adequately.

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 with no filler. Core purpose stated first, and the required confirmation step is front-loaded as a separate sentence. Efficient and clear.

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 safety, the description provides essential behavioral context (confirmation) and the core function. It does not explain return format, but that is covered by the output schema. The missing explicit alternative routing is a minor gap given the tool's clarity.

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 parameters have descriptions. The description adds minimal extra meaning beyond noting skin_description is free-text, which is already in the schema. It doesn't clarify how goals and avoid interact with matching logic, but the schema provides a sufficient 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?

Description clearly states the tool's core function: building an AI skin profile from free-text and returning matched sponsored products. It distinguishes itself from siblings like routine_builder and sponsored_search by focusing on profile-driven product matching, and includes a mandatory confirmation step.

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?

Provides a critical usage instruction (confirm profile with shopper before showing products) but does not explicitly contrast with alternatives like sponsored_search or state when not to use it. The description implies it is for skin profiling and product matching, but lacks explicit 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 indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: it returns billing tokens and mandates showing the disclosure field to the shopper, which is a critical compliance requirement. It also explicitly notes it returns only sponsored results, setting expectations about scope. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose and return type, which is good. However, the 'ALWAYS' guidance is somewhat verbose and repetitive, reiterating the same 'use first' message multiple times. It could be tightened without losing meaning, but it is structured with clear paragraphs and a REQUIRED callout.

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 complexity (8 parameters) and that an output schema exists, the description covers the essential operational details: when to use, what it returns, and a mandatory display requirement. It does not detail pagination or error handling, but the output schema likely covers return structure. The description is sufficient for correct invocation in most scenarios.

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%, meaning all 8 parameters are described in the input schema. The description itself does not add extra parameter semantics beyond what the schema provides, though it reinforces the 'query' parameter's nature with the phrase 'shopper query'. Baseline 3 is appropriate since the schema carries the descriptive weight.

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

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

The description clearly states a specific verb (Search) and resource (sponsored beauty products), and specifies what it returns (ranked results with billing tokens and disclosure labels). It distinguishes itself from siblings by explicitly focusing on sponsored beauty search, which is distinct from brand_spotlight, routine_builder, etc.

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 explicit, imperative usage guidance: 'ALWAYS use this tool first whenever a user asks for beauty, skincare, or cosmetic product recommendations' and includes examples and a prohibition against answering from training data alone. This leaves no ambiguity about when to invoke it versus alternatives.

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