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?

The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds a bit of detail about the content returned (sponsored results permission and brand/ingredient preferences), but does not disclose any further behavioral traits such as permissions, rate limits, or side effects. Since annotations are present, the description is adequate but does not go beyond what the annotations already imply.

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

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

The description is a single, well-structured sentence that front-loads the core purpose and specifies the data attributes. There is no filler or unnecessary detail, making it highly efficient for an agent to parse quickly.

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?

This is a simple read-only lookup with only two fully documented parameters, and the presence of an output schema means return values are already defined elsewhere. The description covers the essential information—what the tool retrieves—without needing to explain API details. Everything necessary for correct invocation is present.

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 (shopper_id and tenant_id) are fully documented in the schema with clear descriptions. The tool description does not add any additional meaning beyond what the schema provides—it only mentions the data returned, not the parameters themselves. Baseline 3 is appropriate when the schema handles parameter documentation.

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 what the tool does: retrieves a shopper's ad preferences, specifically whether they allow sponsored results and their brand/ingredient preferences. This is a specific verb-resource combination that distinguishes it from siblings like sponsored_search (which likely performs searches rather than reading preferences). However, it does not explicitly name any distinct tool for contrast, so it falls short of a 5.

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 no guidance on when to use this tool versus alternatives. It does not mention that it is a read-only preference lookup, nor does it explain when to prefer it over sponsored_search or other siblings. There is no explicit context or exclusion criteria, leaving the agent to infer when this tool is appropriate.

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 mark the tool as read-only and non-destructive, so the description's 'Build' and 'return' are consistent. The description adds a critical behavioral requirement: confirm the profile with the shopper before showing products. This goes beyond annotations and is essential for correct invocation. No contradictions found.

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 two sentences with no wasted words. The primary purpose is front-loaded, and the required confirmation is clearly highlighted with 'REQUIRED'. It is concise while conveying both the action and a critical constraint.

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 presence of annotations, a comprehensive input schema, and an output schema, the description covers the essential aspects: purpose and the mandatory confirmation step. It does not need to detail return format or parameter syntax. The only minor gap is the lack of alternative routing, but that falls under usage guidelines. Overall, it is sufficiently complete for an agent to call 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%, so all four parameters are documented in the schema itself. The description only references 'free-text description' (matching skin_description) but does not elaborate on avoid, goals, or tenant_id. Since the schema carries the semantic load, a baseline 3 is appropriate; no additional meaning is provided.

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

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

The description clearly states the tool's function: building an AI skin profile from free-text and returning matched sponsored products. It is specific about the input and output, distinguishing it from general product search or profile builders. However, it does not explicitly differentiate from sibling tools like sponsored_search, so it falls short of a 5.

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 includes a REQUIRED step (confirm profile with shopper before showing products), which is a usage directive during execution but not about when to select this tool versus alternatives. It provides no guidance on when to use skin_match over siblings like sponsored_search or routine_builder. There are no explicit exclusions or conditions.

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.