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

With no annotations provided, the description carries the full burden of behavioral disclosure. It communicates the core metrics and scope, but leaves important behavior implicit: what list_id means, whether from/to are required or defaulted, how the 'all' shop value interacts with list_id, and what the response looks like. This is too sparse for a tool with no output schema and no annotation safety 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 a single, efficient sentence with no filler and the most identifying details front-loaded. It is appropriately concise, though slightly terse and missing some behavioral 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?

Given four parameters, no required fields, no output schema, and no annotations, a 16-word description is not enough. It leaves list_id semantics, default date-range behavior, the handling of 'all', and return format unaddressed, making it incomplete for an agent to call the tool confidently.

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 only 50%, so the description needs to compensate. It adds useful meaning by interpreting to/from as 'date range' and shop_id as 'one shop or all'. However, list_id is not explained at all, and no additional format or constraint detail is given beyond what the schema already 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 clearly enumerates the metrics returned (shop visits, product clicks, saves, list clicks) and the scope (date range, one shop or all). This is specific enough to distinguish the tool from analytics_top_products and earnings_summary, though it lacks an explicit verb like 'retrieves' or 'returns'.

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 'over a date range (one shop or all)' gives some context for when the tool is appropriate, and the metric list implies a focus on engagement analytics. However, it does not explicitly state when to prefer this tool over siblings such as analytics_top_products, nor does it mention exclusions or 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?

With no annotations, the description must carry the behavioral burden, but it only states the basic output and scope. It does not disclose whether the operation is read-only, how the date range works, whether results are paginated, or how 'most clicked/saved' is ranked.

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 short and front-loaded, with no wasted words. However, it is a noun phrase rather than a complete instruction, and its brevity comes at the cost of missing important usage 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?

For a tool with three undocumented parameters, no output schema, and no annotations, this description is incomplete. An agent would not know how to format the date parameters, whether they are required, what 'all' means for shop_id, or what the response looks like.

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

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

Schema description coverage is 0%, and the description adds almost no parameter meaning. It does not explain that 'to' and 'from' are likely date bounds, nor the semantics of 'shop_id' including the special 'all' 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 identifies the result: the most clicked/saved products of a shop. It lacks an explicit verb such as 'returns' or 'lists', but the meaning is unambiguous and distinct from sibling tools like analytics_kpis.

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 about when to use this tool versus alternatives. The phrase 'of a shop' gives minor context, but there is no mention of similar analytics tools, filters, or when another tool would be more appropriate.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It states that no credentials are needed and the content is purely informational ('How the wishlist basket works and how to integrate it well'), implying a read-only, non-mutating operation. It could more explicitly say 'does not modify anything,' but the guide framing is sufficient.

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 one dense, front-loaded sentence that packs a lot of useful information: scope, topics, prerequisites, and usage pointer. Every part earns its place without filler or repetition of 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 simple documentation tool with one optional enum parameter and no output schema, the description covers what the guide contains, that no credentials are needed, and when to read it. It does not explicitly state the return format, but for a guide tool 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 0%, so the description must compensate. It lists the exact content areas (config, embedding, checkout, events) that map to the enum values, giving meaning beyond the bare enum names. It does not explain the 'all' default or describe output format, but the single parameter is simple and self-explanatory with this context.

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 identifies the tool as a conceptual guide to the wishlist basket, covering config, embedding, checkout, and events. It specifies the resource (wishlist basket) and the purpose (understand and integrate it well), which distinguishes it from siblings like snippet_basket or docs_search.

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

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

The description gives explicit usage context: 'Read before baskets_create' and 'No credentials needed.' It tells the agent when to consult the guide, though it does not explicitly compare against alternative sibling tools or state 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It tells the agent what is searched and that results have affiliate links, but it does not disclose return format, pagination behavior, whether the search is read-only, or what happens when no matches are found.

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

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

The description is a single efficient sentence that front-loads the core purpose and adds concrete scope. Every word earns its place, and there is no repetition of the title or schema fields.

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 nine parameters, no output schema, and no annotations, this description is too sparse for reliable invocation. It provides enough for tool selection but omits required-parameter context, filter semantics, and expected results, leaving an agent to guess at correct usage.

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

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

Schema description coverage is 0% and the description mentions none of the nine parameters. Even though names like q, brand, limit, and price_max are somewhat self-explanatory, the description adds no meaning about required shop_id, how filters interact, or what offset/limit control.

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

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

The description names a specific verb ('Search'), a specific resource ('affiliate product catalog'), and clarifies the scope by listing sources: Awin feeds, Amazon, and existing products. It also states the purpose ('find products with ready affiliate links'), which distinguishes this search tool from sibling tools focused on creation, updates, or analytics.

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 this tool is for finding existing affiliate-linked products before adding or managing them, which gives some usage context. However, it does not explicitly state when this tool should be preferred over alternatives like products_add_existing or products_preview_url, nor does it mention any 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?

With no annotations, the description carries the burden of behavioral disclosure and it does disclose key behavior: it searches public docs, returns sections with links, and requires no credentials. It does not mention ordering, pagination, or rate limits, but for a read-only docs search the most important traits are covered.

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

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

Two short sentences front-load the action and resource, add the scope and result type, and close with the auth note. Every sentence earns its place with zero 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, read-only, two-parameter search tool, the description covers the source, the result shape, and authentication requirements. The schema supplies the remaining constraint details, so an agent has enough to invoke it 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 0% and the description adds no explicit parameter meanings. The query parameter's role is inferable from the tool purpose, and limit has schema defaults and constraints, but the description does not explain how limit affects results or how the query is matched.

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 and object: 'Search the public developer docs' and clarifies the exact sources ('llms.txt index + endpoint summary'). It also states what is returned ('matching sections with links'), clearly distinguishing it from sibling tools like catalog_search that search other data.

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 establishes clear context for use: it is for searching public developer docs and explicitly notes that no credentials are needed, which helps an agent choose it for unauthenticated documentation lookup. It does not name alternative tools or explicit when-not-to-use conditions, so it misses the top bar.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions the 70/30 rev-share calculation, which adds domain context, but it does not state whether the operation is read-only, what time range is covered, how results are aggregated, or what the response contains beyond the metric names.

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 filler. It front-loads the most important output concepts and includes the useful rev-share detail without wasting 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?

There is no output schema and no annotations, so the description should explain return shape and behavior, but it does not. It also fails to clarify the optional 'months' parameter, leaving an agent with incomplete information for making a correct call.

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

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

Schema description coverage is 0%, and the description does not explain the 'months' parameter or the accepted formats for 'shop_id'. It only says 'of a shop', which adds little beyond the schema's required shop_id field.

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 identifies the resource (a shop's affiliate performance) and the specific metrics included (earnings, clicks, conversions, payouts), so an agent can tell what the tool reports. It does not use an explicit verb like 'retrieve' or 'list', and it does not name or differentiate from sibling analytics tools, but the intent is still 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 provided about when to use this tool versus alternatives such as analytics_kpis, analytics_top_products, or shops_get. The description gives domain context but no when-to-use rules, exclusions, or prerequisite 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?

No annotations are provided, so the description must carry the full behavioral burden. It states the core effect (a new list is created) but does not disclose response shape, default values for optional flags like is_public or is_featured, or any 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 front-loaded sentence with no fluff, and the parenthetical example adds practical meaning. It is compact and readable, though the brevity also explains why several behavioral and parameter details are missing.

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 seven-parameter create operation with no output schema and no annotations, the description is too thin. It does not explain optional parameters, what a successful response looks like, or any constraints beyond what the schema's required fields imply.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the shop context and gives a concrete name example ('Herbst-Favoriten'), which helps with shop_id and name. However, it leaves is_public, cover_image, description, is_featured, and market_code entirely unexplained.

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') and resource ('product list in a shop'), with a useful example name. It clearly distinguishes this from list read/update/delete tools and from shop-create siblings.

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

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

There is no guidance on when to use this tool versus alternatives like lists_update, lists_delete, or product-add tools. The action itself implies creation, but no explicit context, preconditions, or 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?

With no annotations, the description carries the full burden of behavioral disclosure. It usefully reveals one key side effect: products remain in the catalog after list deletion. However, it does not mention irreversibility, permissions, error behavior, or what happens to the list's contents beyond products.

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, tightly scoped sentence. The primary action 'Delete a list' is front-loaded, and the parenthetical adds exactly one useful clarification without 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 two-parameter delete operation, the description covers the essential effect and the most important side effect. However, there is no output schema and no annotation, so details such as return value, failure modes, and reversibility are left unstated. It is adequate but has clear gaps.

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

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

Schema description coverage is 0%, and the description does not explain shop_id or list_id. The parameter names are fairly self-explanatory, and the schema provides types and required status, but the tool description adds no parameter-level meaning. It therefore does not compensate for the missing schema descriptions.

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

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

The description clearly states the operation: delete a list. It also adds an important scoping detail—products stay in the shop catalog—which helps distinguish this from deleting products or catalogs. It does not explicitly name a sibling alternative, but the verb+resource is specific enough.

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 no guidance on when to use this tool versus alternatives like lists_update or products_remove_item. There is no mention of prerequisites, conditions, or excluded cases. Usage is only implied by the title and description, not explicitly stated.

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?

No annotations are provided, so the description carries the full burden of explaining behavior. It only hints at the return contents and does not mention read-only nature, errors, authorization needs, or any other runtime behavior beyond the implicit 'get' in the name.

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 short and free of filler, but it is more under-specified than concisely complete. It front-loads the main object, yet the lack of a verb and parameter context means brevity comes at the cost of usefulness.

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

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

For a simple two-parameter GET tool the description is minimally recognizable, but with no output schema, no annotations, and no parameter explanations, it leaves too much for the agent to infer. The agent can guess that list_id identifies the list and shop_id scopes it, but the description does not confirm this.

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

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

Schema description coverage is 0%, and the description does not explain shop_id or list_id at all. The only field-level detail in the description refers to output product fields, not to the two required input parameters, so it adds no parameter meaning beyond their bare names.

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

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

The description identifies the resource as 'a list with its products' and gives useful detail about the returned product fields, but it never states an action such as 'gets' or 'retrieves'. The title and tool name make the operation inferable, yet the description itself reads more like a result shape than a purpose statement.

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

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

There is no guidance about when to use this tool versus alternatives like lists_list or lists_update. The sibling names imply a distinction, but the description provides no explicit context, use cases, 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?

With no annotations, the description carries the behavioral disclosure burden. It usefully reveals the compact-row output format and that full=true returns raw records, but it does not mention pagination, ordering, errors, or explicitly confirm read-only behavior.

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 names the resource, output shape, and the important full flag. There is no filler or redundant restatement 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?

This tool has no annotations and no output schema, yet the description omits pagination behavior, filter semantics, and when to choose it over siblings. The field list and full flag help, but the description is not complete enough for confident 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 only 20%, and the description adds meaning primarily for the full parameter. The schema already documents q, while shop_id, limit, and offset receive no additional explanation, so the description does not compensate for the low 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 (list), the resource (shop lists/collections), and the output format (compact rows with named fields). It is distinct enough, though it does not explicitly contrast with the sibling lists_get.

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 like lists_get or lists_create. There is no mention of context, exclusions, or preferred scenarios, so the agent must infer usage entirely.

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?

No annotations exist, so the description carries the disclosure burden. It does reveal the destructive pruning consequence of passing the full product array, but it does not state whether omitted fields are left untouched or reset, or what the response/return behavior is. This is partial but meaningful transparency.

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 front-loads the update capabilities and contains no filler. Every clause adds meaning, and the most destructive behavior (pruning) is placed at the end with the exact payload mechanism.

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 8-parameter mutation with no annotations and no output schema, the description covers the key behaviors but omits patch-vs-replace semantics, cover_image handling, and return value expectations. It is adequate but leaves an agent guessing about edge cases.

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

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

With only 13% schema coverage, the description compensates by mapping name/description to rename/describe, is_public/is_featured to toggles, and products to ordered-array reorder/prune semantics. It leaves cover_image unmentioned, and the required identifiers are left to schema naming, but the main mutating parameters are given useful meaning.

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 and enumerates concrete operations: renaming/describing a list, toggling public/featured, and reorder/prune products via a full ordered array. This clearly distinguishes lists_update from sibling list read/create/delete 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 makes it obvious this is the tool for modifying an existing list, but it never explicitly states when to choose it over lists_create/lists_delete or when not to use it. Usage guidance is implied by the name and sibling context rather than stated.

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?

With no annotations, the description carries the full transparency burden. It does disclose an important behavioral trait: deleting the video also removes its files, which goes beyond a plain 'delete media' statement. However, it does not state that deletion is permanent/irreversible or mention any permission 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?

The description is a single sentence with no filler, and it front-loads the action and target. The additional clause 'and its files' adds meaningful scope without bloat.

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

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

For a one-parameter delete tool with no annotations or output schema, the description is minimally adequate but leaves gaps: no explicit statement that deletion is permanent, no clarification of what id refers to, and no usage conditions. It is complete enough to guess the core operation but not fully self-sufficient.

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

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

Schema description coverage is 0%, so the description needed to explain the id parameter, but it does not mention id at all. The schema only establishes that id exists and accepts an integer or numeric string; the description adds no clarification about whether this is the media ID or product ID.

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 ('Delete') and clearly identifies the resource: a product video and its associated files. This distinguishes it from sibling tools like media_update or media_upload_video, which have different actions.

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 about when to use this tool versus alternatives such as media_update or media_list, and no prerequisites or conditions are stated. The only contextual signal is the word 'Delete', which is not enough to constitute explicit usage direction.

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?

There are no annotations, so the description carries the behavioral burden. It discloses the main scope, optional filters, and that the plan limit is included in the result. Still, it does not clarify whether the operation is read-only, how results are ordered or paginated, or what 'plan limit' means in the response.

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 tightly written sentence conveys scope, optional filtering, and return content without repetition or unnecessary detail. The information is efficiently front-loaded and every phrase 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 two-parameter list tool, the description covers the core purpose and optional parameters. But with no output schema and no annotations, it leaves some important context implicit, such as the structure of the returned video list, the exact meaning of 'plan limit', and whether the filters are mutually exclusive or combinable.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaning by explaining that product and shop are optional filters, which maps to product_id and shop_id. However, it does not elaborate on value formats, whether the filters can be combined, or the exact behavior when no filters are supplied.

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

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

The title supplies the verb 'List' and the description names the resource ('product videos') plus the scope ('of the partner') and optional filters (product/shop). It is clear enough to distinguish from media_upload_video, media_update, and media_delete, though the description itself is phrased as a noun fragment rather than a full imperative.

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 retrieve product videos, with optional filtering by product or shop. However, it gives no explicit guidance about alternatives, exclusions, or when not to use it, leaving the agent to infer the 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?

With no annotations, the description carries the transparency burden. It usefully explains that status hidden|ready corresponds to hide/show and that product_ids replaces only additional links while the primary product_id stays. However, it does not clarify whether omitted fields are left unchanged or cleared, whether changes are reversible, or any permission 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?

One dense sentence gets the action and scope across immediately; the parenthetical about status values and the primary product_id caveat add real value without bloat.

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 definition is enough to make a basic update call, but with no output schema and no annotations it leaves ambiguity about partial-update behavior (are unspecified fields cleared?) and about the expected language/position value formats. The 'or' phrasing also slightly obscures that multiple updates can likely be combined.

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 low (14%), but the description compensates by mapping status to hide/show, naming the editable metadata fields, and explaining product_ids replacement semantics. It leaves id, language, and position semantics mostly to their names, so not a 5.

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

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

The description names a specific update operation with the exact mutable fields (title, caption, language, position, status, product_ids) and a non-obvious rule (primary product_id is kept). This makes it clearly different from the upload/list/delete sibling tools.

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

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

The wording 'Change...' implies this is for modifying an existing video's metadata, visibility, or product links, but it does not explicitly say when to prefer it over media_upload_video or media_delete, nor does it state any 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal important behaviors: the upload results in 'status ready' (published), there is a quota ('Creator Free: 5 ready videos per shop'), and the video is linked to products. However, it does not disclose whether the operation is asynchronous, if it is reversible, or any side effects or error handling. It also omits details about required permissions or prerequisites. The transparency is partial, leaving critical behavior unstated.

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 concise, composed of three sentences, each adding substantive value. It front-loads the core action and constraints, then explains the product linking and quota. There is no redundant fluff or repetition of schema content. The structure is efficient, though it could be slightly more organized (e.g., separating quick specs from usage context), but it remains well within acceptable conciseness.

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 complex tool with 11 parameters (2 required), no output schema, and no annotations. The description covers only a subset of the tool's functionality and context. It omits details on optional parameters like title, language, and duration_s, and does not mention prerequisites such as the need for an existing shop or product, or how errors are handled. It also does not explain the upload's effect on existing media or the response format. The description leaves significant gaps for an agent to use the tool correctly in a real scenario.

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 only 36%, so the description must compensate. It does add semantic value for product_id and product_ids by explaining their relationship and display context ('show next to the video in the shop's video feed') and clarifies source format (MP4/MOV, max 200MB). However, it provides no information for the eight undocumented parameters (title, width, height, caption, shop_id, language, duration_s). Given the low coverage, the description fails to adequately explain the meaning of most parameters, leaving agents without guidance.

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 action: 'Upload an MP4/MOV (max 200 MB) for a product from a local path or URL, optionally with a poster image, and publish it (status ready).' It specifies the resource (product video), format, size limit, and result (status ready). It also explains the distinct roles of product_id and product_ids, which differentiates from siblings like media_update or media_list. The purpose is unambiguous and well-defined.

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 explicitly state when to use this tool versus alternatives like media_update or media_delete. It provides contextual details (e.g., video always belongs to at least one product, creator free limit) but no direct usage scenario or exclusions. The presence of an upload-specific tool among siblings implicitly implies usage for new video uploads, but the description does not articulate that clearly enough for an agent to confidently select it over a generic media 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?

With no annotations, the description carries the transparency burden. It usefully discloses that the page is scraped, that affiliate_url is the visitor-clicked link, and that it may equal source_url. It does not mention duplicate handling, failure modes, permissions, or what happens if scraping fails.

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 tight sentences: the first states the core action and scraping behavior, the second covers affiliate_url and optional overrides. There is no filler and the key information 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 13-parameter creation tool with no output schema and no annotations, this description covers the main path but omits return behavior, error/duplicate handling, and the meaning of several optional fields. It is sufficient for tool selection but not for handling edge cases or unexpected outcomes.

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 low at 23%, so the description must compensate. It adds meaning for source_url, affiliate_url, and the title/image/description/price overrides, but it leaves shop_id, list_id, tags, categories, adult_only, and market_code without explanation. Some parameter semantics still rely on inference from the schema and sibling context.

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 'Add a product to a list from its shop URL' — a clear verb, resource, and source. Mentioning that the page is scraped for title/image/price sets it apart from manual or existing-product add flows, though it does not explicitly name those sibling tools.

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

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

The use case is implied: use this when you have a shop URL and want the product scraped and added to a list. However, there is no explicit guidance about when not to use it or when to prefer products_add_manual or products_add_existing instead.

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?

No annotations are provided, so the description carries the full burden of explaining behavior. It states the core side effect—placing an existing product into a list—but does not disclose permissions, idempotency, duplicate handling, return values, or what happens when required references are invalid. For a mutation tool with no annotation support, this is a notable gap.

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 well-structured sentence that front-loads the main action and adds the key optional capability in a compact way. There is no wasted wording or redundant restating of the title.

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

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

Given 9 parameters, no output schema, and no annotations, the description is not complete enough. It provides a general sense of the operation but does not cover optional parameter behavior, expected response, failure conditions, or selection guidance relative to similar sibling tools, leaving an agent to guess at important invocation details.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions product id, affiliate link, and 'overrides', but several parameters such as market_code, manual_price_minor, and manual_price_currency are not addressed at all. The description gives high-level hints but leaves much of the parameter meaning to an unhelpful 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 a specific action ('Place a product') and resource ('into a list'), and clarifies that the product must already exist and be identified by product id, e.g. from catalog_search. This distinguishes it from sibling tools like products_add_by_url and products_add_manual, which add products in different ways.

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 establishes the key usage context: use this tool when the product already exists and you have its product id, rather than when adding by URL or manually. It does not explicitly name the alternatives or state when not to use it, but the 'already exists' constraint makes the intended use 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?

With no annotations provided, the description carries the burden of explaining effects. It states that the product is added to the shop catalog and clarifies that list placement is out of scope, but it does not disclose return values, validation behavior, error cases, or required permissions for a write operation.

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: the first states the primary action and mode, the second routes list placement to alternatives. No redundant filler, and the core use case 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?

The description adequately establishes the tool's scope and its relationship to list operations, but it is incomplete for a 12-parameter mutation with no output schema and no annotations: it leaves return behavior, parameter-specific guidance, and error conditions unexplained. The schema supplies the remaining structure.

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

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

Schema description coverage is 0%, so the description should compensate for the 12 parameters, but it only provides the umbrella phrase 'your own data (no scraping).' Property names and types in the schema cover some meaning, but the description adds no specifics about fields like market_code, original_price, currency constraints, or how affiliate_url is used.

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 action and target: 'Add a product with your own data (no scraping) to the shop catalog.' This clearly states what the tool does and distinguishes it from URL-based scraping siblings like products_add_by_url and from products_add_existing, which handles list placement.

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 frames the use case as supplying your own data and warns off scraping, giving clear context for when products_add_manual is appropriate. It also names lists_update(products) and products_add_existing as the right routes for placing the product in a list, though it does not spell out when products_add_by_url should be used instead.

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?

With no annotations, the description must carry behavioral disclosure. It reveals the operation is non-destructive ('without adding it') and states the return value (productId). However, it does not disclose failure modes, URL eligibility, or any side effects of scraping, which limits transparency for an external-fetching tool.

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

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

The description is two tight sentences with no redundant wording. The core action and scope are front-loaded, and the second sentence adds a valuable integration detail, making every word earn 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?

The description adequately covers the core behavior and return value, but it lacks details about the optional market_code parameter and the exact return structure beyond productId. With no output schema and no annotations, an agent may be uncertain about handling the productId or interpreting the scraped fields.

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

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

Schema description coverage is 0%, so the description must compensate for parameter explanations. It only implicitly covers 'url' by referring to 'a product page', and it completely ignores the optional 'market_code' parameter, leaving the agent without guidance on its purpose or valid values.

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 ('Scrape') with a clear resource ('product page'), enumerates the extracted fields (title, image, price, brand), and explicitly notes it does not add the product. It also references the sibling products_add_by_url, making the tool's purpose and distinction immediately 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 implies a preview-before-add workflow by stating 'without adding it' and mentioning that the returned productId is reusable in products_add_by_url. This gives context for when to use the tool, though it does not explicitly list exclusions or alternative comparison criteria.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavior. It states the core mutation ('Remove a product from a list') but says nothing about whether the operation is reversible, whether the product itself is deleted, what permissions are required, or what the response indicates about success or failure.

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 with no filler or redundant wording. It is appropriately concise for a simple removal operation, though the brevity contributes to under-specification that is penalized in other dimensions.

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 destructive tool with three required parameters, no annotations, and no output schema, the description is too thin. It omits return behavior, error conditions, idempotency, and the semantic relationship between shop_id, list_id, and item_id, leaving an agent without enough context to invoke the tool correctly in unfamiliar situations.

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

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

Schema description coverage is 0% and the schema provides no per-property descriptions. The description marginally relates 'product' to the item and 'list' to the list, but it does not clarify whether item_id refers to a product ID or a line item ID, nor does it explain the role of shop_id or the relationships among the three required parameters.

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 ('Remove') and identifies the resource ('a product') and its container ('a list'), which distinguishes it from sibling add/update product tools. However, it does not explicitly differentiate itself from products_update_item or clarify whether the product record itself is deleted versus only its membership in the list.

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

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

The intended use case is implied: use this when removing a product from a list. However, the description provides no explicit guidance about when not to use it, no alternative tools are named, and no prerequisites such as list ownership or item existence 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?

With no annotations, the description carries the full burden of behavioral disclosure, but it only says the operation changes data. It does not clarify whether updates are partial or full replacements, whether null values clear overrides, what side effects occur, or what the response contains.

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 efficient sentence with no filler, and the item_id source hint adds practical value. It is concise, though it sacrifices parameter-level detail that would be necessary for a tool with this many inputs.

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 13-parameter mutation with no annotations, no output schema, and 0% schema description coverage, this description is far too thin. It omits the roles of shop_id and list_id, the meaning of most optional fields, update semantics, and any return or error behavior.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at affiliate_url and override-related fields and explains item_id. The other ten parameters, including available, manual_price_minor, manual_price_currency, and list_item_* fields, are left entirely unexplained.

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 ('Change') and resource ('affiliate link or overrides of a product in a list'), which makes the basic purpose clear. It doesn't explicitly differentiate from sibling tools, but the update-versus-add/remove distinction is inferable from the tool name and sibling list.

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

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

It provides a useful usage hint by mapping item_id to listItemId from lists_get, indicating this tool operates on an already-known list item. However, it does not explain when to prefer this over products_add_by_url, products_add_manual, or products_remove_item, nor does it mention any prerequisites for list ownership or permissions.

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 absent, so the description carries the full behavioral burden. It indicates a non-mutating availability check and that a slugified suggestion is returned, but it does not specify the response shape, whether the suggestion is always returned, or any auth/validation behavior.

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

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

Two short sentences with no filler. The primary action is front-loaded, an example is included, and the return behavior is stated concisely; 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 low-complexity tool with one required parameter and no output schema, the description is enough to make a basic call with a handle. But the exact availability result format and the purpose of exclude_shop_id remain underspecified, so an agent may need to infer response semantics.

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

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

Schema description coverage is 0%, and the description adds useful meaning for the required handle parameter by defining it as a URL slug with an example. However, it does not explain the optional exclude_shop_id parameter, so parameter coverage is incomplete.

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 (check whether) and a specific resource (shop handle/URL slug) with a concrete example. This clearly distinguishes it from siblings like shops_get, shops_create, or shops_update, none of which are availability checks.

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 states what the tool does but gives no explicit when-to-use guidance, exclusions, or alternatives. An agent must infer that this is meant for pre-checking a handle before creating or updating a shop, and no sibling is named for comparison.

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?

There are no annotations, so the description carries the behavioral disclosure burden. It clearly states the shop is created as a draft, that the handle becomes the public URL, and that publishing is deferred to shops_publish. It does not describe failure modes or response shape, but the key side-effect semantics are disclosed.

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 with no filler. The core action and the most important downstream step 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 create tool with six parameters, nested settings, and no output schema, the description is useful but minimal. It covers the draft lifecycle and URL behavior but does not mention what the create response contains, how to identify the newly created shop later, or what happens on conflicts. This is acceptable but not 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 about 50%, so the description should add some parameter meaning. It usefully clarifies that handle maps to the public URL https://shareawish.shop/<handle>, which goes beyond the schema's 'URL slug' note. However, it does not add meaning for undocumented parameters like name, settings, or description, leaving the schema to carry most of that burden.

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 and resource: 'Create a creator shop (draft)'. It also distinguishes this tool from the publish step by explicitly naming shops_publish, so an agent can tell creation and publication apart.

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 lifecycle context: this creates a draft, and publication is a separate later step via shops_publish. It does not explicitly list exclusions or when to prefer shops_update, but the draft/publish split is enough for basic 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?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the response scope by listing the record fields, which is useful for a read tool. However, it does not mention error behavior, authentication requirements, or explicitly confirm that no side effects occur; the 'get' naming implies read-only behavior.

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 one compact, front-loaded sentence that leads with 'Full shop record' and then lists the relevant fields. It has no filler and every part adds informational 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 one-parameter get-by-id tool with no output schema, the field list gives a reasonable high-level view of the return value. It would be more complete with explicit error/not-found behavior or a contrast with shops_list, but the low complexity makes the current description adequate for 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 schema already documents the single shop_id parameter at 100% coverage, including a helpful pointer to shops_list for finding the numeric id. The description adds no additional parameter meaning, so the schema is carrying the load and 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 identifies the tool as retrieving a full shop record and enumerates the major fields: name, handle, description, template, settings, images, markets, publish state. This is more specific than the title alone and conveys the granularity of the response, although it does not explicitly distinguish from shops_list.

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

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

There is no guidance on when to use this tool versus siblings such as shops_list, shops_check_handle, or shops_update. The only pointer to shops_list appears in the schema's parameter description, not in the tool description, and no conditions or exclusions are given.

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?

There are no annotations, so the description carries the disclosure burden. It does this well by describing the compact row shape, the q/limit/offset behavior, and warning that full=true returns large raw records. It does not discuss ordering or authorization, but for a list operation the key behavioral choices are covered.

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 dense sentences with no wasted words. The output shape is front-loaded, followed by filtering, pagination, and the full-payload warning, making it easy for an agent to parse quickly.

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 and no annotations, the description covers the essential context: what rows look like, how to filter and page, and when responses can get large. It leaves public_only and sort order unmentioned, but overall an agent has enough to call 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 only 20%, so the description must compensate. It adds real meaning to full=true (raw records, large payload), explains pagination via limit/offset, and reinforces the q filter. The only gap is public_only, which is neither described in the schema nor the description, though its name is fairly self-explanatory.

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 action and object ('Creator shops ... as compact rows') and enumerates the returned fields, so an agent knows exactly what the tool produces. The plural 'shops' list semantics clearly distinguish it from shops_get.

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 conveys that this tool is for listing shops and explains filtering and pagination. However, it never names alternatives or states when not to use it, leaving the agent to infer the choice between this and shops_get.

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?

With no annotations provided, the description carries the full burden of revealing behavior. It discloses the visible effect: making a shop public or returning it to draft. However, it does not mention prerequisites, side effects, auth requirements, or what happens to an already-live shop, so the disclosure is only partially complete.

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 with no filler. It states the action and both possible target states efficiently, making it easy for an agent to parse quickly.

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 low-complexity tool with two required parameters and no output schema, the description is mostly sufficient. Still, it lacks any guidance on when to prefer this over shops_update and gives no behavioral edge cases, leaving minor but real context gaps for an agent invoking a mutation.

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

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

Schema description coverage is 0%, so the description needs to compensate for parameter meaning. It does clarify the 'status' parameter by mapping 'live' to public and 'draft' to unpublished, but it says nothing about 'shop_id' beyond what its name implies. This partial compensation earns a mid-range score.

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 identifies the operation as setting a shop's publication state to either 'live' or 'draft', with a specific verb and resource. It does not explicitly distinguish itself from siblings like shops_update, but the status-toggle scope is clear enough to avoid major confusion.

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 'Set the shop live (public) or back to draft' provides clear context for when to use this tool: when an agent needs to publish or unpublish a shop. It does not explicitly mention alternatives or exclusions, but the intended use case is unambiguous.

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

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

The description adds one meaningful behavioral detail: settings are merged with existing settings rather than replaced wholesale. However, with no annotations, it does not disclose other important behavior such as whether unspecified fields are left untouched, whether the update is reversible, what permissions are needed, or what the response contains.

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 short and front-loaded, with the key action and fields in the first sentence and the merge behavior in the second. It earns its place, though the ambiguity of 'markets' and omission of domain slightly weaken precision.

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

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

For a mutation tool with 8 parameters, nested settings, no output schema, and no annotations, the description is too thin. It doesn't explain return value, partial-update semantics beyond settings, constraints like Creator Pro domains, or required identification via shop_id.

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 only 13%, so the description needed to compensate by explaining parameters. It lists several fields (name, description, template, handle, markets, settings) but omits domain entirely and uses 'markets' where the schema has 'allowed_markets', which could mislead. The merge semantics for settings add value, but the parameter guidance is incomplete.

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 operation (update) and the target resource (shop), and lists the fields that can be changed. It distinguishes from sibling list/get/create/publish tools by virtue of the update verb, though it doesn't explicitly call out any 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?

There is no guidance about when to use this tool versus shops_create, shops_publish, or shops_check_handle, and no mention of prerequisites or constraints such as requiring an existing shop_id. The context is somewhat obvious from the name, but the description doesn't help the agent decide between 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?

With no annotations provided, the description carries the behavioral burden. It discloses the accepted source types, size limit, formats, and attach behavior. However, it does not mention whether an existing image is overwritten, what the response looks like, or any auth/permission 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?

The description is a single, well-structured sentence that front-loads the core action and resource, then appends the key constraints. Every part contributes useful information 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?

For a mutation tool with no annotations and no output schema, the description gives enough to attempt a call: three required parameters are all plausibly derivable, and the source/type constraints are explicit. It is incomplete on response formats, error conditions, and overwrite behavior, which an agent would need for robust handling.

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 low at 33%, and the description adds meaningful constraints for 'source' (local file path or http(s) URL, max 10 MB, jpg/png/webp) and clarifies 'type' via logo/cover. The 'shop_id' parameter is not explained, though its purpose is fairly inferable from the tool name and title.

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 ('Upload'), identifies the resource ('logo or cover image'), and states the destination ('attach it to the shop'). It clearly distinguishes this from sibling tools like media_upload_video and products_add_by_url.

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 makes the use case clear: the agent should call this when it needs to set a shop's logo or cover image from a local file path or URL. It does not explicitly name alternatives or exclusions, but the logo/cover scope and 'attach to the shop' language provide sufficient 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?

With no annotations, the description carries the full behavioral burden. It discloses that the tool returns copy-paste code, includes the add-to-cart bridge (onAddToCart → respond), and specifies two hard requirements (config id and https). It doesn't mention rate limits, auth, or side effects, but as a code generator it is clearly non-mutating and the requirements are the key behavioral constraints. This is transparent for the tool's nature.

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 that front-loads the purpose and then efficiently enumerates modes, frameworks, the bridge, and requirements. Every sentence adds necessary information, and there is no fluff. It could be slightly more scannable with bullet points, but it is appropriately sized for the complexity and keeps the most critical info first.

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

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

For a 4-parameter tool with no annotations and no output schema, the description covers the core mechanics (modes, frameworks, config_id, https, bridge) but leaves public_key unexplained and does not address how the output snippet is delivered or what it looks like. It also fails to mention alternatives, which would help an agent choose correctly. Overall it is functional but has clear gaps that could confuse a first-time caller.

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

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

Schema description coverage is 0%, so the description must compensate. It explains mode with detail ('side panel opened from a header button – recommended', 'section on a page', 'standalone wishlist page'), lists all framework values, and describes config_id as a 'basket config id (bkt_…)' with creation context. However, public_key is not mentioned at all, leaving a gap. It adds substantial meaning to 3 of 4 parameters but misses one, so it's strong but not perfect.

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 ('Copy-paste code for the wishlist basket') and immediately differentiates the tool from siblings like snippet_save_button and basket_guide by focusing on the basket modes and frameworks. It clearly states the deliverable (copy-paste code) and the embedding context, so an agent can tell it apart from related snippet tools 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?

The description provides concrete constraints (needs a config id, page must be https) and the prerequisite of creating the config via baskets_create, which guides usage. However, it never explicitly says when to use this tool over alternatives such as snippet_save_button or basket_guide, nor does it state any exclusions. The 'when' is implied by the tool's name and purpose but not made explicit.

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

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

With no annotations, the description carries the behavioral burden. It discloses the key source and, more importantly, the fallback behavior: without a key a placeholder is used, which tells the agent the tool still works with no public_key. The phrase 'copy-paste code' also signals that the tool returns code rather than performing a live mutation.

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 core purpose is front-loaded in the first sentence, and the second sentence packs the prerequisite and fallback behavior into one clause.

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

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

For a two-parameter snippet tool with no output schema, the description is complete: it covers what the tool returns, the supported frameworks, where the key comes from, and the no-key fallback. Nothing essential for selecting or invoking the tool is missing.

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

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

Schema description coverage is 0%, but the description compensates fully: it lists the valid framework values and explains the public_key's origin and what happens when it is omitted. An agent can map 'html, react, vue, shopify' to the framework enum and 'keys' to public_key without opening 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 opens with a specific verb and object: it provides copy-paste code for a save-to-wishlist button, and it narrows the resource to the four supported frameworks. This clearly differentiates it from sibling snippet tools like snippet_basket, which would be for a different button 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 intended context is clear: use when the user needs a save-to-wishlist button snippet in html, react, vue, or shopify. It does not explicitly name sibling alternatives or state when not to use it, but the framework list and button purpose provide unambiguous 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?

With no annotations, the description carries the full burden of behavioral disclosure. It states that it verifies credentials and shows the partner details and shop count, which implies a read-only, non-destructive operation. It also gives a clear ordering instruction ('Call this first'). It could benefit from explicitly stating that it makes no changes and that it may fail if credentials are invalid, but the current description covers the essential behavior.

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 immediately states the action and resource, then details the outputs, and ends with a clear usage instruction. There is no filler or repetition, and every clause 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 tool with no output schema, the description fully specifies what the agent will receive (email, name, plan, shop count). It also provides the crucial context that this should be called first. Nothing essential is missing—an agent can invoke it correctly based solely on this description.

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 schema coverage is effectively complete. There is no need for the description to explain parameters. Per the baseline for zero-parameter tools, a score of 4 is appropriate since the description does not need to add anything 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 verb 'verify' and the resource: the signed-in partner, and explicitly lists what is returned (email, name, plan, number of shops). This distinguishes it from sibling tools like shops_get or earnings_summary, which focus on specific data domains rather than identity.

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 explicit instruction to 'Call this first,' which conveys when to use the tool. It does not explicitly mention alternatives or exclusions, but for an identity/credentials check there are no direct alternatives among the siblings, so the guidance is sufficiently clear. A mention that other tools depend on successful authentication would strengthen it.

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