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

Discloses important behaviors beyond annotations: this consumes a plan brand slot, can fail with a brand-limit error, results in the video direction drafting asynchronously, and does not spend credits. These are not inferable from `readOnlyHint: false`, `destructiveHint: false`, or the schema, and they materially affect agent decisions.

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: purpose, usage conditions, user consent, plan-limit behavior, alternatives, async follow-up, and credit disclosure. Front-loaded with the core action before routing to alternatives.

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?

Covers the full call context: when to use it, prerequisites, side effects, failure mode, fallback tools, and follow-up polling behavior. With no output schema, it still provides enough for an agent to invoke correctly and handle the outcome.

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 already documents both parameters, so the baseline is 3. The description adds context by explaining that `name` overrides the storefront-detected name and that brand attributes are drafted from the storefront scrape, slightly enriching the parameter 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?

States a specific verb and resource: creates a new brand from an identity detected on a product waiting on `brand_decision_required`, and attaches the product to it. Clearly distinguishes this from the sibling `set_product_brand`, which re-points an existing brand.

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 says when to use: when the product belongs to a company the account has no brand for, typically with a new store. Names alternatives and conditions: `set_product_brand`, optionally with `replace_identity: true`, or upgrade when the plan's brand limit is reached. Also instructs to ask the user before calling.

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 reveals asynchronous behavior: it returns product_id immediately, downloads happen in the background, and the first video-direction draft runs later. It also discloses important constraints and side effects—public URLs only, 8MB skip limit, at most 9 images used, and no credit consumption—adding real behavioral context beyond 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 front-loaded with purpose and contains no filler. It is somewhat long with multiple paragraphs, but each paragraph adds operational value—async behavior, polling instructions, alternative tool guidance, and credit semantics—so the length is justified, if not perfectly tight.

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, the description covers the full invocation picture: what inputs are needed, what happens on success, how to track progress, when to prefer an alternative, and cost implications. An agent has everything needed to call this tool correctly and interpret the immediate result.

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 all parameters. The description adds meaningful parameter-related constraints, especially for image_urls: they must be publicly reachable, cannot come from the caller's machine, images over 8MB are skipped, and at most 9 are used. This goes beyond the schema's 'Publicly reachable image URLs, most representative first' and earns more than the 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 opens with a specific verb and resource: 'Start a new InstantClips product from hosted product photos', and adds a precise scope condition ('for a product that has no public page to scrape'). It clearly distinguishes itself from import_product_from_url by naming what this tool is not for, so an agent can select it confidently.

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 to prefer import_product_from_url when a product page exists, and explains why: the scrape collects name, description, price, and brand identity for a better direction draft. It also gives lifecycle guidance: poll get_product until import_status is 'imported', making the tool's role in the workflow unmistakable.

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?

It discloses the credit charge timing, automatic refund on failure, queued return behavior, and insufficient-balance handling. These behaviors go well beyond the annotations (`readOnlyHint: false`) and tell the agent exactly what side effects to expect.

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 average but the content is almost entirely operational guidance needed for a credit-spending tool. It is front-loaded with the most critical warning, though some repetition with the title ('spends credits') and a few overlapping consent instructions add slight 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?

Without an output schema, the description explains what the call returns (`video_request_id`), how to follow up (`get_video`, 20-30s polling until `done`), and what to give the user (`output_url`, `share_url`). It also covers the insufficient-funds path, making the expected behavior 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 only parameter `product_id` has a schema description that already covers its meaning completely, so the tool description adds no new semantic information. The baseline of 3 applies because schema coverage is 100%.

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 'Render the video' and identifies the exact resource (`product_id`), so the agent knows this is the rendering action. It also separates it from siblings like `get_video` and `update_video_direction` by noting the product's current direction/settings are used as-is.

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 user approval and cost disclosure before every call, and it lists forbidden uses ('see what happens', retry in progress, self-initiated batch). It also tells the agent to poll `get_video` afterwards, giving a clear and complete workflow.

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 adds substantial behavioral detail: `import_status` value meanings, the `video_direction.drafting` readiness flag, and the meaning of `video_direction.credit_cost`. It tells the agent how the tool behaves over time and how to interpret the result.

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: the core purpose is front-loaded, and each paragraph adds necessary operational context—polling usage, status interpretation, and credit cost. 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?

With no output schema, the description carries the burden of explaining return semantics, and it does so well. It covers the key fields an agent needs to decide whether the product is ready, whether import failed, and what generation will cost, making it complete enough to use 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?

There is only one parameter, `product_id`, and the schema already describes it fully with 100% coverage. The description does not add extra parameter-level meaning, so 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 opens with a specific verb and resource: 'Read a product' and then enumerates exactly what is returned—import findings, video direction/settings, and generated videos. This clearly distinguishes it from siblings like get_video, which would focus on a single video.

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 states when to use the tool: poll after `import_product_from_url` or `create_product_from_images`, with a recommended polling interval. It also explains the readiness condition. However, it does not explicitly contrast with alternatives or say when not to use it, 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 readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds substantial behavioral context beyond that: it explains the meaning of each status, that 'done' provides output_url and share_url, that 'failed' triggers an automatic credit refund, and that a render typically takes a few minutes. It also warns against tight polling, which is a behavioral trait an agent needs. 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 moderately long but every sentence earns its place. It front-loads the purpose, then uses a bulleted list to enumerate statuses and actions. It could arguably be tightened by trimming the 'pending' line, but overall it's well-structured and free of fluff.

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

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

For a status-check tool with a single parameter and no output schema, the description is fully complete. It covers all possible status values, the meaning of each, the appropriate agent action for each, and the expected duration. It also tells the agent how to behave (inform the user). Nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 100% — the single parameter video_request_id already has a clear description ('Returned by generate_video, and listed under videos in get_product'). The tool description does not add any additional parameter-level semantics, and with full coverage 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 opens with 'Check one video's render,' which is a specific verb (check), a specific resource (one video), and an action (render status). It clearly distinguishes itself from generate_video (which creates) and get_product (which lists videos), so an agent can tell them apart without reading 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-to-use guidance: each status value comes with a recommended action — poll every 20-30 seconds for 'generating', call generate_video for 'pending', etc. It also tells the agent to inform the user rather than poll silently, which is a clear usage directive. There are no explicit exclusions, but the status-based routing fully covers the decision space.

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

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

Goes far beyond the annotations by disclosing the asynchronous behavior, the immediate product_id return, the background scrape/download/draft, the polling condition, duplicate-URL handling, the brand-decision stop state, and the credit policy. This is exactly the behavioral context an agent needs.

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

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

The description is front-loaded with the core action and return behavior, then adds only high-value operational details. Every paragraph earns its place, and the asynchronous and brand-decision caveats are clearly separated without 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 what the agent needs: the immediate return, how to check completion, duplicate handling, the brand-decision failure mode, the resolution path, and the credit implications. This is complete for a complex side-effecting tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful value for brand_id by explaining when it is appropriate to pass it, how the tool behaves without it, and that list_brands exists for discovery. The url parameter is adequately covered by the schema.

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

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

States a specific verb and resource: 'Start a new InstantClips product from a product page URL.' It clearly differentiates this import-from-URL tool from sibling creation paths, especially create_product_from_images, by the input source and the background-import behavior.

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

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

Gives explicit when-to-use guidance, including when to pass brand_id ('only when the user has told you which brand'), when not to assume a brand, and how to resolve a brand decision using create_brand or set_product_brand. Also tells the agent to poll get_product and clarifies that generate_video is the only credit-spending 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful context beyond annotations, including that the tool does not spend credits and what information it returns. No contradiction with annotations.

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

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

The description is front-loaded with the core listing behavior, followed by usage guidance and a credit note. The brand-identity explanation adds context but is slightly longer than strictly necessary for calling the tool; still, each sentence provides useful background.

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, read-only list tool with rich annotations, the description is complete: it states the resource, the output contents, the exact trigger conditions, and the side-effect profile. Nothing essential is missing.

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

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

The tool has zero parameters, so the baseline is 4. The description correctly adds no parameter information, and the account scope is implied by the title and description. No parameter ambiguity exists.

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 ('List the brands on this account') and specifies the returned data (plan brand limit and whether another brand can be created). The meaning is unambiguous and distinguishes it from brand-creation or brand-assignment siblings like create_brand and set_product_brand.

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

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

Gives an explicit trigger: call before answering a `brand_decision_required` from `get_product`, and whenever the user needs to choose or name a brand. This tells the agent exactly when to invoke the tool without requiring inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description reinforces this by stating it overwrites current direction and that calling it twice gives different drafts. It adds valuable non-annotation context: background execution, polling via get_product until drafting is false, and that it does not spend credits. This goes beyond the annotation baseline.

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?

Though longer than average, each section earns its place: purpose, destructive warning, background mechanics, and cost. The main action is front-loaded in the first sentence, and the structure is logical with no redundancy or fluff.

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

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

Given the tool's complexity—background execution, destructive behavior, polling requirement—the description covers all necessary operational details: what to expect (drafting flag), how to poll, and user confirmation. The absence of an output schema is compensated by the description's explanation of the return state and polling approach.

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 detailed descriptions for both parameters. The tool description adds no additional parameter semantics—it does not mention product_id or format beyond what the schema already says. Thus 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 tool drafts a fresh creative direction for a product's next video using product facts, images, and brand identity. It distinguishes itself from video generation by focusing on the 'direction' and implies alternation from the current one. It does not explicitly name sibling update_video_direction, but the purpose is unambiguous.

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

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

The description explicitly states when to use it: 'to get a first draft, or to try a different angle when the user does not like the current one.' It also warns about overwriting edits and instructs to confirm with the user before re-rolling. It provides clear context including background execution and polling, though it does not explicitly list alternative 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 indicate the operation is destructive, but the description goes much further by explaining that the default leaves the brand identity untouched, while `replace_identity: true` rewrites a brand identity shared by other products. It also discloses the post-condition that video direction starts drafting afterward and confirms the operation does not spend credits, which is valuable beyond the structured annotations.

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

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

Every paragraph earns its place: the core action, the confirmation requirement, the destructive `replace_identity` caveat, the post-call polling step, and the credit note. The content is front-loaded with the primary verb and resource, and the longer sections provide necessary safety context rather than filler.

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

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

With no output schema, the description still provides a complete picture of prerequisites, side effects, post-call behavior, and how to verify progress by polling `get_product`. It is sufficient for an agent to know when to call, what to pass, what consequences to expect, and how to follow up.

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 a 3, but the description adds meaningful semantics for `replace_identity` by explaining it is the 're-point my brand at a different company' move and by emphasizing that it affects every product on the brand. The descriptions of `product_id` and `brand_id` are otherwise consistent with the schema and do not require much additional explanation.

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 action with a precise subject: attaching a product waiting on `brand_decision_required` to an existing brand. It clearly differentiates from sibling tools like `create_brand` and `update_video_direction` by focusing on the brand assignment step and the required product state.

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 context by telling the agent to use `list_brands` to see existing brands and warns to act only after explicit user confirmation that the product belongs to the brand. It does not explicitly name an alternative for cases where the brand does not exist, such as `create_brand`, so it stops short of full exclusion guidance.

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

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

Annotations already mark this as non-read-only and non-destructive, but the description adds rich behavioral context: partial updates only, no credit spending, the pre-generation precondition, creator_note being passed verbatim, and target_market persisting on the brand. This goes well beyond the structured hints and does not contradict 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 front-loaded with the core action and partial-update semantics, then groups parameter guidance by relevance. It is longer than average, but the tool has seven parameters and subtle constraints; no sentence is filler, and key warnings (don't invent, only before generation, no credits) are clearly highlighted.

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 7-parameter mutation tool with no output schema, the description covers the essential invocation context: what changes, when it is valid, cost behavior, parameter-specific quirks, and the relationship to redraft_video_direction. Nothing critical needed to call it correctly appears missing.

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

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

Schema description coverage is 100%, but the description adds substantial meaning: the six-section creative_direction structure, the instruction not to invent a direction and to prefer redraft_video_direction, creator_note's verbatim pass-through semantics, and target_market's lasting brand-level effect. This materially helps an agent fill parameters correctly.

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: 'Edit the creative direction and render settings for a product's next video.' It also distinguishes itself from the closest sibling by calling out redraft_video_direction explicitly, so an agent can identify the right tool without ambiguity.

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

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

Provides explicit routing guidance: use redraft_video_direction when no direction has been drafted yet, and states the timing constraint 'Only works before generation starts.' It also explains what is deliberately not done here ('does not spend credits'), which helps the agent choose between this and generation tools.

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