Able.Style

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

Annotations declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is already structured. The description adds genuinely new behavior: authentication is required and a missing session triggers an OAuth flow, plus the hard prerequisite that a prior suggest-outfit-tool result must exist. It does not discuss reversibility or idempotency beyond what the annotations 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?

The alias/deprecation notice and use cases are appropriately front-loaded, but the closing paragraph about locating the styleId largely repeats the verbose schema description of the same parameter, and the 'Do not claim you cannot see the styleId' warning is a guardrail rather than tool semantics. Structure is sound; redundancy drags it down.

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 values need no explanation, and the description covers everything else an agent needs: alias status, preferred alternative, auth requirement and OAuth trigger, the upstream suggest-outfit-tool dependency, and the purpose of the wardrobe write. Nothing required for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description still adds value beyond the schema by naming the exact path (outfitItems[i].styleIdentifier.styleId) that the required styleId must come from and by framing the failure mode (ask the user or request a new outfit suggestion).

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+resource ('Adds or removes a known clothing item from the user's personal wardrobe by its style ID') and immediately distinguishes itself from its sibling by declaring it a backward-compatible alias and naming add-to-or-remove-from-wardrobe-by-id as the preferred call. An agent can select correctly without opening either 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?

It states when to use the tool ('users want to track clothing items they own or indicate they have something similar'), supplies concrete example utterances, and explicitly names the alternative ('Prefer add-to-or-remove-from-wardrobe-by-id for new calls'). Both the when and the routing are covered.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is largely covered. The description adds genuinely new context: authentication is required and an OAuth flow will trigger if the user is logged out, plus the downstream effect that wardrobe items personalize outfit suggestions.

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?

Purpose and use cases are front-loaded, which is good, but the closing paragraph is bloated with repeated, near-identical warnings about not fabricating the styleId and re-examining context. The same admonition appears in both the description and the styleId schema field, so it does not earn its length.

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 no explanation, and the description covers the auth requirement, the required upstream suggest-outfit-tool call, and the fallback behavior. Complete for correct invocation, with only the sibling-disambiguation gap remaining.

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 documents every parameter, including the enum for addOrRemove and the sourcing of styleId/isUserStyle/styleDescription. The description repeats rather than extends that guidance, so the 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 pair and resource ('Adds or removes a known clothing item from the user's personal wardrobe by its style ID'), which implicitly distinguishes it from the from_description and from_image siblings. However, it never explicitly differentiates itself from add-to-or-remove-from-closet-tool, which sounds near-identical in purpose.

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 concrete when-to-use triggers ('Add this to my wardrobe', 'I have a similar jacket'), the prerequisite that a prior suggest-outfit-tool call must exist, and an explicit when-not path ('If no valid styleId is available... do not call this tool'). It stops short of naming sibling alternatives such as add_wardrobe_item_from_image.

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 cover the safety profile (readOnly false, idempotent false, non-destructive), and the description adds real behavior beyond them: a hard precondition that the description must contain exactly one item with explicit colour, an instruction to prompt the user rather than invent a colour, the menswear/womenswear override semantics, the returned review link, and the disclosure that a new item's image may still be generating in the background.

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?

Front-loads purpose and the primary alternative before the conditional detail, and every sentence carries a distinct rule. It is on the long side and the colour/exactly-one-item constraint is repeated from the schema description, which is mild redundancy rather than 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 mutation tool with an output schema, the description covers preconditions, sibling routing, override semantics, and a hint about the returned review link and background image generation. An agent has everything needed to decide and call 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%, and both schema properties already carry detailed descriptions (10–150 chars, exactly one item, colour required, override of profile preference). The description restates that content rather than adding syntax or format detail beyond it, so the 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 ('Adds'), resource ('one item ... to their Able.Style wardrobe'), and the input source ('from a text description supplied by the user'). The scope is narrowed to exactly one owned item, which separates it from the by-id, from-image, and closet siblings.

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

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

Explicit routing rules: use this when the user describes an item in words; use add_wardrobe_item_from_image when a photo/attachment/URL is the source; fall back to create_image_upload with purpose wardrobe_image_add if transfer is unavailable; use add-to-or-remove-from-wardrobe-by-id for items already returned by suggest-outfit-tool. It even names an anti-pattern (don't infer a description from an image) and a blocking precondition (ask for colour if missing).

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 write/idempotent/non-destructive/open-world, yet the description adds the contract details that matter: the server processes the actual image, exactly one of file/imageUrl/image.data must be supplied, formats and 10 MB cap, the prohibition on inventing file IDs or URLs, and the exact fallback sequence with the same requestId. This goes well beyond what the annotations convey and is internally consistent with idempotentHint.

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?

Front-loaded with purpose and usage, then requirements, then fallback; nearly every clause is actionable. It is dense and slightly long, but no sentence is 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?

For a five-parameter mutation with nested input objects and no output schema, the description covers the trigger, input alternatives, validation limits, anti-fabrication rules, and how to retrieve the result via get_wardrobe_image_activity, leaving nothing essential to inference.

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% and nested objects are documented, so the baseline is 3, but the description adds critical semantics the schema omits: the three image inputs are mutually exclusive ('provide exactly one of'), requestId must be generated and reused for retries/fallback, and fabricated IDs are forbidden. The menswearOrWomenswear default is already in the schema, so only modest extra value there.

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 ('Add one clothing item from the user's original image to their wardrobe') and explicitly scopes it to image-sourced adds, which separates it from the text-based sibling add_wardrobe_item_from_description. An agent can identify the tool 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?

Gives the trigger condition ('when the user attaches a photo or supplies an image URL and asks to add/save the pictured item'), an explicit exclusion ('Do not replace this flow with add_wardrobe_item_from_description or your own visual interpretation'), and a named fallback path (create_image_upload plus get_wardrobe_image_activity).

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, idempotent, non-destructive, not open-world), but the description adds a substantive behavior the annotations do not: it will never trigger an authentication flow. That negative behavior is exactly what an agent needs to know. It stops short of explaining how the status is obtained or refreshed, so not a full 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, front-loaded with what the tool does and then the critical usage restriction. Every clause earns its place with no 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 described. For a zero-parameter, read-only status check, the description covers purpose, invocation context, and the key behavioral caveat — nothing an agent needs 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?

The tool takes zero parameters, so there is no parameter semantics to document; baseline is 4. The description correctly refrains from inventing inputs.

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 — checking whether the current Able Style app session is signed in — with the scope ('app session', 'current') made explicit. No sibling tool touches authentication, so there is no ambiguity to resolve.

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 both a when ('checks the current session') and an explicit when-not ('must not be called by the model'), plus the rationale that it is an app-only tool that never starts authentication. This is unconditional routing guidance an agent can act on directly.

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 cover safety and idempotency, and the description adds context beyond them: it discloses the return fields (uploadId, uploadPageUrl, expiresAt), the idempotency mechanism (reuse requestId for retries), and critically the side-effect boundary ('Creating the link does not upload the chat attachment or add the item'). That last point is exactly the kind of non-obvious behavior an agent needs before calling a non-read-only tool.

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?

Front-loaded with the core action and trigger, then progressively adds routing, returns, and workflow. Dense and mostly waste-free, though the 'Use this even when you can see a chat photo but cannot pass its real file reference, public URL or original bytes' clause is slightly verbose and could be tightened.

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 non-read-only tool with no output schema and nested params, the description covers purpose, routing, return values, idempotency, the side-effect boundary, and the required follow-up (show uploadPageUrl and ask the user to submit). Nothing essential for correct invocation 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 only 33%, so the description must carry meaning, and it does for two of three params: it fixes purpose to wardrobe_image_add ('one clothing item per image') and explains requestId generation/reuse semantics. The nested options.menswearOrWomenswear field is left entirely to the schema description, but overall the description meaningfully supplements the low-coverage 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 ('Create a secure web or installed-app image picker') and immediately distinguishes itself from add_wardrobe_item_from_image and add_wardrobe_item_from_description. An agent can tell exactly what this produces (an upload link/picker) 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?

Gives explicit trigger conditions ('when the user asks for an upload link, or an image-based action cannot receive the original image directly'), names the correct sibling for the alternative path, and adds an explicit exclusion ('do not silently switch to add_wardrobe_item_from_description'). This is textbook when/when-not/alternatives routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by disclosing the two possible result shapes (safe failure details, or the added item and its link), signaling this is an asynchronous outcome check rather than a plain read.

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: the purpose and return shape come first, the parameter sourcing last. 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 no output schema, the description appropriately summarizes the return payload, and annotations cover the safety profile. The remaining gap is that it never indicates whether the action resolves immediately or must be re-polled, which matters for a status-check 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 0% for the single activityId parameter, and the description compensates by naming the exact sibling tools that mint that ID. It does not describe the ID's format or lifetime, but the origin guidance is the meaningful missing piece and is supplied.

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 the status of an owned wardrobe image action', and further defines what the result contains (failure details vs. added item and link). No sibling in the list provides an activity/status lookup, so an agent can identify this tool unambiguously.

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 tells the agent where the required activityId comes from ('add_wardrobe_item_from_image or create_image_upload'), which routes it correctly from the two producing siblings. It does not state any when-not-use condition or polling cadence, so it falls short of the highest bar.

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 the mutation/lifecycle profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds real context beyond that: authentication is required and triggers an OAuth flow for logged-out users, and preferences feed back into future suggestions. It stops short of stating whether a removal is reversible or what the response contains, but it does more than restate the annotations.

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

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

The opening and use-case sentences are well front-loaded, but the long IMPORTANT paragraph about outfitId visibility largely duplicates the outfitId parameter description verbatim, including repeated warnings about not fabricating or claiming blindness. That redundancy inflates the definition without adding decision-relevant 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?

With annotations covering the safety profile and an output schema present, the description supplies the remaining essentials: authentication requirement, data source for outfitId, failure handling when no prior suggestion exists, and the downstream personalization effect. Only minor details (reversibility of removals, post-call state) are left unstated.

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 documents all three parameters, including the boolean semantics of 'value' and the enum meaning of 'likeOrDislike'. The description mostly repeats the outfitId sourcing guidance that the schema parameter description already contains, adding little new semantic detail. Baseline 3 applies when the schema carries the load.

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 first sentence gives a specific verb and resource: 'Records or removes a like or dislike for a specific outfit suggestion.' It also distinguishes itself from the sibling suggest-outfit-tool by naming it as the prerequisite source of the outfitId, so an agent can place this tool in the workflow without opening other schemas.

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 provides concrete trigger phrases ('I like this outfit', 'Save this to my favorites', 'Remove my like from this outfit') and explicitly states the prerequisite: an outfitId must come from a prior suggest-outfit-tool call, and if none exists the tool must not be called. It does not, however, disambiguate against save-flavored siblings such as add-to-or-remove-from-closet-tool, which is the main remaining gap.

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, idempotent, non-destructive), yet the description still adds real behavior: a five-item page size, a total match count, widget-driven auto-pagination, and the nextPageToken fallback procedure. The explicit constraint not to combine pageToken with query/sortBy/filters is exactly the kind of operational rule structured fields 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?

Front-loaded with purpose, then pagination mechanics, with no filler sentences. The pagination paragraph is slightly dense but each clause governs a distinct call pattern (widget vs. manual token), so it 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?

An output schema exists, so return values need not be spelled out, yet the description supplies cardinality and pagination semantics anyway. Combined with the conflict rule and the nested-filter hint (attribute requires itemType.category), an agent has everything needed to call this 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 coverage is 75% and the schema already documents parameter formats, so the baseline is 3. The description still adds value by illustrating natural-language query semantics ('flowery shirts'), clarifying the pageToken-alone rule, and implying the interaction between 'newest items' and sortBy.

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+resource ('browse or search their signed-in wardrobe') and enumerates the queryable dimensions (categories, colours, attributes, newest items, natural-language terms). This is clearly distinguishable from the add/remove/outfit siblings, which perform writes rather than retrieval.

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

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

Opens with an explicit when-to-use trigger ('when the user wants to browse or search their signed-in wardrobe') and includes concrete query examples. It does not name or exclude a specific alternative sibling, but the sibling set is so operationally distinct (add/remove/style) that exclusion is not strictly needed.

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 (readOnlyHint, idempotentHint, destructiveHint=false), but the description adds real value: sign-in is required, the offer is re-checked for freshness, and it explicitly is not an order placement despite the 'buy' in the name. It stops short of explaining link staleness/expiry behavior, which keeps it from 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?

Four short sentences, each carrying distinct information (what it returns, auth requirement, when to call, what it is not), with the core action front-loaded and no 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?

With an output schema present, return-value detail is unnecessary, and the description still covers auth, input sourcing, valid-offer preconditions, and the no-order-placement clarification. 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 description coverage is 0%, so the description must compensate, and it does by naming all four required inputs and their origin (the exact styleId, styleProductId, offerId and delivery country from style-purchase-options-by-id). It does not explain the format expectations (hash patterns for offerId/styleProductId) or the country enum, so a small gap remains.

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 (recheck a purchase offer, return its current retailer link) and clarifies the scope against the name's misleading 'buy'. It implicitly distinguishes itself from the feeder sibling style-purchase-options-by-id, so an agent can tell what this tool does 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?

It names the exact precondition (only when the user wants to open a retailer), the required sibling that supplies the inputs (style-purchase-options-by-id), and an explicit exclusion (do not call for offers with canBuy false). This is when-to-use, when-not, and the alternative all in one.

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?

Goes well beyond the readOnly/idempotent/openWorld annotations: it discloses the sign-in requirement, the country precedence chain (explicit > saved account > host hint), the fallback of asking the user, and the refresh semantics of re-calling with identical arguments. These are exactly the operational traits an agent cannot infer from 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?

Purpose is front-loaded in the first sentence and every subsequent sentence carries functional information (auth, ID constraints, country logic, refresh, alternative tool). It is dense but not padded; the length is justified by the amount of conditional behavior, though it could be trimmed slightly.

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 an output schema, the description covers everything an agent needs: auth, ID constraints, country resolution, refresh behavior, and the sibling to call for buy links. The return payload is only briefly summarized, but an output schema exists so that is appropriate.

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 0% and the enum country field has no per-value documentation, so the description must compensate; it does so by defining country precedence rules, the fallback when unset, and how to persist a choice, plus constraining styleId to catalog IDs only. This adds substantial meaning beyond the raw 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 ('Find matching products and retailers where the user can buy a catalog style') and its scope is clearly distinct from sibling style-purchase-buy-url, which it explicitly routes to for buy links. An agent can separate it from style-ways-to-wear-by-id and style-wear-with-get-by-id 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?

Provides explicit preconditions (requires sign-in, exact catalog styleId, userStyle IDs unsupported), resolution rules for the country parameter, and named alternatives/prerequisites (update-user-settings-tool for saving, style-purchase-buy-url for buy links, re-call to refresh). It also states what the agent should do when no country is available.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: the sign-in requirement, the pagination contract (five items per page, widget auto-loads on scroll, re-call with only pageToken to continue), and the external selection logic it mirrors. This is exactly the extra behavioral detail annotations cannot carry.

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?

Purpose is front-loaded and the subsequent sentences each carry distinct operational content (auth, ID sourcing, exclusivity, pagination). It is dense but not padded; the only soft sentence is the vague reference to matching the Able.Style page's selection logic.

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 values need no explanation, and the description still covers everything an agent needs to invoke correctly: auth, ID provenance, parameter exclusivity, and pagination. Nothing material is missing for this read-only lookup.

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 mutual-exclusion rule ('Provide exactly one of styleId or userStyleId') and the mapping from result refs to parameters (kind style → styleId, kind user_style → userStyleId). That tells the agent how to derive each ID, which the schema alone does not.

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

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

The description names a specific verb and resource — 'Get outfit inspirations showing ways to wear a particular clothing item' — and scopes it further by noting the returned tagged styles and owned userStyles. It does not, however, distinguish itself from the similarly named sibling style-wear-with-get-by-id, leaving the agent to infer the difference between 'ways to wear' and 'wear with'.

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 an auth precondition ('requires sign-in'), tells the agent where IDs must come from ('Copy exact IDs from earlier results'), and explains the continuation path for the no-widget case. It stops short of explicitly naming when a sibling tool would be the better choice, so it is clear context without exclusions.

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, idempotent, non-destructive, closed-world). The description adds real behavioral context beyond them: it requires sign-in and discloses pagination behavior (five items per page, widget auto-loads on scroll, re-call with nextPageToken as pageToken).

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?

Front-loaded with purpose, then progressively layers auth, ID semantics, and pagination. Five sentences are dense but each earns its place; only mild tightening is possible without losing operational detail.

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 paginated, dual-ID-mode tool with an output schema (so return values need not be explained), the description covers selection logic, auth requirement, ID disambiguation, and the full paging loop. Little an agent needs 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 baseline is 3, but the description adds meaning the schema lacks: it explains that a ref of kind style maps to styleId and kind user_style maps to userStyleId, and enforces exactly-one-of the two IDs. That mapping is genuine added value over the schema descriptions.

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 other styles and owned userStyles that can be worn with a particular clothing item.' This differentiates it from the similar sibling style-ways-to-wear-by-id, but that sibling is never named explicitly, so an agent must infer the distinction.

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 operational guidance (requires sign-in, provide exactly one ID, how to page), but never states when to choose this tool over the closely related style-ways-to-wear-by-id. The when-to-invoke logic versus alternatives is left implicit.

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 mark it non-readonly, non-idempotent, non-destructive; the description goes well beyond that by disclosing that results are personalized from the signed-in user's saved wardrobe, that the returned styleIdentifier.styleId values must be reused verbatim by add-to-or-remove-from-wardrobe-by-id, and that no follow-up questions should be asked.

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?

Purpose and trigger phrases are front-loaded before return and workflow details, and every block (usage, returns, downstream-call contract, link mandate) carries operative instructions. It is on the long side with some repetition across the personalization and response-requirement passages, but no sentence is pure 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?

For a 4-parameter tool with a full output schema, the description covers what remains: when to invoke it, that output is personalized to the signed-in user, how the returned identifiers feed downstream tools, and the mandatory user-facing link requirement. Nothing needed to call or chain it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with smartness, temperature, gender and inspirationId already carrying detailed mapping rules in the schema itself, so the baseline of 3 applies. The description adds no parameter-level guidance beyond what the schema provides.

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 states a specific verb (generates) and resource (personalized outfit suggestions) with its input basis (wardrobe, preferences, weather, formality). This clearly separates it from siblings like search_wardrobe or style-ways-to-wear-by-id, which retrieve existing data rather than compose an outfit.

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

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

It gives explicit trigger utterances ("What should I wear?", "Outfit ideas for [weather/event]") so an agent knows when to reach for it. However it never states when NOT to use it or names an alternative sibling (e.g., search_wardrobe for looking up specific items), so routing edge cases remain inferred.

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 the safety profile (not read-only, idempotent, non-destructive, closed-world), so those traits need not be repeated. 'One or more settings' hints at partial-update semantics but never states whether unspecified settings are preserved, what auth is required, or whether the update is atomic.

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, stating the verb, resource, and scope efficiently. It is appropriately short, though arguably thin rather than tight given the nested parameter structure it omits.

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 output schema and annotations relieve the description of explaining return values and safety traits. Still, for a mutation tool with a nested enum parameter, it omits which settings are settable and the partial-update behavior, leaving meaningful gaps.

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 0% except for a single nested field description, and the description names no parameters or settings at all. The nested 'settings' object with its three enum-constrained sub-fields (windSpeedUnit, temperatureUnit, deliveryCountry) is left entirely undocumented in prose, so the description does not compensate for the coverage gap.

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 ('Updates') and resource ('settings on the signed-in user's Able Style profile'), scoping the operation to the authenticated user. The sibling set is entirely wardrobe/outfit oriented, so there is no competing update-settings tool to distinguish from, but the description itself is 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?

Usage is implied by 'signed-in user's profile', which tells the agent this targets the current account rather than any arbitrary user. However, there is no explicit when-to-use guidance, no exclusions, and no mention of prerequisites such as authentication state.

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