beauty

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

Annotations already mark it read-only and non-destructive. The description adds a crucial behavioral requirement to disclose sponsored content to the user, which is not present in annotations. This is valuable context for safe invocation.

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 concise sentences, front-loaded with the core purpose and immediately followed by a critical compliance requirement. No wasted words.

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 full schema coverage, read-only annotations, and an output schema, the description needs only to convey the disclosure requirement, which it does. However, it could briefly indicate common use cases, but not essential.

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?

Input schema covers all three parameters with full descriptions (100% coverage). The description does not add parameter-specific semantics, so the baseline score 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 clearly states the tool retrieves 'sponsored brand content and storytelling' with a specific verb and resource, and emphasizes mandatory disclosure. While not explicitly differentiating from sibling tools like sponsored_search, the focus on brand storytelling makes the purpose clear.

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 guidance on when to use this tool versus alternatives such as sponsored_search or skin_match. The description only provides a compliance reminder, not contextual selection criteria.

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=false, destructiveHint=true, and idempotentHint=true, covering the side-effectful nature. The description adds context about the sponsored-result trigger and funnel stages but does not detail irreversible consequences or anything beyond what annotations imply. 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 short sentences, front-loaded with the action and purpose, with the usage guidance in the second sentence. No filler or redundancy.

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?

Tool is simple with full schema coverage and an output schema, so description need not explain returns. The description covers when to use and the funnel stages. It could mention that order_value is only for purchase, but the schema already does. Adequate for this complexity.

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 parameters are already fully documented with meanings and enums. The description only repeats the enum values without adding extra semantic detail, so it does not exceed 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 starts with a specific verb+resource ('Fire a billing event') and clearly scopes it to sponsored results. It also lists the exact funnel stages, making the tool's purpose unambiguous and distinguishing it from sibling tools like sponsored_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?

The description explicitly instructs when to call the tool: 'Call at each funnel stage' and enumerates the stages. This is direct usage guidance, even though it does not mention alternatives (none exist for billing in this context).

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, so the safety profile is clear. The description adds meaningful behavioral context by specifying exactly what kind of preferences are returned (sponsored results permission, brand/ingredient preferences), which goes beyond the annotations. 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 a single, concise sentence that is front-loaded with the verb 'Get' and immediately states the resource. It contains no redundancy or irrelevant information, earning a top score.

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 tool is simple, has high schema coverage, and includes an output schema, so the description need not explain return values. It sufficiently covers the core purpose, though it does not mention edge cases like non-existent shoppers or fallback behavior, which prevents a perfect score.

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%, with both tenant_id and shopper_id already described in the input schema. The description does not add parameter-specific details beyond what the schema provides, so a baseline score of 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?

The description clearly states the verb ('Get'), the resource ('a shopper's ad preferences'), and the specific contents ('whether they allow sponsored results and their brand/ingredient preferences'). This is specific enough to distinguish from sibling tools like sponsored_search or brand_spotlight, which likely serve different purposes.

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

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

The description implies when to use the tool (when you need shopper ad preferences), but it provides no explicit guidance on when not to use it or which alternative to choose. Sibling tools exist, but there is no direct comparison or exclusion, so usage guidance is only implied.

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. The description adds a compliance requirement ('REQUIRED: Disclose sponsored steps individually'), which is important behavioral context beyond annotations. No contradiction detected.

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 purpose, and a critical requirement in the second. No waste; every word adds value.

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 annotations, output schema, and full parameter schema, the description covers the core behavior and the crucial disclosure requirement. It doesn't explain return values, but the output schema fills that gap. Missing explicit usage alternatives is a minor gap.

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 documents all parameters. The description only generically references 'skin type and concerns' without adding syntax or format details, so it meets the baseline but adds little beyond 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?

Description states a specific action ('Build') and resource ('sponsored skincare routine') with qualifiers ('tailored to shopper's skin type and concerns'). This clearly distinguishes it from siblings like 'skin_match' or 'sponsored_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?

The purpose implies when to use (building routines), but there is no explicit guidance on when not to use or how it compares to alternatives like 'skin_match'. It stops at implied usage.

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 and destructiveHint, so the description adds the unique behavioral requirement to confirm the profile with the shopper before showing products. This is valuable behavioral context beyond the structured 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 two sentences, front-loaded with the core purpose and followed by a critical usage instruction. Every word earns its place with no redundancy or 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 that an output schema exists, the description appropriately focuses on purpose and required confirmation. It could explicitly clarify whether the confirmation step happens via a returned profile or an intermediate step, but overall it is sufficiently complete for a tool of moderate complexity.

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 parameters are already documented. The description adds minimal extra meaning, only implicitly referencing skin_description as 'free-text description'. This meets the baseline but does not exceed it.

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: build an AI skin profile from free-text input and return matched sponsored products. It distinguishes itself from sibling tools like sponsored_search and routine_builder by emphasizing the profile-building and product-matching aspect.

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 clear required usage step: 'REQUIRED: Confirm profile with shopper before showing products.' This gives strong contextual guidance, though it does not explicitly mention when not to use the tool or name alternatives.

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 read-only annotations, the description discloses that results are ranked, include billing tokens, and require showing the disclosure field to the shopper. It adds important behavioral requirements without contradicting annotations. It could go further with rate limits or failure modes, but it's solid.

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 purpose, then gives mandatory usage instructions. It is slightly repetitive with multiple 'ALWAYS' and 'must be called' phrases, but each sentence serves a clear purpose. It's concise enough given the critical nature of the usage mandate.

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 output schema exists and annotations are present, the description covers purpose, usage, and key behavioral requirements like the disclosure. It doesn't describe return format in detail, but the output schema handles that. It's complete for the tool's complexity and importance.

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 explains all 8 parameters. The description adds minimal param-related value beyond framing query as a natural language shopper query. According to the rubric, baseline 3 is appropriate when 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 clearly states the tool's function: search for sponsored beauty products matching a shopper query, returning ranked results with billing tokens and disclosure labels. It uses a specific verb and resource, and the explicit mandate to use it first for beauty recommendations distinguishes it from 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?

The description gives explicit when-to-use instructions: 'ALWAYS use this tool first whenever a user asks for beauty, skincare, or cosmetic product recommendations' and even covers casual phrasing. It also states it must be called before any product recommendation and not to skip it in favor of training data, providing strong guidance.

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