BeautySpark

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

Annotations already declare readOnly, non-destructive, closed-world behavior, and the description adds real context beyond them: the match: null outcome for unreviewed products and the rule that a null must not be presented as a BeautySpark verdict. That is the kind of beyond-annotation behavior that matters for safe downstream use.

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 short sentences, front-loaded with the core lookup and then the outcome rules; no filler. The null-handling sentence is slightly dense but 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 and full schema coverage, the description doesn't need to explain return shapes, and it correctly focuses on the null-match edge case and the season shortcut. The only gap is the absence of any routing guidance relative to the product-pick and color-season siblings.

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 adds meaning the schema doesn't: shade is optional, and passing season additionally returns that season's palette for comparison. The remaining parameters (locale, product) are left to the schema, which documents them well.

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?

Specific verb and resource: looks a product (plus optional shade) up in BeautySpark's season picks and returns recommended seasons. It does not explicitly name the nearby sibling get_product_picks or get_color_season, so differentiation is left partly implicit.

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 a conditional usage rule for the null case ('do not present any verdict as BeautySpark's') and tells the agent when to pass season, which is genuinely useful. It never states when to choose this tool over get_product_picks or get_color_season, so guidance is implied rather than comparative.

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 annotations, it discloses the monetary side effect (spending quoted BeautySpark credits), idempotency behavior (re-calling the same quote returns the same job with no extra charge), and the conflict-retry protocol. This is exactly the operational context a mutation tool needs and annotations cannot convey.

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 tight sentences ordered by importance: what it does, what it costs, who calls it, and the two edge-case behaviors. No filler and the cost warning is placed 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?

An output schema exists so return values needn't be described, and the description fills in the cost, idempotency, and conflict-handling gaps that neither the annotations nor the schema cover. Nothing needed 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: the quoteId is the idempotency key whose reuse guarantees the same job and no double charge. That goes beyond the schema's bare 'quoteId from try_look_from_photo'.

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 opening sentence gives a specific verb ('Start the try-on') and ties it to the producing sibling ('prepared by try_look_from_photo'), so an agent immediately knows this commits a previously-prepared operation rather than creating one.

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 states exactly when the tool is invoked (the widget's Confirm button), what to do when it isn't (ask the user to confirm cost first), and the retry condition on conflict. The when/when-not/alternative routing is fully explicit.

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=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact beyond the annotations: the returned URL expires after 15 minutes. It does not say whether the URL is single-use, whether calling it repeatedly creates orphaned URLs, or what auth the caller needs.

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 purpose and then the key return characteristic. No filler, no redundancy, and the expiry fact is placed where it is most useful.

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 one-parameter, low-complexity tool with an output schema, the description covers what the tool produces and its lifetime. However, it leaves the caller without guidance on how to use the URL (e.g., the upload method) or what to do after expiry, which matters for a widget-facing flow.

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?

There is one parameter, contentType, with 0% schema description coverage; only the enum values document it. The description never mentions contentType, so it contributes no meaning about why the type is required or how it constrains the upload. An agent must infer everything about the sole parameter from the enum alone.

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: creates an upload URL for a user-picked photo, in the context of the try-on widget. An agent can tell this is the pre-step to uploading a photo for virtual try-on. It does not name the sibling that consumes the URL (e.g., try_look_from_photo), so sibling differentiation is only implied by the flow.

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 phrase 'Used by the try-on widget' gives an implied usage context: call this when the user has selected a photo to try on. There is no explicit when-not guidance, no mention of which sibling to follow with, and no statement about prerequisites such as authentication or quota.

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, readOnlyHint=false and openWorldHint=false, so the safety profile is known without the description. The second sentence, "The look is removed," merely restates destructiveHint, and nothing is said about irreversibility, recovery, or behavior when the ID is unknown or already deleted.

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?

It is short and front-loaded, but the second sentence is pure redundancy with the destructive annotation and earns no place. Two sentences where one would carry the same information.

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 an irreversible destructive operation with no output schema and no description of success/failure response. Even with annotations covering the destructive hint, the definition omits whether deletion is permanent, whether an error is returned for a missing ID, and how the caller should confirm the target.

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 single parameter is documented as "A saved look id from search_my_looks," including a UUID pattern. The description adds no further meaning about the ID, so the baseline of 3 applies since the schema does all the work.

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?

"Delete a saved look from the user's BeautySpark My Looks" pairs a specific verb (delete) with a specific resource (a saved look), which clearly separates it from get_my_look and update_my_look among the siblings. It does not explicitly name those siblings as alternatives, so it stops 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?

There is no when-to-use guidance, no mention of when NOT to delete (e.g. use update_my_look to modify instead), and no note that the ID should come from search_my_looks. An agent must infer the workflow entirely from the sibling list.

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, destructiveHint=false and openWorldHint=false, so safety is covered; the description adds genuine behaviour by disclosing that the return payload is full text and that the id encodes three distinct content shapes. It stops short of saying anything about payload size or truncation for long articles, which would be the one remaining disclosure of practical 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?

Three compact sentences, front-loaded with the usage condition before the mechanics, with no redundant restatement of the title or annotations. The dense final sentence carrying the id formats is information-bearing 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?

An output schema covers return shape and annotations cover the safety profile, so the description only needs usage, scope and id construction — all present. The one residual ambiguity (fetch vs get_article_look) is minor relative to the overall coverage of a two-parameter read 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 coverage is 100%, so baseline is 3, but the description goes beyond the schema's bare "An id returned by search" by showing the literal id syntaxes ("<locale>/<slug>#<anchor>", "look:<id>", "season:<season>"). That materially helps an agent construct or validate the required id rather than just copying 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?

States a specific verb and resource ("Returns the full text of one item from search") and then enumerates exactly which id forms are in scope: guide section, article look, and colour-season palette page. The agent can tell this apart from get_guide and knows the tool is an id-driven full-text retriever rather than a search tool.

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 positive context ("For research modes (deep research, company knowledge)") and an explicit exclusion with a named alternative ("In chat, use get_guide instead"). The gap is that it does not say how fetch differs from the sibling get_article_look even though one accepted id form is "look:<id>", leaving a plausible routing ambiguity.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful ordering and labelling semantics, but says nothing about result counts, the limit parameter, or what happens when no matches exist.

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 tight sentences with the core capability front-loaded, followed by ranking behavior and the return contract. No filler or redundant restatement of the 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 not be spelled out, though the description still helpfully states that look ids and an article URL come back. It is complete enough for correct invocation, with only minor gaps around limit, locale and empty-result behavior.

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 80%, so most parameters are already documented in the schema. The description maps loosely onto the type, season and query filters but adds no syntax or format detail beyond what the schema provides; the locale and limit parameters are not addressed at all.

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 gives a specific verb and resource ('Find makeup looks shown in BeautySpark articles') and names the three filters. It also implicitly separates this tool from the user-owned-look siblings by scoping results to articles, and from get_article_look by saying it returns ids for it.

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 explains the ranking behavior when a season is supplied and notes that general looks follow and are labelled, which tells the agent what to expect from filtering. It stops short of naming an alternative tool or stating when not to use this one, so there is no 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 declare readOnly, non-destructive, and closed-world, so the safety profile is covered. The description adds meaningful context on top: the payload is the steps and shades of a single look drawn from editorial article content rather than the user's own saved looks, which affects trust and interpretation of results. It says nothing about error behavior for unknown ids, which keeps it below 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 short sentences with no filler; the core action is front-loaded and the prerequisite follows. Nothing is repeated from the title and every clause carries information.

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 tool with a full schema, an output schema, and complete annotations, the description covers what an agent needs to select and call it. The only omission is behavior on an invalid or stale look id, a minor gap given the tool's simplicity.

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 the id format and the locale parameter's language-tag guidance are already fully documented in the schema. The description only restates the id's provenance, which is a modest clarification rather than new meaning. 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 and resource ("Get the steps and shades of one makeup look") plus the source domain ("from a BeautySpark article"), which cleanly separates it from sibling tools like find_article_looks (listing) and get_my_look (user-owned looks). An agent can identify the operation without opening the 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?

Explicitly ties invocation to a prerequisite: the id must come from find_article_looks, including the expected format. It does not explicitly exclude adjacent siblings such as get_my_look or get_look_status, so the routing guidance is strong but not complete.

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, so the safety profile is covered. The description adds that output includes hex codes and season-guide makeup advice, plus a citation duty ('Cite the returned URLs'), which is genuinely behavioral. It says nothing about the relationship between locale and returned language, caching, or URL lifetime, so beyond-annotation disclosure is modest.

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 what is returned, followed by the citation obligation. No filler, no restatement of the title or annotations.

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 simple two-parameter read tool with an output schema and full annotations, the description covers purpose, content, and the post-call citation requirement, which is what an agent most needs. Minor gaps remain: which URLs are meant by 'returned URLs' and whether locale changes the returned palette text.

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, establishing the baseline of 3. The description's 'one of the 12 color seasons' merely restates the schema's 'One of the 12 seasons' and adds nothing for 'locale'. With no enums declared, extra domain detail (valid season names, accepted casing) would have been valuable but is absent.

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?

Names the resource precisely (one of the 12 color seasons) and enumerates the returned content: best/neutral/avoid colors with hex codes plus eye makeup and lips & cheeks advice. An agent can tell this is a lookup, not a search or list. It stops short of naming the siblings it differs from (list_my_palettes, get_guide), so it lands at 4 rather than 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?

Implied usage is clear from the content (fetch a season's palette when the season is known), and the '12 color seasons' constraint narrows the input domain. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as list_my_palettes for saved palettes or get_guide for general guide content.

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 establish readOnly, non-destructive, and closed-world, so the safety bar is low. The description goes further by describing what comes back (full section plus sibling section ids and headings) and imposes a citation obligation ('Cite the returned url'), which is real behavioral guidance not present in structured fields.

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 primary action, followed by the secondary return content and the citation rule. No filler or restated 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?

A one-parameter read tool with an output schema, full schema coverage, and complete annotations. The description covers input provenance, primary and secondary return content, and the citation requirement — nothing an agent needs to invoke 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 coverage is 100% and the schema's own id description already gives the 'returned by search_guides' provenance and an example format, so the description's mention of the id source is largely redundant. Baseline 3 applies since 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 ('Read one section of a BeautySpark guide in full') and pins the input's provenance to search_guides, which separates it cleanly from the search_guides sibling. It also discloses a secondary effect (listing other sections' ids and headings) up front.

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 phrase 'by an id from search_guides' establishes the intended workflow: search first, then read. There are no explicit when-not-to-use cases or edge-case guidance, but for a single-purpose read tool the context is unambiguous.

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 this a safe, closed-world read, so the bar is low. The description adds genuinely non-obvious behavior: the call blocks for up to waitSeconds (capped at 25), so an agent knows to expect latency rather than an instant snapshot.

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 tight sentences, front-loaded with what the tool does and how long it blocks. The final sentence describing the returned image URL and step colours partly duplicates the output schema, which is the only waste.

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 polling tool with a full output schema and read-only annotations, the essentials are covered: what it polls, the blocking cap, and what a completed result carries. It doesn't say what a timed-out or failed job returns to the agent, a minor gap given the output schema may cover it.

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 says jobId comes from confirm_look_generation and waitSeconds ranges 0-25. The description restates the 25 cap but adds no format, default, or trade-off detail beyond the schema. 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 verb and resource ('Check a try-on') and anchors it to the originating sibling ('started by confirm_look_generation'), which separates it from try_look_from_photo and list_my_generations 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?

The 'started by confirm_look_generation' clause makes the correct sequencing explicit, and the wait semantics imply polling. It stops short of saying what to do on timeout or when to call again, and names no exclusion case.

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, so the safety profile is covered. The description adds the payload scope ('in full' with photos and an external link), which is useful, but says nothing about failure behavior for an unknown id, ownership scoping, or photo format.

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?

A single front-loaded sentence with the verb and scope first and the returned fields enumerated after; no filler. The field enumeration partially duplicates what the output schema already carries, which is the only inefficiency.

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 one parameter, full schema coverage, annotations and an output schema, the description supplies everything needed to call it correctly. The only gap is edge-case behavior (missing/foreign id), which is minor given the structured fields.

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?

There is a single required parameter with 100% schema description coverage, including its origin ('A saved look id from search_my_looks'), so the schema does the heavy lifting. The description only reinforces that the id identifies a saved look, adding no format or validation detail beyond 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 and resource ('Get one saved look') and enumerates what comes back (steps, products/shades, tags, categories, notes, photos, BeautySpark link), which clearly separates it from list/search siblings. It stops short of naming an alternative such as search_my_looks to route discovery, so it is clear but not fully differentiated.

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?

Usage is only implied: the singular 'one saved look' plus the required id conveys a fetch-by-id operation. There is no explicit when-to-use/when-not guidance, no note that an id comes from search_my_looks (that hint lives only in the schema), and no mention of related siblings like get_look_status or list_my_generations.

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, so the safety profile is covered. The description's one genuine addition is that all fields are null until the selfie analysis runs, which matters for interpreting results, but it says nothing about behavior when the profile is absent (error vs empty object).

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: the first states the payload front-loaded, the second gives the one precondition that changes how the result should be read. No filler, no restatement of the title, nothing 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?

This is a parameterless read tool with full annotations and an output schema, so the description only needs to frame what is returned and any caveat, both of which it does. The only gap is what an agent should expect before the selfie analysis exists, beyond 'null fields'.

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?

The tool takes zero parameters, so there is no parameter semantics for the description to add and the baseline of 4 is approached only loosely. The schema already carries no arguments to document and an output schema exists, so nothing here is left to inference.

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 the resource precisely and enumerates its contents (color season, undertone, eye shape, face shape, app language), which lets an agent distinguish it from narrower siblings like get_color_season. The retrieval verb is only implied by the tool name rather than stated in the description, keeping it just 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?

Usage is implied rather than stated: an agent can infer this is the aggregate profile read versus the single-attribute sibling get_color_season, and the null caveat signals a prerequisite. However, no explicit when-to-use or when-not-to-use guidance, and no sibling is named.

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, so the safety profile is covered. The description adds that results are a top pick per category accompanied by a reason and originating article, which is useful context, but it says nothing about result completeness, locale effects, or empty-result behavior beyond what annotations and output schema 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?

A single front-loaded sentence with no filler; the core concept (top pick per category for a season) comes first and the output details follow. The parenthetical category list is somewhat redundant with the enum but still efficiently conveys scope.

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 simple read-only lookup with full schema coverage and an output schema, the description covers purpose, scope, and the shape of each result. It is essentially complete for correct invocation, though it could mention the sibling alternative to be fully self-sufficient.

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 three parameters are already documented, including the season format examples and locale behavior. The description only restates the category set already enumerated in the enum, adding little semantic meaning beyond 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?

States a specific verb (get) and resource (top product pick per category for a color season), and enumerates the categories plus the fact that each pick includes a reason and source article. It does not explicitly distinguish itself from the sibling check_product_for_season, so it lands just short of 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 says what is returned but gives no when-to-use guidance, no conditions selecting it over siblings like check_product_for_season (which validates a specific product against a season), and no prerequisites. Usage is only inferable from the name and purpose sentence.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond them: the newest-first ordering and the 'already in My Looks' flag that lets an agent avoid re-saving. It omits pagination/truncation behavior, though the limit parameter partly covers that.

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 compact sentences with zero filler: the resource and ordering come first, then the actionable cross-tool hint. Every clause carries information an agent can act on.

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, full annotation coverage, and a fully described single parameter, the definition gives an agent enough to call it and to know what to do next. The only gap is that 'My Looks' and the relationship to get_look_status are referenced but not spelled out.

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?

Only one parameter (limit), fully documented in the schema at 100% coverage, so the schema does the work and baseline 3 applies. The description mentions a jobId, which is not a parameter of this tool — a helpful pointer to a sibling, but not added meaning for the actual input.

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 the specific resource (the user's finished BeautySpark look generations) and its ordering (newest first), and 'finished' implicitly separates it from get_look_status, which handles in-progress jobs. It never uses an explicit verb like 'list', but the noun phrase plus ordering makes the read intent 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?

Gives useful forward guidance by naming save_generation_to_my_looks and the jobId needed to call it, which helps an agent chain the two tools. It offers no explicit when-to-use/when-not guidance relative to close alternatives like get_look_status or get_my_look; the distinction must be inferred from the word 'finished'.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds the useful behavioral fact that palette IDs are meant to be reused as userPaletteId in save_my_look, which is a real integration constraint the annotations cannot convey.

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 resource description comes first and the actionable usage second. Nothing is repeated from the schema or annotations.

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 zero parameters, the description does not need to explain return values, and it correctly focuses on how the data is used. A minor gap is behavior when the user has no scanned palettes, which an agent might want to know.

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?

The tool takes zero parameters, so the baseline is 4. The only identifier mentioned (paletteId) is a returned value used downstream, not an input, and it is described clearly in that role.

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 identifies the resource (the user's scanned palettes in BeautySpark) and its contents (shade names and hex colors), which is enough to distinguish it from siblings like list_my_generations or search_my_looks. The verb is only implied ('The palettes the user scanned'), so it is slightly less crisp than an explicit 'List'.

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 a concrete use case (advise with products the user owns) and a downstream handoff (pass a paletteId as a product's userPaletteId in save_my_look), which connects it to the correct sibling. It does not state exclusions or what to do when no palettes have been scanned, so it stops short of full when/when-not 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 declare readOnlyHint=false and destructiveHint=false but say nothing about repeat calls; the description fills that gap by disclosing idempotent behavior ('Saving the same generation again returns the look already saved'), which is genuinely useful for retry decisions. It does not describe error behavior for non-finished jobs or any account/profile constraints.

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 resource, with the idempotency caveat second. Nothing is redundant or padded.

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 one-parameter mutation with an output schema, the description covers prerequisite source, effect, and idempotency, which is what an agent needs before calling. The remaining gap is the relationship to the sibling save_my_look and behavior on an incomplete job.

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 coverage and a single required parameter, the schema already carries the semantics, and the description's 'a jobId from list_my_generations' merely restates the schema's parameter description verbatim. No format, validity, or cross-tool constraint is added beyond 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?

States a specific verb and resource ('Save a finished BeautySpark generation ... as a look in My Looks') and anchors the input to a source tool (list_my_generations), so the action is unambiguous. It does not, however, differentiate itself from the sibling save_my_look, leaving the agent to infer the distinction from the jobId input.

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?

'Finished ... generation' implies a prerequisite (the job must be complete) and 'a jobId from list_my_generations' implies where to obtain input, but neither is stated as an explicit condition. There is no guidance on when to use this instead of save_my_look, and no failure guidance for unfinished or unknown jobs.

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 only declare the safety profile (not read-only, non-destructive, closed-world). The description adds two behaviors the annotations cannot convey: photos are silently not persisted and must be added later via the returned link, and identical saves within 10 minutes are idempotent, returning the original look. Those are exactly the traits an agent would otherwise get wrong. It stops short of describing what the returned link looks like or failure modes.

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 carrying distinct load: identity of the action, the photo exception with the required user-facing behavior, and the dedupe rule. The photo constraint is front-loaded before the save semantics, which is the right order for an agent deciding whether to call.

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 13 params, an output schema, and full schema documentation, the description only needs to carry behavior — which it largely does. The remaining gap is sibling disambiguation against save_generation_to_my_looks and update_my_look, which matters for a save tool in a crowded namespace.

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 field docs are unusually detailed (step ordering, allowed tool slugs, 0-based productRefs/shadeRefs, leaving photoAssetId and position unset). The description adds no parameter-level meaning beyond the photo caveat. Baseline 3 is appropriate when the schema does this much of the work.

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 destination: "Save a new look to the user's BeautySpark My Looks." That is unambiguous about what the tool creates. It does not, however, distinguish itself from the close siblings save_generation_to_my_looks or update_my_look, leaving the agent to infer which save path applies.

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 concrete situational guidance for one case — when the user attaches or mentions a photo, warn them before saving that only text is stored. It also implicitly covers the repeat-save case via the 10-minute dedupe note. But there is no explicit when-to-use versus save_generation_to_my_looks or update_my_look, which are the most likely routing confusions for an agent.

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, non-destructive, closed-world), so the description's added value is the chaining instruction "Read any result with fetch" and the disclosure that only public content is indexed. It does not mention result limits, ranking, or pagination, which is the one remaining behavioral gap given an output schema 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?

Three tight sentences, no filler, and the when-to-use/alternative routing is front-loaded. The middle clause packing three id formats is dense but each format earns its place by enabling follow-up fetch calls.

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, the description need not explain return values, and it instead supplies the routing rule and id formats needed to chain into fetch. Only query semantics and any result-count limits remain unstated, which is a minor gap for a two-parameter search 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 coverage is 50%: locale is documented in the schema while query is not, and the description does not explain query semantics (natural language vs keyword, whether it matches anchors or slugs). The id-format detail clarifies result structure rather than parameter meaning, so 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 (searches) and enumerates the exact resource scope: guide sections, article looks, and colour-season palette pages, all public. The id formats ("<locale>/<slug>#<anchor>", "look:<id>", "season:<season>") make the result types concrete and distinguish it from search_guides and search_my_looks.

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?

Explicitly scopes usage to research modes (deep research, company knowledge) and names the alternative for the other case: "In chat, use search_guides instead." The public-only scope implicitly excludes search_my_looks, so an agent can route correctly without opening any schema.

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/openWorld annotations, the description discloses the result shape (up to 5 sections with a snippet and link), an obligation to cite the returned url, and the empty-result behavior (a note saying no guide covers it). Return-value detail is largely covered by the output schema, so this is solid additional context rather than exhaustive.

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 short sentences, front-loaded with the capability, then the result contract, then the no-match case. No filler and nothing repeated from the title or 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?

With a full output schema and read-only annotations, the description covers the key agent-facing concerns: what it returns, how many, what to do with the url, and what an empty result looks like. The only omission is guidance about the optional filters (type, season, locale), which is a minor gap given the schema documents them.

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 each of the five parameters is already documented, including examples for query, locale, and season. The description adds almost no parameter-level meaning — it hints at the 5-result cap but never explains when to narrow by type, season, or locale, 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 gives a specific verb and resource ("Search BeautySpark's makeup and colour-season guides") and scopes results to sections that answer a question, with two concrete example queries. It cleanly separates itself from get_guide (full read) but never distinguishes itself from the generic `search` sibling, leaving one ambiguity.

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 states the use case (finding sections that answer a makeup or colour-season question), names the follow-up tool ("read one in full with get_guide"), and gives example queries. It does not say when to prefer this over the sibling `search` tool or address when the type/season filters are 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, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds useful behavior beyond that: results are scoped to the user's own saved looks and only ids are returned, which shapes how the agent sequences the next call.

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, zero filler, with the search scope front-loaded before the follow-up hint. Every clause carries information the agent needs.

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?

All seven parameters are optional and both schema and output schema are rich, so the description is nearly complete. The one minor gap is that it doesn't say what happens with no filters at all (return all looks vs. empty result), which matters for an all-optional query.

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 including q, tag, person, category, favourite, limit and cursor is already documented in the schema, and an output schema exists. The description's facet list mirrors the schema and adds no syntax or interaction detail, so 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 verb ("Search") and resource ("the user's saved looks in BeautySpark My Looks") and enumerates the facets it can search by, which separates it from get_my_look (single look by id), list_my_generations, and list_my_palettes.

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?

"Returns look ids for get_my_look" makes the intended two-step workflow explicit, telling the agent to use this as the entry point and get_my_look for detail. It stops short of naming when not to use it (e.g. vs. list_my_generations or generic search), so no exclusion 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 only declare that this is non-read-only and non-destructive; the description adds the crucial behavior that it returns credit cost and balance without charging and that no generation happens until confirm_look_generation. It also discloses the widget-only upload path and the saved-selfie default, which the agent could not infer from annotations or schema.

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 front-loaded sentences with no repetition: purpose first, then parameter routing, then the widget constraint, then the no-charge guarantee. Every clause carries information the agent needs.

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 preparation step feeding a two-stage try-on flow, the description covers inputs, upload channel, defaults, and the fact that it returns cost/balance without side effects. An output schema exists and further detail on return shape is unnecessary.

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 each parameter, including the widget-set fields. The description still adds meaning the schema does not express, namely the mutual exclusivity of articleLookId and savedLookId ('Give one reference') and which selfie is used by default.

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: 'Prepare a try-on: BeautySpark recreates a makeup look on the user's selfie.' It also bounds the scope by saying nothing is generated until confirm_look_generation, which separates it from that sibling without needing the 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 prerequisites and alternatives: supply exactly one reference, articleLookId from find_article_looks or savedLookId from search_my_looks, and names both source tools. It also states what is not allowed (photos cannot come from chat attachments) and which selfie is defaulted.

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 only say destructiveHint=true; the description explains exactly what is destroyed — list fields (steps, products, tags, categories, occasions) are replaced whole rather than merged. It also discloses that look photos are preserved and that certain payloads are refused, which is meaningful behavior beyond the annotation flag.

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?

It is front-loaded with the partial-update rule and every sentence carries a constraint that is not in the schema, so little is wasted. The trailing sentence ("To unlink every step, send products too") is compressed to the point of ambiguity and could be stated more plainly.

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 14-parameter mutation tool with a nested steps array, the description covers the highest-risk semantics (whole-list replacement, photo lock, ref coupling) and an output schema exists, so return values need not be explained. It does not mention recovering the id via search_my_looks, which the schema handles, leaving only 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 baseline is 3, but the description adds cross-field meaning the schema cannot express: refs are 0-based indexes into the products array and must accompany every step sent, [] for none, and products must be sent together with steps to keep refs valid. The remaining gap is that the interplay is dense and the final sentence about unlinking is hard to parse.

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?

"Change a saved look" is a specific verb plus resource, and the description immediately qualifies it as a partial update ("Only the fields you send change"). It does not name the sibling it differs from (save_my_look, get_my_look, delete_my_look), so the agent must infer the boundary from the name alone.

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 real when/when-not guidance: steps cannot be changed while any step carries a photoUrl, and in that case the user edits in the BeautySpark app. It also states the productRefs/shadeRefs obligation per step and the refusal condition, though it never routes to an alternative tool for the blocked case.

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