Uwear

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false), the description reveals that filling can also replace an existing slot and that creator-linked slots retain a source guard. This is useful behavioral information not discoverable from annotations or the 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?

Two tightly written sentences deliver the action, target, allowed sources, exclusivity constraint, and the creator-linked guard. There is no boilerplate, repetition, or wasted wording.

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 description plus a fully covered schema and explicit ownership constraints give an agent enough to select and call the tool correctly. It lacks any return-value guidance, and since there is no output schema, a small note on expected result would make it fully complete.

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 each parameter already has a meaningful description, including the 'Use exactly one source field' constraint and the oneOf mutual-exclusion structure. The description reinforces source ownership and public URL but does not add material parameter-level 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?

The description starts with a precise verb phrase, 'Fill or replace one reference slot', names the exact resource (an existing owned avatar/model), and enumerates the three allowed source kinds (workspace file, generation result, public image URL). This makes it immediately distinguishable from sibling tools like create_avatar_from_references or upload_avatar_from_chat_file.

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 clearly scopes when the tool applies: modifying an existing owned avatar/model, filling or replacing one slot, with exactly one of three owned/public sources. It does not explicitly name sibling alternatives or state when not to use it, so it misses the top bar but provides clear usage context.

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

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

Annotations indicate not read-only and not destructive. The description adds the async generation behavior (returns generation_id and requires polling) and notes that the path is free. This is useful context beyond the annotations, though it does not cover rate limits or error cases.

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

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

Two sentences with no filler. The first sentence states purpose and the primary constraint; the second covers modes and the async follow-up. All information is front-loaded and each sentence 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?

Given the tool's asynchronous nature and high schema coverage, the description provides everything needed: input constraints, mode handling, return value, and next steps. There is no output schema, so the description's mention of the returned generation_id and polling instructions is 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?

The schema already describes each parameter (100% coverage), but the description adds the exclusivity constraint (exactly one foreground source) and the mode-specific parameter mapping (solid→color_hex, image→background_image_url). These relationships are not explicitly stated in the schema's property list, so the description adds meaningful value.

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

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

The description clearly names the operation (remove or replace an image background), the resource (Uwear's canonical free backdrop generation path), and the three modes. This is specific enough to distinguish it from all siblings, which do not cover backdrop generation.

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

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

The description explicitly requires exactly one foreground source and lists the valid options. It maps each backdrop_mode to its required parameter and provides the full post-call workflow (poll get_generation_status, fetch get_generation_results), so the agent knows exactly when and how to invoke it.

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 indicate readOnlyHint=false (so it's a mutation) but say nothing about async behavior. The description fills that gap by stating the operation is asynchronous, returns a job ID, and requires polling. It also clarifies the draft vs saved outcome. No contradiction with annotations.

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

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

Three concise sentences that front-load the core purpose, then give the save guidance, and finish with the follow-up polling instruction. Every sentence earns its place with no 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?

The description is complete for an agent to invoke the tool correctly: it explains the async queue, the save flag semantics, and the required next step (polling). The schema covers parameter details, and the lack of an output schema is compensated by the explicit job ID mention. Minor omission: no mention of prerequisites or error handling, but not critical.

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 parameters are already documented. The description adds value by explaining the practical usage of the save parameter ('Use save=true when...') and by hinting at the sources and user_text as inputs to the prompt system. This goes beyond the schema's description.

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 ('Queue') and resource ('conversation for asynchronous ArtDirection authoring'), and clearly distinguishes this from a synchronous creation by mentioning the job ID and polling. It differentiates from siblings like create_art_direction by emphasizing the async nature and the save/draft 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?

The description explicitly instructs when to set save=true vs save=false, and directs the agent to poll get_art_direction_authoring_job until done. While it doesn't name sibling alternatives like create_art_direction, it provides actionable context for the tool's primary decision (save flag) and follow-up procedure.

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, idempotentHint=true, and destructiveHint=false, establishing this as a safe, read-only, idempotent operation. The description adds the context that it should be skipped when the input prompt is already specific, which is useful but not a major behavioral disclosure. Since annotations cover the safety profile, this is adequate.

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

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

The description is exactly two sentences, front-loaded with the purpose and followed by usage guidance. No redundant phrasing.

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, side-effect-free tool with no required parameters and full schema coverage, the description covers the core purpose and the key decision of when to skip it. It doesn't explicitly state the return format, but the tool name and description imply a prompt string, and annotations cover safety. Complete enough.

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?

All 5 parameters are fully described in the schema (100% coverage), so the description doesn't need to repeat them. The description's mention of 'user's rough description' aligns with the user_text parameter, but the schema already documents each parameter thoroughly. 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?

The description clearly states the tool's function: building a highly detailed prompt for avatar/model generation. It distinguishes itself from the sibling generate_avatar by explicitly saying that if the user's prompt is already intentional, the system can skip this and pass wording directly to generate_avatar, making sibling differentiation clear.

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

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

The description gives explicit conditions for when to use this tool ('when the user wants help describing a person before image generation') and when to skip it in favor of an alternative ('if the user's prompt is already intentional and specific... pass directly to generate_avatar'). This directly addresses usage vs alternatives.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=true, and the description aligns with and reinforces these. The description adds meaningful context beyond annotations: it explains idempotency behavior in detail ('Repeated calls return or resume the same durable execution') and the execute=true default nuance. Not a 5 because it doesn't detail what destructive side effects occur or any specific auth/precondition requirements, but with the annotation set present, this is solid coverage.

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

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

The description is a single, dense paragraph of four sentences, each adding value: purpose, MCP semantics, brief_id scoping, and idempotency. It's front-loaded with the core purpose. Slightly less than a 5 because the MCP-phrase guidance is embedded in the middle rather than separated, and could be tightened, but there's no 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 2-param tool with 100% schema coverage and no output schema (so no need to describe return values), the description covers purpose, idempotency, parameter semantics, and usage context. The only minor gap is not explaining what 'execute' actually does post-confirmation (what gets generated/started) or any rate-limits/duplication risks. Given the tool's simplicity, this is well-complete.

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 adds some context for the 'execute' parameter by explaining the MCP-default behavior, and clarifies the brief_id type (visible persisted brief). However, it doesn't add much beyond what the schema's own parameter descriptions already state; the schema description of 'execute' is quite thorough already. 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?

The description clearly states what the tool does: 'approve and idempotently execute a visible persisted Uwear brief.' It uses a specific verb+resource combination and distinguishes itself from siblings like propose_brief and update_brief by focusing on the confirm+execute action. The brief_id scoping ('visible/latest BriefProposal') further disambiguates 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?

The description provides explicit guidance on MCP phrasing that should map to execute=true ('Confirm', 'looks good', 'run it', 'start', 'generate') versus when to set execute=false ('only when the user explicitly wants to save approval without starting generation'). It also references the related brief_id source (visible/latest BriefProposal), guiding which ID to use. This is explicit, actionable 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 readOnlyHint, idempotentHint, and destructiveHint, lowering the burden. The description adds valuable behavioral context beyond annotations: the result carries no live Template dependency, does not update a Workflow, and is meant for insertion through other authoring tools. This clarifies the 'read-only' nature as non-mutating to existing workflow resources.

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

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

The description is a single dense sentence that front-loads the core operation and immediately states the most important constraints: detached, no workflow update, no live dependency, and insertion via canonical authoring tools. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two well-documented parameters and safety-focused annotations, the description covers the essential context: what the output is, what it is not, and how it should be used downstream. It does not describe the exact return shape, but no output schema exists and the copy/config semantics make that less critical.

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 parameter meaning is fully carried by the schema. The description does not add new parameter-level details beyond the schema, but it does reinforce the conceptual role of contract_version through 'contract-typed' phrasing. 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: copies a generation-preset Template into a contract-typed, detached Production Workflow Generate-node config. It clearly differentiates from sibling tools like save_template, get_template, and delete_template by emphasizing detachment and the absence of a live Template dependency.

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

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

The description gives clear usage context: the tool produces a detached config that should be inserted through the canonical workflow version authoring tools. It explicitly says it does not update a Workflow, which sets expectations, though it does not name specific alternative tools for when a live workflow update is desired.

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 are all false, so no protective or destructive hints are present. The description adds the key nuance that this is a direct writer for already-structured markdown, but it does not disclose other behaviors such as validation, overwrite semantics, or return values. The parser contract is also repeated in the schema, so the marginal description value is moderate.

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

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

The description is two sentences: the first states the purpose and the second gives usage guidance. It is front-loaded, scannable, and contains no filler, making it an exemplar of concise yet informative writing.

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 creation tool with no output schema and moderate complexity, the description covers the essential decision of when to use it and what input it expects. It could mention the result of the creation (e.g., saved entity) or any side effects, but the sibling tools and schema fill most gaps. A score of 4 reflects solid but not exhaustive completeness.

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 detailed explanations for all three parameters. The description does not add extra parameter semantics beyond referencing the parser contract in content_markdown, so the baseline of 3 is appropriate.

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

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

The description begins with 'Create a company ArtDirection markdown document,' using a specific verb and resource. It immediately distinguishes the tool from its sibling author_art_direction by noting when to prefer that alternative. This makes the purpose clear and uniquely positioned among the tools.

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

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

The description explicitly states to use author_art_direction first for rough creative text or reference images, and to use this direct writer only for already-structured markdown that follows the Variation Controls parser contract. This provides clear when-to-use guidance and names the alternative.

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 indicate a mutating, non-idempotent, open-world operation, and the description adds valuable behavioral notes: traits are never inferred (explicitly stated) and each reference fills a durable slot. This goes beyond what annotations convey, though it does not mention side effects like overwriting or return values.

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

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

Two concise sentences, front-loaded with the core purpose and followed by a key behavioral constraint. Every word adds value; no filler or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has a nested reference structure and an output that is not documented (no output schema). While the schema covers the input details, the description omits any mention of return values or error behavior, which could leave an agent uncertain about the result. However, given the complexity and the richness of the schema, the description is largely adequate.

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

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

Schema coverage is 80% and already describes most parameters, including the 'Never inferred' note on traits. The description adds a little context (durable slots) but largely relies on the schema. Since coverage is high, the 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?

The description clearly states the tool creates a reusable avatar from an ordered set of references (generated views, workspace files, or URLs). It distinguishes itself from related siblings like save_generated_avatar or upload_avatar_from_chat_file by emphasizing the multi-source reference 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?

The description implies the tool is used when you have multiple reference sources to combine into one avatar, but it does not explicitly name alternatives or conditions for when not to use it. It gives some context but lacks explicit routing guidance compared to siblings like save_generated_avatar.

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 is a write operation (readOnlyHint=false) and not destructive. The description adds valuable context: the backend automatically analyzes the image if no description is supplied, and the tool returns a location_id for later use. This goes beyond the annotations by disclosing the auto-analysis behavior and the reusable nature of the created reference.

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

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

The description is two sentences with no filler. It front-loads the core action, then adds the conditional behavior, then a usage hint. Every sentence earns its place, and the structure is clean and scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 6 parameters, 2 required, and nested objects, the description covers the key behavioral aspects: what it creates, the auto-analysis fallback, and the returned ID. It does not explain error handling or permissions, but the schema and annotations already cover the parameter details and safety profile. For a create tool, this is reasonably complete for an agent to invoke 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 100%, so each parameter is documented in the schema. The description adds minimal extra parameter-specific meaning: it clarifies the behavior of the 'description' parameter (if omitted, backend analyzes the image). This is a useful nuance but does not substantially compensate for the schema already covering all parameters. 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?

The description states a specific verb ('Create'), a clear resource ('reusable location/scene reference'), and the source ('from an image URL'). It clearly distinguishes from sibling tools like create_tag or create_art_direction by focusing on location references. The downstream usage hint ('Use the returned location_id in propose_brief/update_brief') further clarifies its 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?

The description implies when to use the tool (to create a location reference for briefs) and gives a downstream usage hint. However, it does not explicitly state when not to use it or name alternatives like update_brief or get_location. Still, the purpose is clear enough that an agent can infer appropriate usage without explicit 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 communicate that the tool is mutating (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds minimal context by clarifying that it pairs existing garments without uploading new images, but it does not disclose additional side effects, permissions, or return behavior beyond what is implied.

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

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

The description consists of two concise sentences, with the primary purpose front-loaded and no redundant or extraneous information. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple create operation with full schema coverage and clear annotations, the description adequately explains the tool's functionality. The lack of an output schema is not a major gap given the straightforward nature of the operation.

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% for all three parameters, so the description does not need to add parameter-level details. The description implicitly references the purpose of clothing_item_ids but adds no new semantics 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 clearly states the action (create), the resource (outfit), and the source (existing garment IDs). It also distinguishes from upload-related tools by noting that no new images are uploaded, making the purpose 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?

The description implies usage when garment IDs already exist and an outfit needs to be composed, but it does not explicitly state when not to use the tool or mention alternatives like propose_outfits or upload_garment_from_chat_file. No exclusions are provided.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the workspace requirement but doesn't disclose uniqueness enforcement or idempotency-related behavior (e.g., what happens if a duplicate name is submitted). No contradiction with annotations.

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

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

The description is a single front-loaded sentence that communicates the core functionality. The asset type list is slightly detailed but remains compact and 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 simple create tool with full schema coverage and no output schema, the description and schema together provide sufficient guidance. It could mention return values or duplicate-name behavior, but these are not critical for tool selection and invocation.

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

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

Schema description coverage is 100%, with both parameters fully described (name with uniqueness and maxLength; color with format example). The description adds no parameter-specific meaning beyond listing asset types, 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?

The description clearly states the action ('Create a new tag'), the resource ('for organizing assets'), and enumerates the asset types. This distinguishes it from sibling tools like list_tags and get_items_by_tag, which have different purposes.

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

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

The description provides a clear precondition ('Requires an active company workspace') and indicates a broad use case (organizing assets). It doesn't explicitly name alternatives or when-not-to-use scenarios, but the context is sufficient for a simple create tool.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds the behavioral trait of permanence ("Permanently delete") and an ownership constraint, which are not explicitly stated in annotations. This goes beyond the minimal annotation information.

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

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

The description is two concise sentences, clearly front-loaded with the action and resource. No redundant phrasing or filler. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete tool with one parameter and no output schema, the description covers the essential context: permanent deletion and a key caveat about owner-only templates. It could mention error conditions or permissions, but given the tool's simplicity, it is sufficiently complete.

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 schema covers 100% of parameters with a single template_id and its description. The tool description does not add significant semantic detail beyond the schema, and the schema already describes the template as a 'company template.' The parameter is straightforward, 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 clearly states the action: "Permanently delete a library template." This uses a specific verb (delete) and resource (library template), which directly distinguishes it from sibling tools like get_template, save_template, and list_templates.

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

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

The description includes an important usage exclusion: "Owner-only templates must be deleted through their owning resource." This provides guidance on when NOT to use this tool, implying an alternative exists. It could be improved by explicitly stating the general use case (delete any library template) but the purpose makes it evident.

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 indicate a non-read-only, non-destructive mutation (readOnlyHint=false, destructiveHint=false). The description adds context that the copy is 'editable' and that the source can be system or company, but it does not disclose details like whether the original remains unchanged, permissions required, or potential side effects. With annotations providing baseline safety info, this is adequate but not rich.

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 sentence that is direct and complete. It conveys the core purpose without extraneous detail, making it easy to parse and understand.

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 should at least hint at the return value, but it only says the result is an 'editable company copy' without specifying what is returned (e.g., the new copy's ID). It also omits whether the original is preserved, though that is implied by 'duplicate.' For a simple tool, this is minimally sufficient but leaves some 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 covers both parameters (art_direction_id and name) with descriptions, achieving 100% coverage. The description does not add any additional meaning about parameter usage beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the action (duplicate), the resource (system or company ArtDirection), and the outcome (an editable company copy). This distinguishes it from sibling tools like create_art_direction or update_art_direction by focusing on the duplication aspect.

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

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

The description implies when to use this tool (when you want an editable company copy of an existing ArtDirection) but does not explicitly mention alternatives or exclude other tools. It lacks direct guidance such as 'use instead of create_art_direction when you want a copy based on an existing system or company ArtDirection.'

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the agent knows it is a safe calculation. The description adds no behavioral context beyond the name, such as whether the estimate is approximate or depends on current pricing. It does not contradict the annotations.

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

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

The description is a single, focused sentence with no extraneous words. It is front-loaded with the verb and object. While it is brief, this is not a flaw; 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?

Despite having six parameters and no output schema, the description does not clarify what the tool returns (e.g., a numeric credit amount, a breakdown) or how the estimate is computed. The annotations cover safety but not functional expectations. This leaves the agent guessing about the tool's output.

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 input schema provides 100% coverage of all six parameters with descriptive details (e.g., operation enum values, duration constraints, generate_audio doubling cost). The description adds no additional parameter semantics, so the baseline score 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 clearly states the tool's function: estimating credit cost for an operation, using the specific verb 'estimate' and resource 'credit cost'. It is distinct from sibling tools like get_user_credits and create_credit_checkout_session, which deal with balance and purchase rather than cost estimation. However, it lacks detail on the range of operation types covered.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, such as having an operation in mind, or exclusions like needing to check actual credit balance. Sibling tools are not referenced.

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 are all false (readOnlyHint: false, destructiveHint: false), so the description carries the disclosure burden. It explains the prerequisite and classification action but does not reveal side effects like whether it finalizes the garment, consumes handles, or is idempotent. Some scope constraints are added, but deeper behavior remains opaque.

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

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

The description is three sentences, front-loaded with the prerequisite ('Second step only'), and every sentence adds value: prerequisite, action, and exclusion. No fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description doesn't need to explain return values. It covers the two-step flow, the requirement for prepared/uploaded handles, the classification scope, and explicit non-uses. It could mention that it ultimately creates/updates garment records, but the schema's garments array implies this. Fairly complete for an agent.

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 detailed field explanations (e.g., upload_handle description, asset_kind enum, processing_mode). The description only restates the classification concept (full/detail front/back/side) without adding new parameter-level semantics beyond what the schema already provides. 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?

The description clearly states the tool's purpose: 'Second step only for local garment images already prepared with prepare_local_garment_upload' and 'Classify each upload_handle as a full/detail front/back/side asset.' It explicitly distinguishes itself from tools for ChatGPT attachments or public URLs, making it highly specific.

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

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

The description gives explicit usage conditions: 'Second step only' and 'uploaded to every returned target.' It also includes a clear exclusion: 'Do not use this for ChatGPT attachments or arbitrary public URLs.' This effectively tells the agent when to use it versus alternatives.

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

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

Annotations include destructiveHint=true and readOnlyHint=false, which the description does not contradict. The description adds behavioral context beyond annotations: traits are never guessed, and the multi-view generation workflow is explained. It doesn't discuss side effects or non-idempotency, but annotations cover that partially. Overall it adds useful context.

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

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

The description is well-structured with the core purpose front-loaded, followed by workflow and guidance. It is slightly long but every sentence serves a purpose, and it avoids redundancy with the 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?

For a tool with 11 parameters and many sibling tools, the description covers the essential workflow, the default view, and when to route to other tools. It doesn't explain output format (no output schema) or some self-explanatory params, but given the complexity, it is sufficiently complete.

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. The description adds meaning to identity_reference_urls by explaining the draft flow and how to use the bust URL. It also clarifies that build, age_range, and height_cm are user-given and never inferred. This enriches the schema definitions.

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

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

The description clearly states the tool generates reusable avatar/model references and distinguishes it from siblings like build_avatar_prompt (for description writing) and save_generated_avatar (for saving). It specifies the default view and the intended use case.

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

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

The description gives explicit workflow guidance: generate the bust first, pass its URL as identity_reference_urls for slot views, then save with save_generated_avatar. It also names when to use build_avatar_prompt instead and when to pass the prompt directly. This is clear and actionable.

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, covering the safety profile. The description adds the term 'selectable,' which suggests a filtering or state-related behavior not present in annotations, but it is vague. No additional details about not-found behavior or response format are provided.

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

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

The description is a single, concise sentence (7 words) that is immediately understandable. There is no fluff or redundant information, and the key information (get by ID) is front-loaded.

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 get-by-ID tool with one parameter and strong annotations, the description is largely sufficient. However, the term 'selectable' introduces ambiguity about whether non-selectable ArtDirections are excluded, and without an output schema, the description does not clarify the return structure beyond implying the ArtDirection object. This leaves some context 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 input schema already fully describes the single parameter (art_direction_id with type and description). The description's 'by ID' reinforces the parameter's purpose but adds no new semantic detail. Baseline of 3 applies due to 100% schema coverage.

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

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

The description clearly states the action (Get) and the resource (ArtDirection) with a specific scope (by ID). It distinguishes from list_art_directions by implying single retrieval, though it doesn't explicitly differentiate from other get_* tools. The word 'selectable' adds a minor qualifier but the core purpose is clear.

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

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

No guidance is given on when to use this tool versus alternatives like list_art_directions or get_art_direction_authoring_job. The description only states what it does, not the context or exclusions. There is no mention of prerequisites or when to prefer this over other retrieval methods.

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 description goes well beyond the annotations (readOnly, idempotent, non-destructive) by detailing what a done job includes (authored markdown, optional saved art_direction_id), what iteration jobs expose (source ID, expected revision, apply outcome), and what a failed job provides (per-source status, safe failure reason). This gives the agent a clear behavioral model for expected outputs and 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?

The description is compact and front-loaded, opening with the core purpose in one sentence. Each subsequent sentence adds distinct value (polling semantics, done job payload, iteration specifics, failure handling). No superfluous words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema, the description sufficiently explains return values and states: done vs failed, what each contains, and special cases for iteration jobs. It also covers the async polling pattern and save flag behavior, making the tool's behavior fully understandable for a complex async operation.

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 schema already describes job_id with 100% coverage, but the description adds important context by clarifying that the job ID can come from either author_art_direction or iterate_art_direction, extending the schema's mention of only the former. This enriches the agent's understanding of valid 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?

The description clearly states the tool's purpose: to read an asynchronous ArtDirection authoring job. It uses a specific verb ('Read') and resource ('ArtDirection authoring job'), and distinguishes itself from sibling tools like get_art_direction by focusing on polling job status rather than fetching a direct entity.

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

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

The description provides clear usage context: poll the job ID returned by author_art_direction or iterate_art_direction until done/failed. It names the source functions and describes polling behavior. However, it does not explicitly state when not to use this tool or mention alternatives like get_art_direction for direct retrieval, so it stops short of a 5.

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/idempotent/non-destructive, but the description adds essential behavioral context: it loads 'unchanged,' rejects placeholder/guessed IDs, and is not for starting new shoots or editing. This goes beyond the annotation flags without contradicting them.

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

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

The description is four sentences, front-loaded with the core function, then usage rules, then exclusions. Every sentence adds necessary guidance with zero fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description fully covers the tool's purpose, constraints, and relationship to alternatives (update_brief). With one well-documented parameter and rich annotations, no critical information 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 parameter description already provides semantics: 'Real persisted brief ID to load unchanged. Do not use 0, guessed IDs...' The description reiterates these constraints but does not add significant new meaning beyond usage context, which is already covered by guidelines. 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?

The description opens with a specific verb+resource: 'Load an existing persisted brief unchanged by a real positive brief_id.' It clearly distinguishes from siblings by explicitly stating when to call update_brief instead of looping on get_brief.

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

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

The description provides explicit when-to-use conditions ('Only use when the user supplied that brief_id or after propose_brief/update_brief returned it') and when-not-to-use ('Never use this to start a new photoshoot' and 'call update_brief instead' for modifications). It names the alternative tool update_brief 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 already declare the operation as read-only, idempotent, and non-destructive. The description adds useful behavioral context by specifying exactly what it returns and that it is scoped to the authenticated connection, without contradicting the annotations.

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

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

The description is two sentences with no filler. The first sentence front-loads the core function, and the second adds the key usage context. Every sentence 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?

For a zero-parameter getter with rich annotations and no output schema, the description adequately explains both the return values and the operational context. Nothing critical is missing for an agent to decide when and how to invoke 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?

The tool has zero parameters and the schema is fully self-documenting with an empty properties object. The description therefore has no parameter burden to carry, and a baseline of 4 for zero-parameter tools is appropriate.

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

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

The description states a specific verb ('Return') and resource ('profile ID and active company ID used by this authenticated MCP connection'), making it clear what the tool does. This distinguishes it from the many get_* siblings, which operate on different resources.

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

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

The description explicitly instructs when to call this tool: 'Use this before a paid operation when a release or audit must prove the connection is scoped to the intended Uwear account.' It does not explicitly state when not to use it or name alternatives, but no sibling appears to overlap with its purpose.

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, idempotentHint=true, and destructiveHint=false, so safety profile is covered. The description adds no extra behavioral context (e.g., not-found behavior, return details), but with annotations present, the value added is limited. It does not contradict 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?

One short sentence that is front-loaded and earns its place. No wasted words or redundant restating of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a simple get-by-ID with one parameter and no output schema. Annotations cover the safety profile. The description plus schema is sufficient for an agent to invoke it correctly; no additional detail is essential.

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

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

Schema description coverage is 100%: the single parameter garment_id is fully described as 'The garment ID to retrieve'. The description 'a specific garment by ID' adds no new semantic meaning beyond what the schema already provides, 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?

The description 'Get a specific garment by ID' clearly states the verb (get), resource (garment), and singular scope (specific, by ID). It distinguishes this tool from siblings like list_garments, which retrieves multiple garments.

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

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

The description implies usage when you need one garment by ID, but it does not explicitly state when to use this tool versus alternatives like list_garments or update_garment. No when-not-to-use or alternative names are provided, so it only meets the implied usage level.

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?

Despite readOnlyHint and idempotentHint annotations, the description reveals non-obvious behavior: 'They are display previews, not originals: url/download_url are originals, preview_url is the fallback link, and poster_url/thumbnail_url is a video poster.' It also warns against Markdown-embedding result URLs and mentions that raw payload is returned when available, providing significant context beyond annotations.

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

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

The description is long (about six sentences) but each sentence provides necessary information for correct usage, such as URL semantics, ID handling, and confirmation-flow guidance. It is front-loaded with the purpose but the later section on confirmation clients could be separated for better scannability. Still, no sentence is 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?

For an 18-parameter tool with no output schema, the description thoroughly covers retrieval modes, result content (labeled ImageContent previews), URL differentiation, downstream ID usage, and date-filter examples. It addresses confirmation workflows and raw payload recovery, making it nearly self-sufficient for an agent to use this tool and understand its outputs.

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 schema covers all 18 parameters, so the baseline is 3. The description adds value by clarifying the generation_result_id vs generation_id usage and emphasizing that these integers are required for QA/edit/upscale/video commands. It also gives a semantic example for start_date/end_date, slightly exceeding 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 description opens with 'Look up generation results by exact IDs, filters, or hybrid image/name/SKU search', clearly stating the action and resource. It further differentiates from siblings by explaining the distinction between generation_result_id (single result) and generation_id (list a job's results), which prevents confusion with get_generation_status or QA tools.

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

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

The description explicitly tells when to use downstream tools: 'Confirmation-gated clients use propose_brief(commands=[...], execute_immediately=true) when the user asked to run now, update_brief for a complete command replacement, or confirm_brief(execute=true) for a visible brief.' It also provides clear guidance for using generation_result_id vs generation_id and gives a real-world example for start_date/end_date ('last week').

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds substantial behavior beyond that: preview URLs are display-only fallbacks, failed jobs return safe error details, status can remain Created while queued, and UI model names map to specific model_slug values. No contradictions with annotations.

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

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

The description is front-loaded with a clear one-line purpose and then packs dense, useful details about previews, error types, and status behavior. It is somewhat long and repeats the model_slug mapping already present in the schema, but each sentence still contributes operational value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter status tool with no output schema, the description is complete: it covers status transitions, returned fields, failure payloads, preview URL semantics, and polling guidance. An agent has enough context to invoke the tool correctly and interpret its response.

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% for the single generation_id parameter, so the schema already documents the parameter. The description does not add new meaning about generation_id itself; it lists return fields and behaviors, which is useful but not parameter-specific. 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?

The description opens with a specific verb and resource: 'Check generation job status.' It clearly distinguishes this status-checking tool from result-fetching siblings like get_generation_results by focusing on job progression and return metadata rather than final outputs.

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

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

The description provides practical usage guidance: avoid tight polling loops while status remains Created, use completed previews directly, and never Markdown-embed result URLs. It does not explicitly name alternative tools or give exclusion criteria, but the intended usage context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add context. It does by noting 'grouped by type' and the no-UI workflow context, which informs expected behavior. It does not contradict annotations and adds some value beyond them.

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 crisp sentences: the first states the core function, the second provides workflow context. No wasted words, information is front-loaded and immediately relevant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only lookup with two parameters and rich sibling context, the description covers the workflow and return type sufficiently. It could elaborate on the exact grouping structure, but the absence of an output schema is partially mitigated by the description's clarity.

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

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

Schema coverage is 100% with descriptions for both parameters, including allowed values for item_types. The description does not add significant meaning beyond the schema, 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?

The description uses specific verb+resource ('Get all item IDs tagged with a specific tag, grouped by type'), clearly distinguishing it from sibling tools like list_tags or propose_brief. The workflow reference further clarifies its unique role.

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 states when to use ('Use after list_tags for no-UI MCP requests'), provides a concrete example ('use my clothes tagged summer26'), and names an alternative ('instead of opening request_user_context'), giving strong usage 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the context that the location is 'reusable' and a 'scene reference', but does not disclose any additional behavioral traits such as error handling or response details.

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

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

The description is a single, front-loaded sentence that communicates exactly what the tool does with no wasted words. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter read operation with strong annotations, the description is nearly sufficient. It clearly identifies the resource and method, though a brief note about the return value would make it fully complete.

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 only parameter 'location_id' is clearly described in the schema. The description adds no new parameter information beyond 'by ID', so it does not elevate above the baseline for full schema coverage.

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

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

The description uses a specific verb 'Get' with a clear resource 'reusable location/scene reference' and method 'by ID', making its function unambiguous. It naturally distinguishes itself from sibling tools like list_locations and create_location by implying a single item lookup.

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

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

The description implies usage (retrieve a location when you have its ID) but provides no explicit when-to-use guidance or mention of alternatives like list_locations for browsing. There is no guidance on when not to use it.

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, covering the safety profile. The description adds meaningful behavioral context beyond annotations by stating that the response includes the outfit's member garments, which is valuable given there is no output 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?

A single sentence delivers the essential message with no filler. The subject and action are front-loaded, and every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-ID read operation with strong annotations and full schema coverage, the description is complete. It clarifies the return composition ('member garments'), which is the main missing piece in the absence of an output schema.

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 outfit_id parameter is already well-documented with type, minimum, and meaning. The tool description adds no additional parameter semantics, 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 uses a specific verb ('Get') and resource ('one saved outfit by ID') with an added qualifier ('including its member garments') that distinguishes it from list_outfits and get_garment. The scope is precise and immediately understandable.

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 clearly implies this tool is for retrieving a single saved outfit when the ID is known, which differentiates it from sibling tools like list_outfits. It provides clear context but does not explicitly name alternatives or state when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the canonical-company scope and the two lookup paths, but doesn't disclose return shape, error behavior, or the exact-one-identifier expectation.

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 and identifier modes, followed by the one conditional parameter note. No filler or repetition.

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 only three optional parameters and rich schema descriptions, the description is mostly sufficient, but it does not state that exactly one of template_id or share_code is needed, nor what a successful load returns. Since there is no output schema, a bit more return-value clarity would improve completeness.

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 reinforces when expected_template_kind matters but adds no new meaning beyond the schema's own descriptions of share_code, template_id, and the expected-kind mismatch behavior.

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 ('Load'), a specific resource ('one canonical company template'), and two concrete identifier modes (ID or public t-xxxx share code). This clearly separates it from siblings like list_templates, save_template, and delete_template.

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 explicitly tells the caller when to supply expected_template_kind ('when the caller requires a generation_preset or batch_workflow'). It doesn't explicitly name alternative tools or exclusion cases, but the single-template load intent is clear enough for tool selection among the siblings.

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, idempotentHint=true, and destructiveHint=false. The description adds the context that it retrieves the 'current' balance for the user, which is useful but minimal. It does not contradict annotations.

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

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

The description is a single, clear sentence with no wasted words. It is immediately understandable and well-structured.

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 tool with no parameters and rich annotations, the description sufficiently communicates the operation. It does not describe the return format, but given the low complexity, this is an acceptable 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?

The tool has zero parameters and schema coverage is trivially 100%, so the baseline is 4. The description adds no parameter details because there are none to describe.

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

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

The description clearly states a specific verb ('Get') and resource ('user's current credit balance'), which distinguishes it from related tools such as create_credit_checkout_session and estimate_cost. It is slightly more specific than the title, though it does not explicitly mention alternatives.

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

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

No guidance is provided about when to use this tool versus alternatives. The description does not mention any exclusions or context for use, leaving the agent to infer from the name alone.

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 indicate a destructive, non-idempotent write operation. The description adds substantial behavioral context beyond annotations: it is asynchronous (queue + poll), mentions stale-edit protection, and imposes a system-ArtDirection draft-only constraint. These details are not in the annotations and are crucial for correct usage.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then explains save modes and constraints, and ends with the polling instruction. Every sentence 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?

Given the tool is a queue-based revision with 7 parameters and no output schema, the description covers the essential aspects: async behavior, save modes, system constraint, and how to retrieve results. It omits error handling and prerequisites, but these are secondary for a queue tool and the guidance is sufficient for correct invocation.

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 adds value by clarifying that existing authoring references are included automatically and explaining the save parameter's behavior in plain terms, which is not fully captured in the schema. It also implies that sources are additive.

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

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

The description clearly states the tool queues a feedback-driven revision of an existing ArtDirection without resending its markdown, which is a specific verb+resource action. It also distinguishes between save=false (draft) and save=true (update), and implies this is distinct from update_art_direction by emphasizing feedback-driven async revision.

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 guidance on the save parameter (false for draft, true for update with stale-edit protection) and notes System ArtDirections support drafts only. It also instructs to poll get_art_direction_authoring_job for the result. However, it does not explicitly name alternative tools or state when not to use this tool, so some inference is left to the 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context about the returned format (compact summaries), inclusion of system and company ArtDirections, and query behavior for natural-language requests, which is useful beyond annotations.

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

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

The description is three sentences, front-loaded with the primary function and using each sentence for distinct guidance: output scope, query usage, and follow-up action. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is a simple list operation with optional parameters and no output schema, but the description covers what is returned (compact summaries), what is included, how to use it in the workflow, and where to go for full details. It is fully contextualized within its sibling set.

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 already documents page, limit, and query. The description adds slight nuance by explaining query can match exact names and natural-language creative requests, but this largely mirrors the schema's 'hybrid search' description, so a baseline score is appropriate.

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

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

The description clearly states it lists selectable ArtDirections as compact summaries, specifying the scope (visible system plus company ArtDirections). This distinguishes it from get_art_direction, which is referenced for full documents.

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 explicitly positions the tool as the catalog step before choosing an art_direction_id for a brief and advises a fallback to the user's phrase if no match. It also directs users to get_art_direction for full markdown, providing clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description goes beyond by explaining the domain semantics (avatars vs. AI models) and the hybrid search behavior, adding useful context that annotations do not 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?

Three focused sentences, each adding value: purpose, distinction from sibling, and key parameter guidance. No redundant phrasing or unnecessary 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 list tool with 9 optional params and no output schema, the description covers the essential context: what avatars are, the alternative tool, and the critical include_image_url scenario. Pagination and date filters are left to the schema, which is sufficient given the tool's simplicity. It could mention return format, but that's not critical here.

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. The description echoes the query parameter's hybrid search behavior and the include_image_url usage, but these are already described in the schema. It adds minimal new information beyond what structured fields provide.

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 'List the user's avatars', a clear verb+resource statement. It further clarifies that avatars are the reusable people/models/mannequins in fashion terms, and explicitly distinguishes from list_models for AI engines, which differentiates it from a likely sibling.

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 explicit guidance: 'not the AI engines — for those, use list_models' directly names the alternative. It also gives a concrete usage trigger: 'Set include_image_url=true when the avatar image itself is needed.' This tells the agent when to use the tool and how to configure a key parameter.

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 read-only and idempotent behavior. The description adds meaningful behavioral context beyond annotations, such as the OR logic between body_zone and category, the expansion of body_zone to categories, and the exclusion of uncategorized garments unless include_uncategorized is true. These are non-obvious behaviors not fully evident from schema alone.

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 with no redundancy. The first states the core purpose, the second explains the body_zone/category interaction, and the third addresses the uncategorized edge case. All content is essential and front-loaded.

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 description covers the key filtering semantics and edge cases. While it doesn't describe the return format, the tool's name and read-only annotations imply a list of garments. Pagination and sorting are documented in the schema, so the description does not need to repeat them. The description is sufficiently complete for a list tool with no output schema.

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. The description adds value by clarifying the relationship between body_zone and category (ORed, expansion) and the uncategorized handling, which is not fully explicit in the schema. This improves parameter understanding beyond the individual 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?

The description states a clear verb and resource ('List user's garments') and distinguishes itself by detailing the hybrid search and structured filter capabilities. It differentiates from siblings like get_garment (single item) and get_items_by_tag (tag-specific) by implying this is the general listing tool with advanced filtering.

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

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

The description implies usage as the primary garment listing tool but does not explicitly contrast it with alternatives like get_items_by_tag or get_garment. It provides context for when to use it (e.g., when needing structured filters or hybrid search) but lacks explicit exclusionary 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 mark the tool as read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful context about the data being 'reusable location/scene reference images' and the user intent, but it does not disclose additional behavioral traits like return format, pagination behavior, or any edge cases beyond what annotations 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?

Two sentences with no unnecessary words. The description front-loads the main action and resource, then provides filter details and a use case. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 9 optional parameters and no output schema, the description is adequate for a list tool: it names the resource, the filter dimensions, and the primary use case. The comprehensive schema covers parameter semantics. It could be slightly more complete by mentioning the return type (e.g., paginated list of location references), but the current coverage is solid.

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 each parameter having a detailed description. The description's summary of filters ('IDs, tags, date range, and sort') offers a high-level abstraction but does not add meaning beyond what the schema already provides. 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?

The description clearly states the verb 'List' and the specific resource 'reusable location/scene reference images'. It enumerates filter types (IDs, tags, date range, sort) and gives a concrete use case ('pick a saved background/location reference'), which distinguishes it from sibling tools like get_location or create_location.

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 'Use when the user wants to pick a saved background/location reference for a generation' provides clear context on when to invoke this tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of full usage 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond annotations by specifying the returned information: credit costs, capability limits, and model-specific production guidance. This helps the agent know what to expect from the 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?

The description is two sentences with no filler. It front-loads the core purpose, then efficiently adds disambiguation and alternative routing. Every sentence 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?

For a simple, one-parameter, read-only list tool with full schema coverage and clear annotations, the description is complete. It tells the agent what the tool returns, how to categorize models, and which sibling to use instead. No critical information 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 schema already documents the only parameter, model_type, with a clear description covering its allowed values ('generation, edit, upscale, video, backdrop'), so schema coverage is 100%. The description adds context about model categories but does not need to repeat the schema details.

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

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

The description clearly states a specific verb and resource: 'List available AI generation models... by type', and explicitly distinguishes these AI models from human models/avatars. It also names the sibling tool (list_avatars) for the alternative, making the tool's purpose unmistakable.

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 usage guidance: this tool is for AI generation models, not human models/avatars, and directs users to list_avatars for those. This is a clear when-to-use vs alternative distinction.

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, idempotentHint=true, and destrutiveHint=false, so the safety profile is covered. The description adds that the listing is user-scoped and that outfits are saved combinations, but does not disclose pagination behavior, default filter semantics, or return shape. Given annotation coverage, this is adequate but not rich.

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

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

The description is a single compact sentence that leads with the core action and usefully clarifies what an outfit is. Every clause earns its place; there is no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list operation with full schema descriptions, annotations, and a clear resource scope, this description is almost complete. It would be fully complete with an explicit pointer to the single-outfit sibling or a note about pagination defaults, but those are already inferable from the schema.

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 is already documented with defaults and meaning. The description only summarizes parameter categories (garment IDs, active status, date range, query) and adds no new semantic detail beyond the schema. 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?

Clear verb+resource: 'List user's outfits' and defines outfits as 'saved garment combinations'. The filtering summary helps identify the operation, but it does not explicitly differentiate itself from siblings like get_outfit or propose_outfits, so it stops short of full sibling differentiation.

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 'List user's outfits' and the filter list imply this is the bulk retrieval tool for saved outfits, and the user-scoped wording signals scope. However, there is no explicit when-to-use versus alternatives, such as using get_outfit for a single outfit or propose_outfits for generated suggestions.

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, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds behavioral context by outlining a typical workflow (resolving tag names to IDs) and directing to follow-up tools, which goes beyond annotation coverage.

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 core purpose, and immediately followed by actionable usage guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description fully covers what the tool does, why it's useful (tag resolution), and how to use its output. No gaps remain.

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 has zero parameters, and the input schema is empty. The baseline for 0 params is 4 because there are no parameter semantics to explain. The description appropriately focuses on the tool's purpose and usage.

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

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

The description clearly states the tool's function: 'List available tags for the user's company.' This is a specific verb+resource+scope, and it distinguishes from siblings by explaining that this is the tag lookup tool used before other operations.

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 when-to-use guidance is provided: 'Use this to resolve user-provided tag names... before selecting garments, outfits, models, files, generations, or locations.' It also gives a concrete alternative: 'For no-UI MCP flows, find the tag ID here, then call get_items_by_tag or the relevant list_* tool with tag_ids.'

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 carry readOnlyHint=true and idempotentHint=true, and the description adds genuinely new behavioral context beyond them: templates persist but never execute generations, and 'Demo — …' templates are worked examples of the canonical command language. Nothing contradicts the annotations, which support the read-only framing.

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

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

Two sentences with the purpose and filter axes front-loaded in the first, followed by a compact behavioral caveat and a concrete next-step pointer. Every clause earns its place; there is no filler or repetition of schema content.

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 six-optional-parameter list operation with full schema coverage and safety-carrying annotations, the description covers the object's nature, all filter dimensions, the non-execution behavior, and the natural follow-up via get_template. The only shortfall is the absence of return-shape guidance, which carries slightly more weight because no output schema exists.

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 six parameters in detail, including the owner-only visibility rule and the writable/read-only enum distinction. The description adds only a light summary of the filter axes (kind, scope, use case, share code) that maps to schema parameters without deepening their semantics — 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?

The description states a specific verb and resource — 'list canonical company templates' — and enumerates the filter dimensions (kind, scope, use case, share code). It distinguishes itself from siblings by framing templates as persisted canonical commands rather than executable or writable records, and implicitly differentiates from get_template which reads a single template.

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

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

The description explicitly routes follow-up behavior ('read one with get_template before authoring a first brief or workflow') and clarifies that templates 'do not execute generations', steering an agent toward generation tools when execution is needed. It does not, however, enumerate exclusions against other browsing or search siblings such as search_uwear_library.

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

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

Annotations already indicate a non-read-only, non-idempotent, non-destructive mutation. The description adds useful context about app-only availability and session scoping, but does not disclose potential duplicate behavior or other side effects beyond what annotations imply.

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

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

The description is a single front-loaded sentence that conveys all essential information without 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 simple one-parameter mutation tool with no output schema, the description provides key context (app-only, session-scoped, append behavior) and is sufficiently complete. It does not describe return values, but that is not required given the absence of an output schema.

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% (the single parameter has a description), so baseline is 3. The description adds no extra meaning beyond 'append items' which merely restates the parameter name 'context_items'.

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

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

The description clearly states the action ('append'), the resource ('Uwear Shoot Board'), and the scope ('session-scoped'), which distinguishes it from sibling tools like mcp_replace_context (replace) and mcp_clear_context (clear).

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

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

The term 'append' implies adding to an existing board, subtly distinguishing from replace/clear siblings, but there is no explicit guidance about when to use this tool versus alternatives or 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 indicate destructiveHint=true and idempotentHint=true. The description adds behavioral value by explaining the all-or-one-type clearing behavior and the 'App-only' constraint. It does not contradict annotations and adds meaningful context beyond what the annotations 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?

The description is extremely concise—a single sentence that conveys the essential scope and behavior. Every word adds value, and it is front-loaded with the action and resource.

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 tool with one optional parameter, no output schema, and strong annotations, the description is complete. It fully covers the tool's behavior (clear all or specific type) and the app-only constraint, leaving no significant 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 100%; the parameter 'type' is well-documented with an enum and description 'Context type to remove; omit to clear the entire Shoot Board.' The description's mention of 'one context type' adds no new meaning beyond the schema, 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?

The description clearly states the tool's function: 'clear all session context items, or only one context type.' It uses a specific verb (clear) and resource (session context items/Shoot Board), and it distinguishes from sibling tools like mcp_add_context and mcp_replace_context by focusing on removal.

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

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

The description provides clear context: it's app-only and clears either all context items or a specific type. It implies when to use it (when clearing context is needed), but it does not explicitly mention alternatives or when-not-to-use scenarios. This is clear enough for the simple use 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?

Beyond annotations (destructiveHint=true), the description reveals that the tool 'spends credits' and is 'hidden from host LLMs,' adding cost and access context. It also discloses the return behavior: 'Returns the generation_id to poll via get_generation_status.' This complements the annotations without contradicting them.

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 earning its place: the action, the credit/access constraint, and the return value. No redundant detail or padding. The most important operational fact (app-only) is front-loaded.

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?

Despite having no output schema, the description explains the return value (generation_id) and how to follow up (get_generation_status). The credit spend and app-only access are covered. All 4 required parameters are described in the schema, so the description is complete for this tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it references 'user-confirmed montage clips' but does not elaborate on fit_mode, aspect_ratio, or base_resolution. The schema already documents these, so the description does not need to.

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: 'export the user-confirmed montage clips as a stitched video.' It clearly distinguishes from siblings like propose_montage and update_montage_proposal by focusing on the final export action. The phrase 'stitched video' specifies the output type.

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

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

The description explicitly states when to use it: 'App-only' and 'the MCP iframe calls this after the user presses Export on the MontageProposal card.' It also excludes host LLMs ('hidden from host LLMs') and mentions the credit cost, which is a key constraint. This effectively differentiates it from proposal-generation tools.

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

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

Annotations already mark this as non-read-only and destructive, and the description adds important behavioral context by disclosing that it 'spends credits,' is hidden from host LLMs, and returns a generation_id for later polling. This meaningfully supplements the annotation hints, though it does not detail consequences beyond credit spend.

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 deliver the key facts: what it does, who should call it, and what it returns. Every sentence earns its place, and the most critical constraint ('App-only') is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 9-parameter schema with full coverage and no output schema, the description covers the essential usage context: app-only, credit cost, caller, and returned generation_id. It is nearly complete, though it slightly undersells the one-source-input constraint among image_url, uploaded_file_id, and generation_result_id, which is only implied per-parameter.

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 each parameter is already documented in the input schema. The description does not add parameter-level meaning beyond noting the image-to-video nature, which is adequately covered by 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?

Description opens with a specific verb and resource: 'queue an image-to-video generation for a montage clip.' It further differentiates itself from siblings by noting it is app-only, hidden from host LLMs, and tied to a montage editor Generate action, so an agent can clearly tell it apart from other generation or montage tools.

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

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

The description explicitly states when this tool is used: 'the montage editor calls this when the user presses Generate on a draft clip.' It also gives an exclusion by saying it is hidden from host LLMs and names the follow-up tool, get_generation_status, for polling. This is strong usage guidance with minimal inference required.

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 read-only and idempotent behavior, so the description only needs to add extra context. It adds 'App-only' and 'session-scoped' constraints, which are useful, but 'hydrate' remains vague about whether the tool returns data, initializes the board, or both.

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

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

The description is a single sentence with no wasted words, but it is arguably too terse. The term 'hydrate' could be replaced with more explicit language, yet the structure is clean and front-loaded.

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 must convey what the agent should expect. It does not explain what a 'Shoot Board' is or what 'hydrate' returns or does, leaving significant ambiguity about the tool's actual effect and return value.

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 has zero parameters, so there is no parameter documentation burden. The baseline of 4 applies since the description doesn't need to compensate for schema gaps.

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 title 'Get Shoot Board' clarifies the retrieval intent, and the description identifies the resource ('Uwear Shoot Board') and scope ('session-scoped'). The verb 'hydrate' is somewhat non-standard but still conveys loading the board. It is distinguishable from mutation siblings like mcp_add_context, though 'hydrate' adds jargon.

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

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

No guidance is given on when to use this tool vs alternatives such as request_user_context or other getters. The 'App-only' label is a constraint, not a usage trigger, and no exclusions or alternative tools are mentioned.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the 'App-only' scope and the workspace files tab, but does not provide additional behavioral details like pagination behavior or return format. No contradictions.

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

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

The description is a single, concise sentence that is front-loaded with the core action and includes the necessary context ('App-only', 'workspace files tab'). No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a simple read-only list tool with two optional parameters and no output schema. The description states what it lists but does not describe the return value structure or pagination defaults. Given the low complexity, a brief description is mostly sufficient, but a little more detail (e.g., what fields/objects are returned) would be helpful.

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% (both 'page' and 'limit' have descriptions). The tool description adds no additional meaning for the parameters, so the baseline of 3 is appropriate.

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

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

The description specifies the verb 'list' and the resource 'uploaded files', with a clear context ('Uwear MCP workspace files tab'). It distinguishes from sibling list tools by focusing on 'uploaded files' rather than garments, avatars, etc. However, it could be slightly more explicit about what constitutes a 'file'.

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 does not provide any explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions. The 'App-only' prefix is a constraint but not a usage guideline. It gives no indication of when to prefer this over other list_* tools.

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 convey destructive and idempotent behavior. The description adds 'session-scoped' and 'App-only', which narrow the scope and provide context beyond what annotations state. This is meaningful incremental value, though it does not detail side effects.

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

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

The description is a single sentence that front-loads the action and includes key constraints. It contains no filler and every word contributes meaning.

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 description, combined with the schema's parameter descriptions, provides sufficient clarity for an agent to understand the tool's purpose, scope, and parameter semantics. The only minor gap is the undefined meaning of 'App-only', but overall it is complete for a replace tool with no output schema.

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 parameters have detailed descriptions, including the precedence relationship between context_items and context_state. The tool description adds no parameter-specific info, so the schema carries the burden, resulting in baseline 3.

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

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

The description clearly states the action ('replace') and the resource ('session-scoped Uwear Shoot Board items'). This distinguishes it from sibling tools like mcp_add_context and mcp_clear_context, which have different operations.

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

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

The description implies replacement semantics compared to add/clear but does not explicitly name alternatives or provide exclusion criteria. The 'App-only' hint offers some context but does not fully guide an agent on when to select this tool over its siblings.

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 indicate readOnlyHint=false and idempotentHint=false, which align with the write behavior. The description adds context that saves a 'child generation result' and is 'App-only,' clarifying the data model and invocation scope. It could mention return behavior, but annotations cover safety traits adequately.

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

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

Two tightly worded sentences immediately establish the tool's restricted audience and purpose. No wasted words; every element contributes essential context.

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 tool intentionally hidden from host LLMs, the description provides sufficient context for an agent to recognize it as internal. Schema covers required parameters, and the description clarifies the triggering flow. Minor gap: no return value or error behavior described, but given the 'App-only' designation, this is less critical.

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 covers all 5 parameters with descriptions, so baseline is 3. The description doesn't add new parameter-level information beyond what's in the schema, though it gives context for image_base64 and parent_generation_result_id through 'user-edited image' and 'child generation result.'

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

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

The description clearly states the tool's function: 'save a user-edited image from the shared ImageDetail retouch editor as a child generation result.' It uses a specific verb and resource, and the 'child generation result' distinguishes it from sibling save tools like save_generated_avatar.

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 states when to use: 'after the user presses Save.' Also clearly excludes host LLMs with 'Hidden from host LLMs; the MCP iframe calls this,' providing strong context for invocation.

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 description discloses key behavioral traits beyond the annotations: the returned form fields and file_field must be used, local paths must never be sent to Uwear, and a follow-up call is required. This adds essential context about the two-step protocol and response handling, compensating for the lack of an output 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?

Every sentence in the description serves a distinct purpose: scoping, prerequisites, execution details, security constraint, exclusions, and next-step instruction. It is dense yet efficient, with no redundant or filler content, and the key action is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (two-step upload process) and the absence of an output schema, the description is remarkably complete. It tells the agent exactly what to do with the response, what to avoid, and what to call next, covering all necessary context for successful invocation.

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 input schema already provides comprehensive descriptions for each parameter (file_name, content_type, content_length) with constraints like max length and MIME type enums. The description adds no new parameter-level meaning—it only restates the local path rule already embedded in the schema—so the baseline of 3 for high schema coverage is appropriate.

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

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

The description clearly states the tool's role as the first step for uploading garment images from the host's local filesystem, using specific verbs like 'prepare' and identifying the resource. It also differentiates from sibling upload tools by explicitly excluding ChatGPT attachments and public URLs, making its purpose 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?

The description provides explicit conditions for use: only when the host can read local files and perform direct multipart HTTP uploads. It also states exclusions ('Do not use this for ChatGPT attachments or existing public URLs') and directs the agent to call finish_local_garment_upload afterward, offering clear 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description discloses persistence behavior ('commands and immutable plans are persisted without translation'), error-remediation behavior (video_garment_view_not_attached response handling), and the API-only limitation of webhook configuration. It also describes the execute_immediately fallback behavior via the schema. No contradiction with annotations 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?

The description is dense and long, but every sentence earns its place: core purpose first, then command construction rules, video specifics, error handling, exclusions, and routing to update_brief. It is front-loaded with the primary purpose. Slightly over-long, but well-structured and free of redundant 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 complex tool with nested command schemas and no output schema, the description is remarkably complete. It covers command construction, required fields, source ID semantics, video asset attachment rules, error-response handling, execute_immediately semantics, creative_context requirements, and routing to update_brief. The only missing piece—exact return value—is mitigated by the description's error-handling guidance and the absence of an output schema.

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 adds meaningful guidance on top: requiring a concrete model_slug for specific command types, mandating durable command.source IDs, clarifying the role of reference_attachments for video, and explaining when execute_immediately and creative_context should be set. This elevates the semantics beyond the schema's plain 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?

The description opens with a specific verb and resource: 'Create a Uwear BriefProposal from canonical generation commands.' It clearly distinguishes itself from sibling update_brief by stating 'For changes to a visible brief, call update_brief with the complete replacement command list.' The purpose is unambiguous and 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?

The description provides explicit when-to-use guidance: when to set execute_immediately ('only when the user explicitly asks to run now'), when creative_context is required, and it names the alternative tool (update_brief) with the condition selecting it. It also gives negative constraints such as 'Never mix reference_attachments with img_ref_urls' and 'do not append recommendations beyond remaining capacity.'

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 description adds substantial behavioral context beyond the annotations: it clarifies that this tool only PROPOSES a montage for user review (not an actual export), that the user can edit/generate/export later, and that export is free while video generation costs credits. It also details how various parameters affect behavior (trim, generation, speed/mute). With annotations already declaring read-only and idempotent, the description enriches the agent's understanding of the propose-first workflow and cost implications.

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

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

The description is long but every sentence earns its place. It is front-loaded with the critical scoping statement ('ONLY for video montage...'), then systematically covers exclusions, the proposal workflow, per-item semantics, and cost behavior. The structure flows logically from when-to-use to how-to-invoke, and there is no redundant 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?

The tool is complex (nested MontageItemInput with 13 sub-properties, mixed video/image handling), yet the description covers all major aspects: item types, required fields, trim semantics, duration handling for image vs video, audio generation, aspect ratio, resolution, credit costs, and the post-proposal flow. The absence of an output schema is compensated by explaining the proposal-review-confirm sequence. This is as complete as one could expect for such a 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?

Even though schema coverage is 100%, the description adds meaningfully beyond the schema: it explains how to interpret user requests like '3 seconds each' into setting target_duration: 3 on every item, instructs to tailor per-image motion prompts and avoid generic repeated prompts, and advises inspecting the image with view_image when motion isn't specified. These are practical parameter-usage rules that go beyond the raw field 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?

The description clearly states the tool's sole purpose: video montage/stitching/export workflows, and that it PROPOSES a montage for user review. It explicitly differentiates from sibling tools like propose_brief and mcp_export_montage, and enumerates the exact trigger phrases ('create a montage', 'stitch clips', 'make a reel', etc.). This is a specific verb+resource with strong sibling differentiation.

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

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

The description provides explicit when-to-use guidance, including exact user request patterns, and equally explicit when-not-to-use exclusions (photoshoots, lookbooks, product shoots) with the correct alternative path ('request_user_context followed by propose_brief/update_brief'). It also warns against calling the tool merely because images exist in context, and clarifies that photoshoots must first be proposed as a BriefProposal. This is textbook usage 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=true and idempotentHint=true, so the safety profile is clear. The description adds behavioral value by disclosing return contents ('candidate titles, clothing_item_ids, and short rationales') and the correct follow-up action, which are not present in annotations. It doesn't contradict any annotations.

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

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

Two sentences with no redundant phrases. The first sentence introduces the tool's core purpose, and the second provides return details and workflow. Every word contributes essential information, making it efficiently front-loaded.

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 description covers the tool's purpose, return payload, and the necessary next step (calling create_outfit_from_garment_ids). Since there is no output schema, describing return contents is essential and handled well. It doesn't detail edge cases or advanced behaviors, but those are unlikely needed for a straightforward proposal 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%, with all three parameters (clothing_item_ids, max_outfits, instructions) already described in the input schema. The description adds no additional parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'use Uwear's outfit proposer to create styled outfit combinations from selected garments.' It identifies the specific resource (outfit proposals) and action (propose), and distinguishes itself from sibling tools like create_outfit_from_garment_ids by explicitly reserving that tool for a later saving step.

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

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

The description provides clear usage context: it tells the agent to call this tool to generate proposals and to call create_outfit_from_garment_ids only after the user chooses one. It doesn't explicitly list alternative tools or say when not to use it, but the workflow guidance is strong enough to guide tool selection.

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 provide destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds valuable context about credit costs (1 credit per result, no charge for already-completed rows) and that 'Retry generations can cost additional generation credits.' It also notes the tool is 'built for scale' and clarifies behavior for large batches. While it doesn't explicitly state destructive outcomes, the credit/retry details give additional transparency beyond annotations.

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

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

The description is longer than typical but every sentence carries information: purpose, usage triggers, exclusions, workflow, costs, scale guidance. It is front-loaded with the core purpose and remains organized and scannable. A slight deduction for being a bit verbose, but it earns 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?

No output schema exists, so the description should hint at expected outcomes. It does this indirectly by directing the user to call read_generation_result_qa afterward, implying the tool queues QA rather than returning results. It also covers costs, retries, scale, and when to avoid auto-invocation. Missing an explicit statement of what the tool returns (e.g., queue status or IDs), but the follow-up instruction mitigates this 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 description coverage is 100%: both generation_result_ids and max_qa_retries have descriptions that already mention credit costs and retry implications. The tool description repeats those cost mentions but does not add new semantic meaning beyond the schema. Since schema does the heavy lifting, 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?

The description states it is the 'Default tool for generation-result QA' with a specific verb (queue/run QA) and resource (generation results). It clearly distinguishes itself from view_image by explicitly forbidding substitution unless the user asks for manual visual critique. This is a specific verb+resource with sibling differentiation.

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

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

The description provides explicit when-to-use criteria ('whenever the user asks to QA, quality check, validate, review, inspect for defects, approve/reject, or assess already-created generation results'), a clear workflow ('First identify the numeric generation_result_ids, then call this tool, then call read_generation_result_qa'), and explicit exclusions ('do not substitute view_image', 'do not queue QA on your own initiative' for small batches). This fully addresses when and when not to use.

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, covering the safety profile. The description adds value by explaining the tool returns structured QA decision and issues, and advising the agent to summarize rather than give a manual opinion. This extra context about output content and expected behavior goes beyond annotations.

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

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

The description is two sentences, front-loaded with the verb 'Read' and the resource. Every clause provides useful information: purpose, sequencing, and usage guidance. No waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read-only tool, the description covers purpose, when to call, what to return, and how to handle the result. Annotations cover safety, and schema covers parameters. No output schema is needed because the description indicates structured data and summarization advice. Complete enough for an agent to select and invoke 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% for the single parameter generation_result_ids, with clear description. The tool description does not add significant parameter detail, but the schema already fully describes what the parameter means. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly states the tool reads official Uwear QA status, decision, and structured QA JSON for existing generation results. It distinguishes itself from siblings by emphasizing 'official' and 'structured' data, and explicitly contrasts with view_image, making the purpose specific and non-ambiguous.

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

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

The description gives explicit usage guidance: 'Call this after queue_generation_result_qa when the user asks to QA/check/validate/review generated outputs' and instructs to 'summarize the structured decision and issues, not a manual view_image opinion.' This clearly tells when to use it and what not to do, differentiating it from alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds crucial behavioral context: 'BLOCKS until the user confirms their selection.' It also warns against telling users to drag assets into chat and advises to skip model requests when avatars=0. No contradiction with annotations.

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

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

The description is lengthy but every sentence serves a purpose: condition, behavior, exclusions, alternatives, and special cases. It is front-loaded with the primary purpose and subsequent guidance is logically organized. It earns 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?

Given no output schema and the tool's complexity, the description is remarkably complete. It covers when to call, blocking behavior, no-UI alternatives, fallback upload procedures, and avatar handling. This is more than sufficient for an agent to decide and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds context about expected_types by explaining when to request models (optional, only if specific person is wanted) and mentions 'garment/outfit IDs or textual selectors' which indirectly relates to prompt construction. This goes slightly 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 clearly states this is the 'FIRST tool to call for a new photoshoot' when the user hasn't supplied asset IDs or selectors. It specifies the action: 'Opens the MCP app/gallery so the user can choose assets, add them to the Shoot Board, and press Confirm context.' This distinguishes it from sibling tools by explicitly withholding it when a no-UI path can resolve the request.

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

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

The description provides explicit criteria for when to use this tool ('only when the user has not supplied garment/outfit IDs or textual selectors') and when not to use it ('Do not use this when a no-UI path can resolve the request'). It even names alternatives like list_tags/get_items_by_tag/list_garments and upload_garment_from_chat_file, plus avatar fallback options.

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 are all false, so the description carries the disclosure burden. It adds meaningful behavioral context: each result fills a slot recorded in avatar_creator.view metadata, and only completed generate_avatar results are eligible. It does not discuss side effects like overwriting or reversibility, but for a save operation with no destructive hint, this is reasonably transparent.

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, no wasted words. The lead sentence states the purpose, the second explains parameter roles, and the third adds usage timing and eligibility. Information is front-loaded and easy to scan.

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 3 params, no output schema, and no nested objects, the description covers the key operational constraints: when to invoke (after generation, user choice), eligibility (only generate_avatar results), and how results map to slots. It does not state what the response returns (e.g., saved avatar ID), but given lack of output schema, this is a minor gap.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the roles of generation_result_id as 'identity-anchor result' and additional_result_ids as 'view results' that fill slots in avatar_creator.view metadata. This goes beyond the schema's per-parameter descriptions, which individually explain what the IDs are but not their functional relationship in the saved avatar.

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 ('Save') with a specific resource ('completed generate_avatar image results') and outcome ('as one reusable avatar/model'). It clearly distinguishes from sibling tools by restricting to generate_avatar results, unlike upload_avatar_from_chat_file or create_avatar_from_references.

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 timing context: 'Use only after generation finishes and the user chooses the candidates.' Also includes an exclusion: 'Normal text-to-image results are not eligible.' While it doesn't name alternative tools, the guidance clearly indicates when to use and when not to use, differentiating from related file-upload or reference-based avatar creation tools.

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 idempotentHint=false, so the description doesn't need to restate those. The description adds valuable behavioral context: the batch nature of the operation, the ordering requirement between files[] and image_file_N, and the constraint that inputs must be chat file references (no base64, no local paths). It also clarifies the destination ('Files library'). This goes beyond the annotations without contradicting them.

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

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

The description is three sentences with zero waste. The core action and destination are front-loaded, followed by the critical ordering instruction, then the exclusion clause. Every sentence earns its place and the most important operational detail (ordering) 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?

For a 14-parameter batch upload tool with no output schema, the description covers the essential operational semantics: what to pass, how to order it, what not to pass, and when to use it. The only minor gap is that it doesn't describe the return value or success/failure behavior, but with no output schema and the annotations covering safety, this is a minor omission. The description is complete enough for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters. The description adds critical cross-parameter semantics: the ordering relationship between files[] and image_file_1..10, and the rule that image_file_N should be used when the matching item has no image_url. It also clarifies that files[] holds metadata while image_file_N holds the actual file references. This is meaningful value 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 ('Batch save'), a clear resource ('reference images from chat attachments into the Files library'), and explicitly distinguishes the tool from related upload tools by excluding garments and avatars. It also names the sibling tools it is not (upload_garment_from_chat_file, upload_avatar_from_chat_file) implicitly through the exclusion clause.

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

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

The description explicitly says when to use this tool ('Use for mood boards, backgrounds, and other reference images') and when not to use it ('not garments or avatars'). It also provides critical usage instructions: keep metadata in files[] and pass top-level image_file_1, image_file_2, etc. in the same order, and warns against base64 or local paths. This is 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 destructiveHint=true, and the description adds genuinely non-obvious behavior beyond that: 'updates are complete replacements' (full overwrite, not patch), the expected_revision concurrency requirement, and the fact that it 'persists the template and does not generate images.' No contradiction with annotations; the only unstated behaviors are revision-conflict handling and authorization requirements.

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?

Five dense sentences with the primary purpose front-loaded. Each sentence earns its place: create/replace semantics, complete-replacement behavior, persistence and non-generation, single-generation scope, and routing to alternatives. Slightly long but zero redundancy with the 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?

For a create/replace tool with a fully self-documenting schema (100% description coverage) and destructive hint already set, the description covers the critical decision layer: when to use, what the payload must be, what the operation does and does not do, and where the alternatives lie. Remaining gaps are minor — no mention of revision-conflict error behavior or return value, but no output schema exists and these are secondary for a save operation.

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. The description adds usage-level meaning by pairing template_id with expected_revision in the replacement path and by framing the payload contract — 'Send typed GenerationCommand objects; updates are complete replacements' — which tells the agent the payload is structured and the operation is wholesale, not incremental.

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+resource pair — 'Create a canonical company template, or replace one by passing template_id with expected_revision' — and further disambiguates from image-generation siblings by stating it 'does not generate images,' and from legacy templates by declaring them read-only history. An agent can distinguish this tool from list_templates, get_template, delete_template, and generation tools 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?

The description gives explicit when/when-not guidance with named alternatives: single-generation presets belong here; 'Use Production Workflows in the Automation workspace for reusable multi-step generation'; and 'Legacy batch Templates are read-only history and cannot be created, edited, or imported.' This is the strongest form of usage guidance — explicit exclusions plus alternative tooling.

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/idempotent annotations, the description discloses important behaviors: lexical matching requires every word to match, vector results stay close to the best match, interactive searches do not refresh the index, and indexed_count is always 0. It also states the shape of returned selection data, which matters because no output schema is present.

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

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

The description is long but dense, front-loading the core purpose and usage before edge-case caveats. Almost every sentence earns its place, though the indexed_count caveat and repeated querying guidance push it toward the longer end of what is ideal.

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?

Because there is no output schema, the description compensates by explaining that it returns stable typed IDs, ids_by_type, detail_tool/detail_arguments, and selection hints, and by explaining how to use art_direction_id in briefs. It covers query constraints, index behavior, and sibling routing, leaving no critical gap for correct invocation.

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. The description adds value by providing concrete example queries ('SKU 42', 'urban art direction', 'summer denim') and clarifying query formulation behavior beyond the schema's phrasing, such as the one-concept-per-call rule and the exact-name/SKU/ID fallback.

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 resource: universal hybrid retrieval across the user's visible Uwear library, and enumerates all covered item types. It also explicitly disambiguates from recommendation tools by saying 'This is a finder, not a recommender' and from outfit workflows by routing to list_outfits/propose_outfits.

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 when-to-use guidance: short 2-5 word queries, one concept per call, exact name/SKU/ID or before opening the picker, with examples. It names alternatives for saved outfits, instructing the agent to retrieve garments first and then call list_outfits or propose_outfits, which makes tool selection explicit.

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