ApparelHub

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

Annotations only supply openWorldHint=true, so the description carries the behavioral load and does it well: it discloses the identity-match requirement, tier compatibility, and key-scoping behavior. It even reports the return payload (account + workspace), which is useful given no output schema.

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

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

Three compact sentences, front-loaded with the action and precondition, with no redundant restatement of the name. The trailing '[#e7e5ee]' artifact is stray noise but does not obscure meaning.

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

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

For a single-parameter tool with no output schema, the description covers auth requirement, scope/tier, and the return shape, which is enough for an agent to call it correctly. Only the absence of explicit sibling routing keeps it from a 5.

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

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

Only one parameter and schema description coverage is 100%, so the schema already explains the token fully (from the invite email / accept URL). The description's 'by token' adds nothing beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb (accept) and resource (pending invite) plus the mechanism (by token). It is clearly separable from siblings like invite_member, resend_invite, and revoke_invite, which operate on the inviter side.

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

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

Gives real preconditions: the authenticated key-holder's email must match the invite, and it works on any tier and with a workspace-scoped key, identifying this as the invitee-side action. It never explicitly names the counterpart tools (invite_member / revoke_invite) or states when not to use it, so it stops short of a 5.

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

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

Annotations supply openWorldHint and idempotentHint (retry safety), and the description adds genuinely new behavioral context: the hard prerequisite of a connected fulfillment provider and the failure it causes if unmet. It stops short of covering auth/permission requirements or what the response returns.

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, front-loaded with the purpose and then the prerequisite and sequencing. The stray '[#87c31f]' artifact is noise that slightly detracts from an otherwise efficient description.

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 state-mutation tool with no output schema and annotations covering the safety profile, the description covers purpose, prerequisite, failure mode, and sequencing adequately. It could say more about permissions or reversibility, but nothing critical to a correct call is missing.

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

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

Schema description coverage is 100%, so both store_uuid and workspace are already documented in the schema. The description adds no parameter-level syntax or format detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb (activate) and resource (store), plus the concrete consequence: it can 'list products and ingest orders'. This clearly separates it from sibling lifecycle tools like archive_store, unarchive_store, and create_store.

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

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

Explicitly states the prerequisite ('Requires at least one fulfillment provider ... to be connected first') and the sequencing ('Use after create_store or unarchive_store once a provider is connected'). It names the alternatives and the condition that selects them, leaving nothing to inference.

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

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

With only openWorldHint in annotations, the description carries the burden and does so richly: per-provider semantics (Printful/Gelato edit in place, Printify cancels and re-creates), the resulting edit_method="recreated" and new fulfillment_external_id, and the reassurance that nothing is charged on a draft. It also names the exact error code for the non-editable case.

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

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

Front-loaded with the core action and the draft constraint, and the provider-specific risk is placed where an agent will read it before acting. It is dense but nearly every clause carries decision-relevant information; the trailing '[#f416d1]' artifact is stray noise.

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 6-param mutation tool with no output schema, the description covers preconditions, per-provider side effects, price semantics, and error behavior, so an agent has everything needed to call it correctly and interpret the recreated-order case.

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

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

Schema coverage is 100%, so baseline is 3; the description adds real value by disambiguating custom_price (per-unit retail) and shipping_cost (order-level retail the customer pays, NOT provider cost) and by stating the omit-behavior for both. Quantity and workspace are left to the schema.

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

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

States a specific verb+resource (add an item to a DRAFT order) and scopes it precisely against the surrounding order tools, e.g. it is not remove_order_item and not a catalog operation. The draft-only constraint further disambiguates it from order-creation 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?

Clearly states when it applies ('Only works while the order is in "draft" status' before confirmation to production) and gives the failure condition (409 order_not_editable if already confirmed). It does not explicitly point at sibling alternatives such as remove_order_item or submit_order_to_fulfillment, so it stops short of full routing guidance.

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

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

Annotations only declare openWorldHint=true, so the description carries most of the behavioral burden. It does disclose a genuinely useful side effect (products propagate to a synced channel) and an input precondition, but says nothing about permissions, idempotency, or what happens if a product is already in the collection.

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 two informative sentences are front-loaded and efficient, but the definition is polluted by a stray color-code artifact ('[#e8080a]') that has no semantic value and adds noise.

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 output schema and near-empty annotations, the description covers the precondition and the cross-channel effect but omits failure modes, permission requirements, and confirmation of the result. Adequate but with 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%, so the schema names the parameters but explains none. The description clarifies the uuid semantics of product_uuids and collection_uuid and confirms multi-add via 'one or more', but leaves the workspace parameter and the store_uuid/collection_uuid relationship 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?

States a specific verb and resource ('Add one or more products ... to a collection') and constrains input to uuids, so the agent knows exactly what the tool does. It does not explicitly distinguish itself from the sibling remove_product_from_collection, but the direction of the operation is unambiguous.

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

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

Provides a clear precondition ('products must already be associated with the store') that tells the agent when the call is valid, and explains the channel-sync consequence. It stops short of naming alternative tools (e.g. remove_product_from_collection, update_collection) or when-not to use it.

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

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

Annotations only carry openWorldHint=true, so the description adds meaningful behavior: it resolves provider_variant_ids by color+size from provider options, flags the AQUA-vs-Navy trap, and states variants must exist before syncing. It still omits permission needs, reversibility, and duplicate-handling 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?

Three dense, front-loaded statements with no filler, each carrying information. The trailing '[#0d5443]' artifact is noise that earns nothing and slightly harms cleanliness.

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

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

A mutation tool with no output schema and thin annotations; the description covers the core operation, a resolution rule, a trap, and a prerequisite, but leaves error cases, workspace scoping, and result behavior unexplained.

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 (25%), so the description must compensate. It adds real semantics for provider_variant_ids (resolved by color+size or passed explicitly), but says nothing about workspace or product_uuid, and defers the AQUA-vs-Navy guard mechanism to the schema.

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

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

States a specific verb+resource ('Add variants to an existing product') and clarifies it is a 'split primitive', which distinguishes it from create_product and update_product in the sibling list. It does not name a sibling directly, but the resource and operation are unambiguous.

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

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

Provides implied usage context via 'Variants must exist before syncing', giving a prerequisite/ordering constraint, and explains when to pass provider_variant_ids explicitly vs resolving them. It does not name alternatives or state when NOT to use this tool, leaving usage largely inferred.

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

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

Annotations already cover readOnlyHint=true, so the trailing "Read-only" adds nothing. The description does earn credit for two non-annotation facts: the Advanced Analytics plan gate and the "(everything else)" folding behavior that keeps totals reconciling. It still omits how long a large breakdown takes or any rate-limit/auth nuance.

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

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

Three tight sentences, front-loaded with the core action and scope, with no filler. The stray "[#127113]" artifact is dead weight but minor.

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

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

With no output schema, the description covers what an agent needs: scope (one dimension), the row-cap/folding semantics, the plan prerequisite, and read-only nature. It stops short of explaining reconciliation output fields or currency segmentation, though the schema's currency description partially covers the latter.

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

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

Schema description coverage is 100%, so all 7 parameters (dates, limit, store, currency, dimension, workspace) are already documented in the schema with defaults and constraints. The description restates the dimension options already present in the enum and the limit-folding behavior already noted on the limit param, adding no new parameter meaning. Baseline 3 is correct.

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

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

States a specific verb+resource ("Aggregate KPIs") and enumerates the exact dimensions it can break down by, which distinguishes it from a by-time tool. It never names the analytics siblings (summary/timeseries/portfolio), so an agent must infer the split from the phrase "broken down by one dimension" rather than being told.

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 supplies one hard prerequisite ("Requires an Advanced Analytics plan") which is genuinely useful for routing. However, it gives no explicit when-to-use guidance against analytics_summary, analytics_timeseries, or analytics_portfolio, leaving the agent to infer usage from the dimension phrasing alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so 'Read-only' merely restates structured data. The description does add one thing annotations cannot express: the Advanced Analytics plan requirement, which gates whether the call can succeed. It says nothing about latency, pagination, or result limits, so it is useful but not rich.

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

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

The core content is a single dense sentence front-loading the scope ('Operational health for a date range') then the metric list, with the plan requirement and read-only note appended. It is well sized for the tool's complexity, but a stray render artifact ('[#ed8ddd]') leaks into the text and earns no place.

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

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

With no output schema, the description takes on the job of telling the agent what comes back, and it does so by enumerating velocity averages, counts, rates, and a hold-reason breakdown. Combined with a fully-documented 100%-coverage input schema and readOnly annotations, an agent has enough to call it correctly; only the response shape (formatting, granularity) is left unstated.

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

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

Schema description coverage is 100%, and every parameter (end, start, store, currency, workspace) already carries a well-written description including defaults and the currency-segmentation caveat. The description adds only the generic phrase 'for a date range', so the schema is doing essentially all of the parameter work and the 3 baseline 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 names a specific resource and enumerates exactly what the report covers (fulfillment velocity stages, order counts, cancellation/refund/hold rates, hold-reason breakdown), which is far more specific than a bare name. It does not, however, distinguish itself from the nearby siblings analytics_summary, analytics_breakdown, analytics_portfolio, or analytics_timeseries, leaving the agent to guess which analytics surface to pick.

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

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

Usage is implied by the metric list and the 'Requires an Advanced Analytics plan' prerequisite, which is a genuinely useful gating condition. There is no explicit when-to-use versus the other analytics_* siblings and no statement of when-not-to-use, so an agent picking among four analytics tools still has to infer.

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

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

Annotations already declare readOnlyHint, and the description usefully adds account-tier prerequisites, the specific error returned for ineligible accounts, and the grouping rule (stores bucketed by current workspace across all viewable workspaces). That is real behavioral context beyond the annotation. It stops short of describing pagination, result size or refresh semantics.

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 body is dense and front-loaded with the core concept, which is good, but it ends with a stray artifact '[#65a008]' that carries no meaning for an agent and slightly undermines trust in the text. The middle sentence about store rollups is jargon-heavy relative to its 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?

No output schema exists, so the description carries some burden for the return shape; it names 'per-workspace KPIs plus rolled-up totals' but not the concrete metric fields or result structure. Prerequisites and error behavior are covered, so the definition is adequate but incomplete for a 4-parameter analytics tool.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including date defaults and currency segmentation. The description adds only the conceptual framing of 'per-workspace' grouping, which loosely motivates the workspace parameter but supplies no syntax or constraint the schema lacks. Baseline 3 applies.

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

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

States a specific resource (cross-client portfolio KPIs with rolled-up totals) and frames it as 'the agency view', which is a meaningful distinction. It does not, however, name the sibling analytics tools (analytics_summary, analytics_breakdown, analytics_timeseries) it must be chosen over, leaving that differentiation to inference.

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

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

It gives one strong usage gate — requires an agency (Enterprise) account with Advanced Analytics, otherwise a feature_unavailable error — but gives no explicit when-to-use comparison against the sibling analytics_* tools. The agent must infer that 'cross-client' means this tool is for agency rollups and not single-workspace queries.

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

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

Annotations already cover the read-only safety profile, and the description adds real context beyond them: the plan requirement (Advanced Analytics/Pro/Enterprise), the default 30-day window, and prior-period deltas. It does not state rate limits or the shape of the delta output, but the auth/access disclosure is genuinely valuable.

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

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

Front-loaded with the resource and metric list, followed by defaults and plan requirement in efficient sentences. However, the trailing '[#6b72a2]' artifact is stray noise that slightly detracts from an otherwise tight, low-waste definition.

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

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

No output schema exists, but the description enumerates the returned KPIs, effectively documenting the response. Combined with the plan prerequisite and default window, an agent has what it needs to invoke correctly, with only minor gaps (no mention of breakdown/timeseries routing).

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

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

Schema coverage is 100%, so all five params (start, end, store, currency, workspace) are already fully documented in the schema. The description only restates the date-range default, adding no new syntax or semantics. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (headline order/merch KPIs for a date range) and enumerates the concrete metrics returned, so an agent knows exactly what it produces. It implicitly distinguishes itself from analytics_breakdown and analytics_timeseries via 'headline'/'summary', but never names those siblings, so the differentiation is left to inference.

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

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

Provides useful scoping context ('defaults to the last 30 days') and a plan prerequisite, but gives no explicit when-to-use guidance versus the analytics_breakdown, analytics_timeseries, or analytics_portfolio siblings. Usage is only implied by the word 'headline'.

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

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

Annotations already cover read-only and open-world, so the description adds value with the plan gate, the 'zero-filled' bucket behavior, and the enumeration of returned metrics. It does not disclose result-size or rate limits, but the extra behavioral context above the annotations is meaningful.

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

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

Three front-loaded sentences that lead with the purpose and bucket granularity before the plan requirement and metrics list. The trailing '[#48246d]' token is stray noise that does not earn its place, keeping this from a 5.

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, enumerating the returned metrics per bucket is genuinely useful, and the plan prerequisite is captured. Date defaults and enum values live in the schema, so the description is essentially complete for a moderate-complexity read tool.

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

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

Schema coverage is 100%, so the schema already documents all six parameters including defaults and the interval enum. The description only restates the day/week/month bucketing and date-range concept, adding no format or nuance beyond the schema; baseline 3 applies.

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

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

States a specific resource and scope: a 'KPI trend series over a date range, bucketed by day/week/month'. This clearly separates it by shape from time-point siblings like analytics_summary or analytics_breakdown, though it never names those siblings explicitly to route the agent.

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

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

Usage is implied (reach for this when you need KPI trends bucketed over time) and one prerequisite is stated ('Requires an Advanced Analytics plan'), but there is no explicit guidance on when to choose this over analytics_summary, analytics_breakdown, or analytics_ops.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that this is an own-account signal and that cross-merchant intelligence is not yet available, but it does not describe return shape, pagination, auth requirements, or rate limits.

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, leading with the core purpose and metrics before adding scope caveats. The stray trailing '[#f6f4f3]' artifact is minor noise that keeps it from being a clean 5.

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 four-parameter analytics tool with no parameter descriptions and no output schema, the description is too thin. It conveys the high-level purpose but leaves scope, time window, workspace/store targeting, and return structure unexplained.

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%, with four parameters including two enums, and the description does not explain scope, workspace, store_uuid, or time_window. It names example metrics but does not map them to any parameter or clarify valid values beyond what the bare schema already lists.

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

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

The description gives a specific verb and resource: 'Surface insights from the merchant's own products + orders', with concrete examples like best sellers, top channel, and average order value. It also clarifies own-account scope versus future cross-merchant intelligence, though it does not explicitly differentiate from the many analytics_* 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?

The description implies an analytics use case but does not state when to use this tool instead of alternatives such as analytics_summary, analytics_breakdown, channel_performance, or analytics_ops. It notes own-account scope and read-only behavior, but offers no explicit when/when-not guidance.

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

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

Only openWorldHint is annotated, so the description carries the burden and does deliver useful behavior context: it runs as the connected account, is scoped to the account's own permissions, and the parenthetical that dedicated tools return "clean, guarded results" implies this raw path is unguarded. It still omits that DELETE/mutating calls are possible and says nothing about rate limits or failure modes.

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

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

Front-loads the "Escape hatch" framing and keeps the guidance to a few tight sentences with an inline path example. The stray marker "[#d82569]" at the end is noise that earns no 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 an open-ended, open-world tool with no output schema, the definition covers the essentials: scope, path format, prerequisite lookup, and routing to dedicated tools. It leaves return/error shape and destructive-call behavior to inference, which is a real but acceptable gap given the escape-hatch framing.

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

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

Schema description coverage is 100%, so the schema already documents method, path, body, query and workspace; baseline is 3. The description adds only the relative-path constraint and one example, which mildly extends beyond the schema but doesn't clarify body/query/workspace semantics.

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

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

States a specific verb+resource ("make an authenticated request to any ApparelHub agent API endpoint under /agents/v1") and explicitly frames itself as an escape hatch relative to the ~100 dedicated sibling tools. An agent can immediately tell this apart from accept_invite, create_product, etc.

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

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

Gives explicit when-to-use ("only for capabilities no tool covers"), when-not ("PREFER a dedicated tool when one exists"), plus a prerequisite ordering instruction ("Call get_api_reference first to find the right path"). This is about as complete as usage guidance gets.

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

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

Annotations declare openWorldHint and idempotentHint, but the description adds a genuinely important side effect not captured there: sales-channel/webhook orders are auto-submitted to Printful/Printify. That external action changes the agent's risk calculus and is exactly the kind of disclosure expected beyond annotations.

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

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

The core content is two well-ordered sentences with the side effect front-loaded appropriately. However, the trailing '[#9b6ea5]' token is inexplicable noise that appears to be a template artifact and should not be in a tool description.

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 mutation with no output schema, the description covers purpose, trigger condition, and the non-obvious fulfillment side effect. Missing are any mention of failure modes or what the response indicates, which would be minor additions.

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

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

Schema description coverage is 100% for both parameters, including the workspace-scoping note and the order_uuid provenance, so the schema already carries the semantics. The description adds nothing about parameter formats or constraints, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Approve an order that is awaiting approval') plus the downstream effect ('releasing it for fulfillment'). It differentiates itself from the nearby submit_order_to_fulfillment by explaining that fulfillment submission happens automatically for webhook orders, though it never names that sibling explicitly.

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?

'Use when an order is held for review and the user wants to let it proceed' gives a clear triggering condition. It stops short of naming alternatives (e.g. unapprove_order, approve_order_hold) or stating when-not to use it, so it is context without routing.

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

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

Annotations only cover idempotency and open-world scope, so the description carries most of the behavioral burden. It discloses a genuinely non-obvious trait: when the provider's API cannot flip the hold (Printful today), the call is deferred and returns a dashboard_url, with the hold remaining active until the provider's release fires. Minor gap: no statement about required permissions.

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 front-loaded sentences that lead with the action and then the fallback behavior; no filler. The trailing '[#7b5295]' artifact is stray noise that slightly detracts from otherwise tight prose.

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

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

With no output schema, the description correctly compensates by explaining the deferred-result shape (dashboard_url) an agent should expect. For a 3-param mutation tool this covers what's needed, though the absence of any permission or failure-mode guidance leaves a small gap.

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

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

Schema description coverage is 100%, so all three parameters (hold_uuid, order_uuid, workspace) are already documented in the schema. The description's note that hold_uuid comes from list_order_holds restates what the schema already says, adding no new semantics — baseline 3 applies.

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

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

States a specific verb and resource ('Approve a design-approval hold on an order') plus the downstream effect ('so the provider can proceed'). This cleanly separates it from sibling tools like approve_order, hold_order, and request_hold_changes.

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 tells the agent where to source the identifier ('Get the hold_uuid from list_order_holds'), which is a useful routing hint. However, it never states when to prefer this over approve_order or unapprove_order, nor any preconditions; usage is implied rather than spelled out.

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

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

Annotations only provide openWorldHint and idempotentHint, so the description carries the important behavioral burden and does so well: it discloses reversibility ('Reversible with restore_design') and non-destructiveness toward dependent products ('never touches products that already use the design'). It does not mention auth/permission requirements or whether the archived design's data is retained elsewhere, leaving a small 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?

Front-loaded with the core action and scope, then progressively adds reversibility, safety, and sibling routing; every sentence earns its place. Slightly marred by the stray '[#16a475]' token trailing the text, which adds noise.

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 reversible mutation with no output schema, the description covers what changes, how to undo it, what it does not affect, and how to choose it over siblings. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description adds no format or syntax detail beyond naming the operation. It does hint at the list_my_designs filter semantics, but that is for a sibling tool. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Archive a design') plus the resulting scope effect ('stops showing in the default gallery listing'), which distinguishes it from restore_design and delete_design named in the same text. An agent can identify the operation without opening the schema.

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

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

Explicitly says when to use it ('the right way to retire an unwanted or orphan design'), when to prefer alternatives ('Prefer it over delete_design unless the design must be removed permanently'), and how to find targets ('Find orphan designs first with list_my_designs(on_products=false)'). Routing is fully specified.

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

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

Annotations only declare openWorldHint and idempotentHint, so the description carries the behavioral load and does so well: it discloses the cross-system effects (channel + fulfillment unsync, hide) and a specific failure mode with a named error payload ('returns blocking_orders'). Nothing here contradicts the annotations; the cross-channel reach is consistent with openWorldHint=true.

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

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

Three front-loaded sentences, each earning its place: effect, failure mode with remedy, then the alternative/restore pointer. The stray artifact token '[#4b1462]' at the end is unexplained noise that slightly blemishes an otherwise tight structure.

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

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

No output schema exists, yet the description covers the one return signal that matters (blocking_orders on failure) plus reversibility via restore_product. For a 2-param, non-nested mutation with full schema coverage, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% for both parameters (workspace and product_uuid are fully documented in the schema), so the description is not required to explain them. It adds no parameter-specific detail, which is the correct baseline when the schema already does the heavy lifting.

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

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

States a specific verb and resource ('Archive a product') and expands into concrete side effects: unsync from every sales channel and fulfillment provider, then hide. It explicitly distinguishes itself from the sibling delete_product and points to restore_product, so the agent can route without opening either schema.

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

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

Gives an explicit selection rule ('Use archive rather than delete_product when a product has order history'), names the restore counterpart, and states the precondition for failure (pending orders on its variants) plus the remedy. When-to-use and a real alternative are both present.

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

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

Annotations only supply openWorldHint and idempotentHint. The description adds the substantive behavioral facts annotations omit: order records are preserved for accounting, the store is hidden from the default listing, new orders stop ingesting, and the disconnect_provider flag removes fulfillment credentials. This is exactly the side-effect disclosure an agent needs.

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

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

The scoping rule and reversibility are front-loaded in dense, efficient sentences with no redundancy. The trailing '[#b85c96]' artifact is stray noise that slightly mars otherwise tight structure.

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 reversible mutation with no output schema, the description covers when-to-use, reversibility, and flag side effects well. It omits permission/agency-scoping requirements implied by the workspace parameter, and whether the credential removal from disconnect_provider is itself irreversible.

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

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

Schema description coverage is 100%, so all three parameters are already documented. The description restates disconnect_provider with slightly more emphasis ('every connected fulfillment provider') but adds no syntax or value details beyond the schema. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb (archive) and resource (store), and immediately differentiates itself from delete by scoping archive to 'stores with order history'. An agent can distinguish archive_store from archive_product/archive_design and from delete_workspace without opening schemas.

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

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

'use instead of delete for stores with order history' gives an explicit selection rule and implies the complementary case (no order history -> delete). It also names the reverse tool unarchive_store, so the agent knows the recovery path. Nothing is left to inference.

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

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

Annotations only state openWorldHint and idempotentHint; the description adds real value by disclosing the account-wide key requirement and the precondition that the user must already be an account member. It does not mention whether role changes are reversible or notifiable, but it goes meaningfully beyond the annotations.

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

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

Two tight sentences, front-loading the action and the create-or-update duality, with prerequisites last. The stray '[#5ec6df]' artifact is formatting noise but costs little.

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 3-parameter mutation with no output schema, the description covers the action, prerequisite chain, and auth requirement. An agent has what it needs to call it correctly; only error/failure behavior is left unspecified.

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

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

Schema coverage is 100% and the role enum is fully documented with per-role meanings in the schema itself, so the description adds nothing beyond 'with a role'. Baseline 3 is appropriate when the schema carries parameter semantics.

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

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

States a specific verb (assign/update role) and resource (account member ↔ workspace), and covers both the create and update cases in one line. Distinguishable from unassign_workspace_member by the outcome, though no sibling is named explicitly.

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

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

Gives a clear prerequisite (target must already be an account member; run invite_member first) and an authorization requirement (account-wide key). It does not name when NOT to use it or point at list_account_members/get_role_matrix for discovering valid inputs, so it stops just short of explicit routing.

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

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

With only openWorldHint declared, the description carries the full disclosure burden and does so richly: it states DEFAULTS TO DRY-RUN, that applying only ever archives (never deletes, never goes live), that archiving is restricted to genuinely inert listings, and that with no demand data the proposal is 'review' and nothing is applied. This is exactly the safety framing an agent needs for a potentially destructive 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?

The safety-critical constraints are front-loaded and the prose is dense with useful content rather than filler. It loses a point for the trailing stray artifact '[#170c11]', which is noise with no 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?

With no output schema and only openWorldHint annotation, the description supplies the mutation semantics, default mode, and fallback behaviour an agent needs. The main remaining gap is the meaning of the scope enum values, which matters for selecting rather than merely invoking the tool.

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

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

Schema coverage is only 25%, and the description compensates well for dry_run (confirming the default and what happens when false) but not for the scope enum values (underperformers/out_of_date/all) or for workspace/store_uuid, which are undocumented in both schema and prose. Genuine added value on one parameter against clear gaps on the others.

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 (propose/apply) and resource (optimizations across listings), and implicitly distinguishes itself from sibling archive tools by explaining that a seen-but-unbought listing is fixed rather than archived. It is clear what the tool does, though it never explicitly contrasts itself against near neighbors like listing_changes or diagnose_tiktok_listings.

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

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

Usage context is implied rather than stated: the tool operates 'across listings' with a scope enum, and dry-run is the default. There is no explicit when-to-use/when-not guidance relative to siblings such as archive_product, sync_to_channel, or listing_changes, so an agent must infer routing from the behavioural prose.

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

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

Goes well beyond the readOnlyHint annotation: unknown categories are rejected with the valid list rather than silently returning everything; the `warnings` array signals narrower-than-requested results; and `accepts_photoreal` absence means 'no published signal', NOT 'unsuitable'. These are non-obvious behaviors an agent needs.

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

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

Front-loaded with the core purpose and scoping, and each clause carries information. Minor redundancy: find_garments is invoked twice and the warnings caveat is restated, plus a stray '[#5e449d]' artifact at the end.

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

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

With no output schema, the description usefully explains the response's `warnings`, `decoration_method`, and `accepts_photoreal` fields. Pagination semantics and the `workspace` parameter remain unexplained, a small residual gap for a 7-parameter tool.

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

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

Schema coverage is only 43%, so the description carries weight: it explains `category` resolution against the provider's own taxonomy with rejection on unknown values, `keyword` matching across the whole catalog, and how to obtain valid `provider` values. Only `page`, `per_page`, and `workspace` are left uninterpreted, which are largely self-evident.

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

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

States a specific verb (browse), resource (catalog), and scope (ONE fulfillment provider, garments to print on). It explicitly distinguishes itself from sibling find_garments, which covers a different scope (whole account).

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

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

Explicitly names the alternative and the condition that selects it: 'This searches a SINGLE provider: to ask what the whole account can do, or before concluding a garment cannot take a design, use find_garments.' It also routes to list_catalog_providers for valid provider values.

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

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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known. The description still adds material context beyond that: the cancellation is local plus best-effort at Printful/Printify, and crucially that it does NOT refund on the sales channel. That refund caveat is exactly the kind of side-effect disclosure an agent needs.

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

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

Front-loaded with the action, followed by the two consequential caveats (provider cancellation, no refund) and the usage guardrail. Efficient overall, but the trailing '[#9e800b]' artifact is stray noise that does not belong in the text.

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

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

With no output schema, the description must carry behavioral weight, and it does: it explains what is destroyed (the local order and the provider-side draft/order) and what is explicitly not done (no refund). For a destructive mutation tool this is nearly complete; only the return shape is unaddressed, which 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 description coverage is 100%, so both parameters (workspace, order_uuid) are already documented in the schema. The description adds no syntax or format detail beyond the schema, so the baseline of 3 for a schema-covered tool is appropriate.

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

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

States a specific verb and resource (cancel an order) and immediately scopes what is actually cancelled: locally plus best-effort at the fulfillment provider. This clearly differentiates it from adjacent siblings such as hold_order, approve_order, unapprove_order, or reconcile_order.

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

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

Gives an explicit guardrail -- 'only cancel when the user explicitly asks' -- which is real when-to-use guidance. It does not, however, name a non-destructive alternative (e.g., hold_order) an agent should prefer when cancellation is not explicitly requested.

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 provide only openWorldHint=true, so the description carries most of the behavioral burden. It does disclose a real side effect beyond the annotations — propagation to all variants and re-sync of every connected channel — but says nothing about reversibility, permissions, failure handling, or partial-success behavior on channels.

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

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

Two tightly written sentences with the operation and its propagation consequence front-loaded. The trailing '[#b8aca8]' token is stray noise that slightly degrades the structure but does not obscure meaning.

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

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

For a 5-parameter mutation with no output schema and minimal annotations, the description conveys the essential behavior (variant cascade + conditional channel re-sync). Gaps remain around the workspace parameter and what happens if a channel re-sync fails, but the core calling context is present.

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 40%, so the description should compensate more than it does. It usefully ties store_uuid to channel re-sync and confirms the cascade semantics of new_price, but leaves 'workspace' undocumented and does not explain the interaction between store_uuid and also_update_channels.

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 concrete verb+resource ('Change a product price') and immediately scopes it ('cascades to all variants', re-syncs connected channels). This implicitly separates it from generic siblings like update_product or set_prices_by_margin, but no sibling is named, so an agent must infer the boundary.

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

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

Usage is implied rather than stated: the 'changed on one channel, forgot the others' framing tells the agent this is the tool for keeping prices consistent across channels, and the parenthetical gives the store_uuid condition. There is no explicit when-not guidance and no named alternatives (e.g. set_prices_by_margin, sync_to_channel).

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

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

Annotations already declare readOnlyHint=true, so 'Read-only' is redundant, but the description adds real behavioral context: that unreporting channels are indistinguishable from zero-traffic ones, and that shops needing reconnection are flagged. These interpretation caveats go beyond what annotations convey.

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

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

Three sentences, front-loaded with the core purpose and followed by the key interpretive warning. The trailing 'Read-only' is redundant with annotations and the '[#df2820]' artifact is noise, but overall it is tight and well-ordered.

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

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

With no output schema, the description carries the return-value burden and does explain conceptually what comes back (reporting channels, metrics, reconnection flags). For a zero-required-parameter diagnostic tool this is largely complete, though coverage of metric naming/format is absent.

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

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

Only one parameter (workspace) with 100% schema description coverage, so the schema fully documents it. The description adds no syntax or scoping detail about the workspace argument, making baseline 3 appropriate.

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

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

States a specific resource and scope: which connected sales channels report performance data and which metrics each supplies. This is clearly distinct from performance-reading siblings like channel_performance, though no sibling is named explicitly. An agent can grasp the tool's role without opening the schema.

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

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

Gives an explicit when-to-use trigger: 'Check this before concluding a listing has no traffic,' which is a concrete precondition. It does not name a competing alternative tool or state when not to use it, so it falls short of full routing guidance.

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

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

Annotations already cover readOnlyHint, and the description reinforces it with 'Read-only.' Beyond that it discloses return shape (per-state counts, safe_to_archive, top_opportunities), the archive-safety guarantee ('Nothing else is safe to archive'), and a meaningful edge case where empty results signal a distribution problem rather than healthy listings.

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

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

Front-loaded with the core definition, then usage, then edge cases — a sensible ordering. Every sentence carries information, but the paragraph is long and contains a stray artifact ('[#7c8c30]') that adds noise.

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

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

With no output schema, the description carries the full burden of explaining returns, and it delivers (categorical outputs, per-state counts, archive list). It also covers the interpretation caveat an agent needs to avoid misreading thin results. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, so all five parameters (start, end, store, provider, workspace) are already fully documented in the schema. The description adds no format or default details beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific resource and its defining characteristic up front — listings with proven traffic but broken conversion, ranked by viewers-who-didn't-buy. An agent can immediately distinguish it from analytics_summary or channel_performance siblings. The phrasing is slightly metaphorical but is clarified in the same sentence.

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

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

Explicitly positions it as 'the natural starting point for an optimisation pass' and instructs to fix these before anything else. It also sequences a prerequisite ('READ `shop` BEFORE acting') and explains when the output is misleading (low shop views). Rare, high-value when-to-use guidance.

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

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

Annotations only cover readOnlyHint/openWorldHint, but the description adds substantial behavioral context: the full state taxonomy and what each implies, the summary.shop no_channel_traffic guardrail (the problem is distribution, not titles/images), the warning that channel product ids are only unique within their own channel, and the caution about interpreting missing metrics. This is well beyond annotation coverage.

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

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

Front-loads purpose, then the differentiating use case, then the state legend and guardrails. Every section is load-bearing, though the density and length (especially the inline state enumeration) is on the heavy side for a listing metrics tool.

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

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

With no output schema, the description compensates by explaining the state field's meaning, the summary.shop and coverage blocks, and the channel/store provenance of rows. An agent has enough to call the tool and interpret results correctly without further documentation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real interpretive value on top: it explains that each row carries its channel and store and that these must be checked before comparing rows (because channel product ids are channel-scoped), which clarifies the provider/store filter semantics beyond their 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?

Opens with a specific verb+resource: 'What the sales channel reports about each of your listings: impressions, clicks, click-through rate and units sold, plus a state.' It also explicitly distinguishes itself from the order-based analytics siblings by explaining that those cannot show see-but-don't-buy listings, so an agent can route without opening a schema.

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

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

Gives concrete when-to-use ('find listings people SEE but do not BUY'), when-not (order-based tools cannot show this), and sequencing rules ('READ `summary.shop` FIRST', 'ALWAYS check the coverage block before treating a missing metric as zero'). The state definitions double as action guidance (winner=scale, starved=needs discovery NOT a rewrite, dead=only state safe to archive).

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

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

Annotations cover only readOnlyHint and openWorldHint; the description adds material behavior beyond them: it makes no provider call, is safe to poll every few seconds (rate-limit guidance), and defines a three-state result contract including the failure mode where retrying never helps. That is exactly the context an agent needs to drive a polling loop.

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

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

Front-loads the core action in the first clause, then supplies the polling loop, the user-notification rationale, safety, and the result-state handling in tight sentences. Despite its length, every sentence carries an instruction an agent would otherwise have to guess.

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 the description compensates by enumerating the return states (connected true/false, needs_reconnect) and the correct follow-up for each. Combined with the annotations' safety profile, nothing needed to invoke and act on this 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 100% and each of the three parameters is already fully documented there, including the provider_uuid warning about false negatives and false positives. The description restates the same guidance ('pass the same provider_uuid you gave start_channel_connect') without adding syntax or constraints beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('poll whether a dispatched connection has completed') and ties it directly to the sibling it follows, start_channel_connect. An agent can distinguish this polling tool from connect_sales_channel or check_setup_readiness without opening any schema.

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

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

Explicitly says when to call (repeatedly after start_channel_connect while the user authorizes in the browser), why (the user can't see this conversation), and how to react to each outcome: connected true, connected false, and needs_reconnect with the mandated alternative action. No ambiguity remains.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds genuine non-obvious context: the check is advisory rather than blocking, it surfaces detected text only, and it carries no legal weight.

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

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

Three short, front-loaded sentences with no filler, and the disclaimers are placed where they matter. The stray trailing markup token "[#fba5cb]" is leftover artifact noise that should not be in a definition.

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 six parameters, a third of them described, and no output schema, the description leaves the agent guessing at the rest of the inputs and at what the check returns (pass/fail, risk flags, severity). Scope and limits are clear; invocation details are not.

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

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

Schema coverage is only 33%, and the two documented parameters (name, prompt) are exactly the ones the description repeats. The undocumented parameters — image_url, workspace, design_uuid, and especially target_channels, which likely selects which prohibited-content rules apply — remain unexplained in both places.

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

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

States a specific verb and resource: an advisory pre-flight scan of prompt/name/detected text for IP, trademark, and prohibited-content risk. It is distinguishable from nearby design-verification siblings through its stated scope (protected marks, prohibited content), though it never names those siblings explicitly.

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?

"Advisory pre-flight" implies the usage moment (before shipping/publishing a design), and the description gives two explicit exclusions: not legal advice and not an image-content trademark check. It stops short of naming the alternative tools an agent should reach for 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?

Annotations already declare readOnlyHint=true, but the description adds real value beyond them: it defines the return shape ({eligible, blockers}) and enumerates concrete blocker causes (product in use, forbidden source/destination), which is exactly the behavioral context an agent needs to interpret results. It stops short of permissions/rate-limit detail.

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

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

Front-loads the key concept ('Dry run') and packs return-shape and failure semantics into two tight sentences. The trailing '[#1e988c]' artifact is stray noise that detracts slightly from otherwise clean structure.

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

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

For a read-only check tool with no output schema, the description supplies the return shape and blocker meaning that the agent needs. With annotations covering the safety profile and a fully-described schema, the definition is sufficient, though it could explicitly link to move_design_to_workspace as the follow-up action.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema itself, including the optional source_workspace caveat. The description adds no parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb, resource, and scope: a dry-run report of whether a design can be moved to another workspace. It is immediately distinguishable from siblings like move_design_to_workspace (the actual mutation) and copy_design_to_workspace (the fallback), so an agent can route without opening the schema.

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

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

Clearly frames this as a pre-flight check ('Dry run... without changing anything') and tells the agent what to do on failure ('so copy instead'). It does not explicitly name the sibling tools to run before/after, so a small inference remains, but the when-to-use context is strong.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the redundant 'Read-only' adds nothing, but the description adds real behavioral context: the report is returned by default (include_report defaults true) and the tool only prepares a copy-paste summary_text plus a deep-link because providers require filing in their own dashboards. That tells the agent the tool does not actually file the claim.

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 main action is front-loaded and the content is dense and information-rich, but it is delivered as one sprawling compound sentence with heavy parentheticals. The trailing '[#2f6bdb]' fragment is an unexplained artifact that earns no place and slightly degrades the definition.

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

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

With no output schema, the description carries the burden of describing returns and does so well by enumerating the issue contents and the shape of the report (summary_text plus deep-link). It is essentially complete for calling the tool; only explicit routing guidance versus sibling issue tools is missing.

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

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

Schema coverage is 100%, so issue_uuid and workspace semantics are already covered and the baseline is 3. The description adds meaning beyond the schema by explaining what include_report actually produces (a summary_text and a provider dashboard deep-link), which clarifies the consequence of the parameter rather than just restating it.

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

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

States a specific verb (fetch) and resource (one fulfillment issue), then enumerates exactly what 'in full' contains: affected items, evidence attachments, provider claim tracking, resolution, plus the optional provider-ready report. The singular 'one' plus the 'in full' framing cleanly separates it from the sibling list_fulfillment_issues.

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

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

Usage is implied rather than stated: an agent can infer this is the detail view after list_fulfillment_issues, and the note that Printful/Printify accept problem reports only in their own dashboards explains the report's purpose. But there is no explicit when-to-use or when-to-avoid guidance relative to siblings like list_fulfillment_issues, report_fulfillment_issue, or resolve_fulfillment_issue.

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

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

Annotations only declare openWorldHint and idempotentHint. The description adds genuinely useful context beyond them: it is 'read-mostly' rather than a pure read (it writes local state, including design-approval holds), that it hits an external provider, and that it is safe to call repeatedly. It stops short of stating required permissions or failure 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 tight sentences with the core action front-loaded and the usage hint following. No filler text. The trailing '[#81b1a2]' artifact is noise but does not affect comprehension.

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

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

No output schema exists, so the description carries some return burden; it tells the agent it yields shipping/hold status, which is adequate. Combined with annotations covering external-call and idempotency behavior, an agent has what it needs to call this correctly, though exact status vocabulary is unspecified.

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

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

Schema description coverage is 100%, so both parameters (order_uuid, workspace) are already fully documented in the schema. The description adds no parameter-level syntax or format detail beyond implied order scope, so the baseline 3 applies.

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

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

States specific verbs and resource: poll the fulfillment provider for order status and update it locally. It is distinguishable from a plain read like get_order_details because it names the external polling and local-update behavior. It does not explicitly distinguish itself from sibling sync_orders, so it falls just short of the top score.

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

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

Gives a clear usage context: 'Use to see whether an order has shipped or is on hold at the provider.' That tells the agent when to reach for it. No explicit when-not conditions or named alternatives (e.g., get_order_details, list_order_holds, sync_orders), so it is not a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds real value beyond that: it explains this is a dry run that mutates nothing, and interprets the return payload ({eligible, blockers}) including concrete blocker codes (asset_in_use, asset_has_orders, forbidden_source/destination). Missing only pagination/timeout or auth caveats.

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

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

Three tight sentences, front-loaded with the dry-run intent and followed by the interpretation rule. Minor noise: the trailing bracketed token '[#81f916]' is unexplained and adds nothing.

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

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

With no output schema, the description carries the burden of describing the return shape, and it does so ({eligible, blockers}) plus the semantics of a non-empty blockers list. An agent has everything needed to call and interpret this read-only check.

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

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

Schema description coverage is 100%, including the note that source_workspace may be omitted if the product is in the Default workspace and that destination_workspace comes from list_my_workspaces. The description adds no parameter detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource+scope: a dry-run check of whether a product can be moved to another workspace, explicitly 'without changing anything.' This cleanly separates it from the sibling move_product_to_workspace (which performs the move) and check_design_move (different resource).

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

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

Gives the decision rule explicitly: a non-empty blockers list means the move would fail, so use copy instead. That routes the agent to the copy_product_to_workspace alternative and defines the precondition for calling this tool at all.

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

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

Annotations only give readOnlyHint and openWorldHint; the description adds that it makes no provider calls and is safe to poll, which is real behavioral context beyond the structured fields. It doesn't detail latency or rate limits, but for a read-only status tool this is strong.

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

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

Front-loaded with purpose and return shape, then usage guidance; every sentence earns its place. The trailing '[#01f20c]' artifact is stray noise that slightly detracts.

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

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

With no output schema, the description does the work of describing the return payload (readiness flags, per-store breakdown, next_steps). An agent has enough to call and interpret it, though the semantics of each readiness flag aren't spelled out.

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

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

Schema description coverage is 100% and the single workspace parameter is fully documented in the schema, including the multi-workspace failure mode. The description adds nothing about the parameter, so the baseline 3 applies.

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

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

States a specific verb+resource (check account setup readiness) and enumerates what it returns (ready_to_design / ready_to_fulfill / ready_to_sell, per-store breakdown, ordered next_steps). This distinguishes it from sibling diagnostics like get_account_overview or check_connection_status.

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

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

Explicit when-to-use: 'Start here for any first-time setup, and call it again after each connection to confirm the state actually changed.' No named alternative/exclusion, so it stops short of a 5, but the context is clear.

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

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

The annotations already declare readOnlyHint=true, and the description aligns by saying 'Changes nothing. Read-only.' It adds useful behavioral detail beyond the annotations: the preview shows which stores would move to the Default workspace and which members would have assignments revoked. It does not cover permissions or rate limits, but those gaps are minor for a dry-run 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 a single compact sentence that front-loads the dry-run purpose and affected entities. The trailing '[#bcfd4e]' token is extraneous and slightly harms structure, but the core text is efficient.

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, read-only preview tool, the description is complete enough: it states the action, scope, non-effect, and the categories of information the preview surfaces. Annotations cover the safety profile, and the schema covers the only parameter.

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

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

Schema description coverage is 100%, so the workspace_uuid parameter is already fully documented in the schema. The description adds no additional parameter meaning or usage syntax beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description gives a specific verb and resource: 'Dry run: preview deleting a workspace'. It explicitly scopes the preview to agency/Enterprise workspaces and distinguishes itself from the destructive sibling delete_workspace by stating 'Changes nothing. Read-only.'

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 'Dry run: preview deleting a workspace' clearly establishes the use case as pre-deletion validation. However, it does not explicitly name delete_workspace as the alternative action or state when not to use this preview, so it stops short of full when/when-not routing.

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

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

Annotations only supply openWorldHint and idempotentHint, so the description usefully adds the provider-side, production-sending side effect and the two preconditions that make the call valid. It does not state whether confirmation is reversible or what happens if the provider rejects it, which is the remaining gap for a state-changing external call.

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

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

Front-loaded with the action and its effect, followed by preconditions and sequencing — three tight sentences with no filler. Docked one point for the stray '[#ebe558]' artifact token that adds no meaning and should not be in a tool description.

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

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

For a 2-parameter mutation with no output schema, the description covers action, effect, preconditions, and workflow ordering adequately. It omits failure/error behavior and reversibility, which would matter for an agent deciding whether to call it optimistically.

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

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

Schema description coverage is 100% and both parameters are documented in the schema, including the source of order_uuid (list_my_orders / get_order_details). The description adds the concept of a 'provider order id' precondition but no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Confirm a DRAFT order') plus the consequence ('send it into production at the fulfillment provider'). It is clearly distinguishable from approve_order and submit_order_to_fulfillment, which are named or implied by the preconditions.

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

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

Explicit when-to-use conditions are given: only DRAFT-status orders that already have a provider order id, and explicitly sequenced 'after submit_order_to_fulfillment' for 'prepare, then I confirm' stores. No alternative routing is left to inference for this workflow.

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

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

Annotations only supply openWorldHint, so the description carries the burden and does it well: it discloses that the token is validated before anything is stored (ordering/failure semantics), how the multi-shop result behaves, and a security constraint (never echo the token). These are meaningful traits beyond the annotation.

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

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

Four tight sentences, front-loaded with the primary action and scoping, then validation behavior, then the multi-shop retry path, then the sibling redirect. Every sentence carries distinct information.

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

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

For a five-parameter mutation tool with no output schema, the description covers the failure mode, the multi-shop result shape, the retry path, and the security handling — enough for an agent to invoke and recover correctly without further context.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including shop_id's 'omit on the first call' note. The description reinforces the shop_id retry flow but adds no syntax or format meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Connect), a specific resource (API-token fulfillment provider with examples Printify and Gelato), and the target (a store). It also carves itself apart from the nearest sibling by explicitly routing Printful users to start_channel_connect.

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

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

Gives explicit when-to-use routing (Printify/Gelato here, Printful via start_channel_connect because it needs a browser) and a concrete when-to-reuse condition (call again with shop_id set when the token maps to multiple shops). No alternatives are left to inference.

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

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

Annotations only provide openWorldHint, so the description carries most of the burden — and it does disclose the key trait that credentials are write-only and never returned, which matters for a tool taking a secrets object. It stops short of stating success/failure semantics or whether verification is needed (check_connection_status exists as a sibling), so it is strong but not 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?

Two tightly written sentences with the routing condition front-loaded after the primary purpose. However, the trailing artifact '[#c9093d]' is stray noise that does not belong in a tool description and costs a point.

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

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

No output schema exists, yet the description never says what a successful connection yields or whether the agent should follow up with check_connection_status. Everything else an agent needs — provider routing, credential secrecy, required identifiers via schema — is covered.

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

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

Schema description coverage is 100% and each parameter already names its source (list_my_stores, list_connectable_providers, list_connectable_providers) plus the workspace omission caveat. The description adds nothing per-parameter beyond the write-only credential note, which is behavioral rather than semantic — baseline 3 applies.

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

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

States a specific verb+resource ('Connect an API-key sales channel ... to a store') and immediately scopes the provider set to WooCommerce and Wix. It also names the sibling it is not (start_channel_connect) and gives the reason, so an agent can discriminate without opening either schema.

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

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

Explicit routing rule: use this tool for API-key channels, use start_channel_connect for Shopify and TikTok Shop because they need a browser. The schema further points to list_connectable_providers for provider_uuid, completing the prerequisite chain.

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

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

Annotations only declare openWorldHint, so the description must carry disclosure and it does: it states the operation is non-destructive, that the original stays put, and that the copy gets its own duplicated image file. It also explains the single-workspace read scoping that forces source_workspace. It could still note permission/agency-account requirements, but the added context is solid.

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

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

Front-loaded with the action and its non-destructive nature, then the parameter guidance, with no wasted sentences. The trailing '[#3090dc]' is an unexplained artifact that slightly undercuts an otherwise tight structure.

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 3-parameter copy operation with no output schema, the description covers the key behaviors (non-destructive duplication, workspace scoping, where to get the destination uuid) sufficiently to invoke correctly. Only minor gaps remain, such as return value shape or error conditions.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the source_workspace condition and the list_my_workspaces pointer. The description echoes that guidance, which is helpful routing but adds little the schema does not already say, so the baseline 3 applies.

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

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

States a specific verb (copy) plus resource (design image) and destination (another workspace), then immediately distinguishes itself from the sibling move_design_to_workspace by clarifying it is non-destructive. An agent can tell copy from move without opening either schema.

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

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

Gives concrete routing: use list_my_workspaces to resolve the destination uuid, and pass source_workspace when the design is not in the Default workspace. It implies when to use copy over move via the non-destructive emphasis, but never names the alternative tool explicitly, so it stops short of a 5.

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

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

Annotations only supply openWorldHint=true, so the description carries the behavioral burden and does so well: it discloses the resulting state (unsynced DRAFT, no store mapping, fresh variants), confirms non-destructiveness, and states the source-workspace scoping precondition. This is exactly the side-effect context an agent needs before a cross-workspace copy.

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

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

Three efficient sentences, front-loaded with the action and its key property (non-destructive) before the prerequisite lookups. Docked one point for the trailing '[#d046a8]' artifact, which is noise that does not 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?

With no output schema and minimal annotations, the description adequately covers the outcome (new draft product in the destination workspace) and the preconditions. It stops short of saying what the call returns (e.g., the new product uuid), which an agent may want, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100% and all three parameters are documented in the schema, including the source_workspace omission rule and the list_my_workspaces lookup for destination_workspace. The description restates the same guidance in prose without adding new syntax, formats, or constraints, so the baseline 3 applies.

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

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

States a specific verb and resource ('Copy a product into another workspace'), scopes it to agency accounts, and immediately distinguishes itself from the sibling move_product_to_workspace by declaring the operation non-destructive with the original untouched. An agent can tell it apart from move/copy siblings without opening a schema.

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

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

Gives concrete routing help: use list_my_workspaces to obtain the destination uuid, and pass source_workspace whenever the product is not in the Default workspace. It does not, however, explicitly state when to prefer move_product_to_workspace or copy_design_to_workspace over this tool, so the exclusion side of the guidance is missing.

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

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

With only openWorldHint in annotations, the description adds some behavioral context: the collection is created empty and the name is sent as the collection title. However, it omits permissions, duplicate-name behavior, idempotency, and visibility or sync implications, so it only partially carries the disclosure burden for a create 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?

The description is front-loaded and mostly concise: three useful sentences covering creation, fields, and workflow. The trailing '[#ff2c5e]' token is irrelevant noise that slightly undercuts 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?

For a relatively simple create tool with no output schema, the description covers the core action, key fields, and next steps. Still, missing workspace parameter semantics and mutation caveats leave meaningful gaps given minimal annotations and 0% schema description coverage.

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 name and description, and 'in a store' loosely implies store_uuid, but the workspace parameter is never mentioned and no format or source details are added for store_uuid.

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

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

The description states a specific verb and resource with scope: 'Create a new (empty) collection in a store.' It distinguishes the tool from update_collection, delete_collection, get_collection, and list_collections, and names the follow-up tools add_products_to_collection and sync_collection.

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

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

It gives a clear creation workflow: provide a name and optional description, then use add_products_to_collection and sync_collection. It does not explicitly state when not to use this tool or contrast it with update_collection, but the intended usage context is clear.

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

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

With only openWorldHint in annotations, the description carries the full burden and delivers: it discloses the non-persistent-to-store lifecycle, auto-applied field names and pricing floor, automatic embroidery placement with derived thread colors, the print_style 'fill' default for face goods, and mockup auto-derivation. Little about the tool's side effects is left implicit.

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

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

Front-loaded with the standalone-product constraint before the operational details, and every clause carries information. It is long and clause-dense, and the trailing '[#5f6554]' artifact is stray noise that should not be there.

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 10-parameter mutation tool with no output schema and minimal annotations, the description covers lifecycle, defaults, downstream required steps, and the one-call alternative. An agent can call it and knows what it must do next, with no missing decision-relevant context.

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 40% across 10 params, and the description compensates for the important ones: print_style enum semantics and per-garment defaults, thread_colors being embroidery-only with omission meaning auto-derive, and generate_mockup auto-deriving variants so mockup_variant_ids is unnecessary. It does not explain workspace, design_url, or the pricing/garment substructures, so it stops short of full 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?

States a specific verb+resource ('create a STANDALONE product from a design') and immediately scopes it ('it is NOT placed on any store yet'), which cleanly separates it from ship_product and add_variants. The garment-routing and print_style default behavior further pin down exactly what this tool produces.

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

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

Explicitly names the alternative path: the add_variants -> sync_to_fulfillment -> sync_to_channel sequence for getting it listed, and 'To run that whole pipeline in one call instead, use ship_product.' This is a textbook when-to-use vs when-to-use-the-sibling statement.

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

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

Annotations only carry openWorldHint=true, so the description does the heavy lifting and does it well: it discloses the store's initial state (CLOSED) and the prerequisite to reach ACTIVE. It stops short of auth/permission requirements or error behavior (e.g., duplicate name), so not a full 5.

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

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

Front-loaded with the core action and lifecycle note; every sentence carries meaning. The trailing "[#9d5cbc]" artifact and the stray value are unexplained noise that slightly undercuts an otherwise tight definition.

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 minimal annotations, the description still supplies what an agent needs to call this correctly: the required param, the resulting state, the follow-up activation step, and the workspace-scoping caveat. Nothing essential is missing.

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

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

Schema description coverage is 100%, so baseline is 3. The description restates the workspace scoping rule that the schema already documents ("agency accounts", "Omit for the Default workspace") rather than adding format or constraint detail beyond it.

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

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

States a specific verb+resource ("Create a new ApparelHub store") and immediately differentiates from the sibling activate_store by describing the creation-to-activation lifecycle. An agent can distinguish it from update_store_settings or create_workspace without opening a schema.

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

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

Explicitly says only a name is required, explains the post-creation workflow (connect a fulfillment provider, then call activate_store to make it ACTIVE), and gives the agency-account condition for passing workspace=<uuid>. Both when-to-use and the next-step alternative are named.

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

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

Annotations only carry openWorldHint=true, so the description must supply the behavioral picture, and it does: name uniqueness, an account-wide key requirement, the feature_unavailable failure mode, and the returned uuid. For a mutation tool this is solid disclosure, though it doesn't state reversibility or downstream effects of creation.

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 substance is front-loaded and efficient, but the trailing "[#51f6a7]" fragment is stray noise that detracts from an otherwise tight four-sentence description.

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

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

For a single-param create mutation with thin annotations and no output schema, the description covers the auth requirement, error condition, uniqueness constraint, and return value — enough for an agent to call it correctly. Minor gaps remain (no guidance on post-creation membership setup).

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

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

Only one parameter and the schema already documents it at 100% coverage (unique within account, max 128 chars). The description's mention of uniqueness merely restates the schema, adding no format or syntax detail, so baseline 3 applies.

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

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

States a specific verb+resource ("Create a new workspace in the account") and scopes it to agency/Enterprise accounts, so an agent can distinguish it from update_workspace, delete_workspace, or list_my_workspaces by verb. It does not name a sibling or contrast conditions, so it falls just short of a 5.

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

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

The description gives prerequisite context (needs an account-wide key; tier without the agency feature returns feature_unavailable), which is genuinely useful usage information. However, it never says when to reach for create_workspace versus alternatives like invite_member (joining an existing workspace), leaving selection logic implied.

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

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

Annotations already flag destructiveHint=true and openWorldHint=true, but the description adds genuinely useful nuance: the platform unsyncs the collection from sales channels first, and member products survive while only the grouping is destroyed. This clarifies the blast radius beyond the binary destructive flag, though it does not address permissions or reversibility.

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

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

Front-loaded with the destructive verb and two tight sentences that each add value about side effects. The trailing '[#afdbfe]' token is stray markup that earns no place in the description.

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, but the description adequately covers the key behavioral consequence an agent must know before a destructive call (channel unsync, products preserved). It falls short on parameter meaning and permission/reversibility concerns, leaving the 0%-covered schema unassisted.

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% across 3 parameters, so the description carries the full burden and adds almost nothing: it never explains store_uuid, collection_uuid, or the optional workspace parameter. Only the singular 'a collection' hints that one collection is targeted, which the schema already implies via required UUIDs.

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

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

States a specific verb+resource ('Delete a collection') and immediately clarifies scope by distinguishing what is removed (the grouping) from what is not (member products). An agent can distinguish it from delete_product, delete_design, and delete_workspace without opening any schema.

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

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

The description explains cascading behavior but never says when to use deletion versus alternatives such as archive or unsync_from_channel, nor does it name any sibling tool. No prerequisites or exclusions are 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?

Annotations declare destructiveHint=true and openWorldHint=true, but the description goes well beyond that: it discloses irreversibility, that stored files are also destroyed, the exact refusal error code (design_in_use), and the precondition triggering that refusal. That is meaningful behavioral context the structured fields do not carry.

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

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

Three tight sentences, front-loaded with the destructive nature and the irreversible warning, and every sentence contributes routing or safety information. The trailing '[#02e216]' artifact is stray noise that slightly undercuts otherwise clean structure.

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 two-parameter mutation with no output schema, the description covers irreversibility, side effects on stored files, the failure mode, and the safer alternative. An agent has everything needed to call it correctly or avoid it.

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

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

Schema description coverage is 100% with only two parameters, so design_uuid and the optional workspace are fully documented in the schema. The description adds no syntax or format detail beyond it, which is the expected baseline here.

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

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

States a specific verb ('Permanently delete') and resource ('a design and its stored files'), and makes the scope of deletion explicit rather than tautological. An agent can distinguish it from archive_design and delete_product without opening any schema.

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

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

Names the exclusion condition ('Refused with design_in_use if any live product still uses the design'), names the alternative tool ('archive_design is the safe alternative'), and gives a default recommendation ('Use archive_design unless the design genuinely must be erased'). When-to-use, when-not, and the alternative are all explicit.

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

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

Annotations only supply destructiveHint and openWorldHint; the description goes well beyond by disclosing that hard delete cascades to variants and that synced products risk orphan listings unless unsynced first. The ordering prerequisite and cascading side effects are exactly the behavioral context an agent needs for a destructive op.

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?

Dense and front-loaded: the default behavior, the cascade, and the unsync prerequisite are all in the first two sentences. The trailing '[#020483]' tag is unexplained noise that slightly detracts from otherwise tight structure.

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 3-param tool with no output schema, the description covers side effects, ordering, and sibling routing well. It stops short of stating irreversibility/recovery (e.g. restore_product) or the scope of the undocumented workspace parameter, which are the remaining meaningful gaps.

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

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

Schema coverage is 33%, so only archive_only is documented inline ('Default false (hard delete)'); the description reinforces the archive-vs-hard-delete distinction with no schema help. The workspace parameter's scope and any restrictions on product_uuid remain undocumented in either place, so the description only partially compensates for the coverage gap.

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

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

States a specific verb and resource ('Delete (default) or archive a product') and immediately distinguishes itself from the archive_product and unsync_from_channel siblings. An agent can tell what this tool does without opening the schema.

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

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

Gives explicit when/when-not guidance: unsync before hard-deleting a synced product, use unsync_from_channel for one channel and archive_product for all, and clarifies that sync_to_channel cannot unsync. This routes the agent among three siblings by name.

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

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

Annotations already flag destructiveHint and openWorldHint, but the description goes further by disclosing exactly what happens: stores are reassigned to the Default workspace and member assignments are revoked first, plus the account-wide key requirement. This is the kind of side-effect disclosure a destructive tool needs.

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

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

Three tight sentences with the destructive scope front-loaded and the safety constraint prominent. The trailing '[#c566a1]' token is stray noise that slightly detracts from an otherwise clean structure.

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

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

For a single-parameter destructive mutation with no output schema, the description covers effects, blocking conditions, prerequisites, and a preview path. Nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100% and the schema already tells the agent the uuid comes from list_my_workspaces. The description adds no further parameter detail, so the baseline 3 is appropriate.

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

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

States a specific verb and resource ('Delete a workspace') and narrows the scope to agency/Enterprise workspaces, distinguishing it from sibling update_workspace and create_workspace. An agent can identify the operation immediately.

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

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

Explicitly names the preview alternative ('Preview with check_workspace_deletion'), states a blocking exclusion ('The Default workspace cannot be deleted'), and gives a prerequisite ('Needs an account-wide key'). This is full when/when-not/alternative guidance.

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

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

Annotations only cover readOnlyHint/openWorldHint; the description adds substantial context beyond them: `values` reflects live channel state including platform auto-fills and merchant edits (drift), `unset_required` fields are deliberately not auto-filled, `resolved_for.resolution` keyword_match is an unverified guess, large value lists are elided, and object value_type requires a channel_ref.object_schema structure.

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

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

Front-loaded with purpose and the critical ordering rule, and paragraphs are logically grouped by concern (scope, response fields, warnings). It is long and includes a stray trailing artifact token, so it is efficient but not maximally tight.

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

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

With no output schema, the description carries the full burden by explaining the return shape (fields, value_type, cardinality, free_text, requirement, values, unset_required, resolved_for) and edge cases like supported:false. An agent has everything needed to call it and interpret results.

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 60%, and the description compensates by explaining product_uuid (one listing) vs integration_uuid (shop-wide) and the include_values expansion. store_uuid and workspace remain only self-evident from the schema, so it stops short of full 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?

States a specific verb and resource: 'Discover the channel-defined listing fields you can set ... and what is currently set.' It explicitly names the sibling tools it complements (set_listing_attributes, set_channel_settings), so an agent can distinguish it from the write-side tools without opening schemas.

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

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

Gives an explicit sequencing rule ('Call this BEFORE set_listing_attributes or set_channel_settings') with the reason (guessing field names gets the value dropped), and explains the product_uuid-vs-integration_uuid selection condition for shop-wide vs per-listing scope.

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

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

Annotations only supply openWorldHint, so the description carries the behavioral burden and does it well: it discloses streaming progress, the rate-limit error taxonomy (model_rate_limited vs platform_rate_limited vs request_not_sent), and the per-design fallback_trail with model substitutions. This is rich operational context an agent cannot get from annotations.

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

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

Front-loads the core capability and keeps the routing constraint early, with dense but useful sentences. It loses a point for the trailing stray artifact '[#d84efc]', which adds no meaning and only noise.

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

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

With no output schema, the description does the work of explaining returns ('ready-to-use design(s)'), streaming, and error classes, which is strong. Minor incompleteness remains around several input parameters and any cost or latency expectations for a generative 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 only 22% across 9 parameters, so the description must compensate and only partly does: it adds meaning for needs_transparency (all-over-print rule), no_fallback (redundant with the schema's own description), and the prompt convention. count, style, source, workspace, verify_text, and garment_type remain undocumented in both places, leaving a real gap.

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

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

Starts with a specific verb+resource ('End-to-end apparel design') and immediately states the output ('Returns ready-to-use design(s)'). It explicitly distinguishes itself from the sibling upload_design by stating 'This GENERATES new artwork' and routing existing merchant files elsewhere.

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

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

Gives explicit when-not guidance: use upload_design when the merchant already owns the file and 'do not regenerate their mark', plus the conditional 'Set needs_transparency=false for all-over-print products'. Both conditions name the scenario that selects the behavior.

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 only openWorldHint provided, the description carries the behavioral burden and does so richly: it discloses that title/description writes land on a TikTok-ONLY override and never rewrite the shared product record, that `dry_run` prevents writes, that `diagnosable` does not mean live (citing deactivated/deleted listings), and that tier is a US-market signal. This is well beyond what the annotation covers.

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?

Long but front-loaded, leading with the purpose before the apply semantics and the diagnosable/listing_health warning. Dense prose earns most of its length, though a trailing artifact fragment and some stacking of caveats add minor noise.

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, so the description must explain returns — and it does, itemizing tier, machine-readable issues (code, how_to_solve, unlocked tier), recommendations, requirements, building_blocks, candidates, and listing_health. Nothing an agent needs to interpret results or act safely is missing.

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

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

Schema coverage is 67%, and the description adds real meaning to the undocumented-in-schema semantics of `apply` (safe default, hidden metadata vs merchant-visible copy) and `dry_run`. It leaves `workspace` and `store_uuid` unexplained, so it falls just short of fully compensating for the coverage gap.

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

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

States a specific verb and resource (diagnose TikTok Shop listing quality) plus the optional mutation (apply TikTok's recommendations), and implicitly distinguishes itself from siblings like auto_optimize_listings and update_product by describing the diagnosis-plus-graded-tier workflow. An agent can tell what this does without opening the schema.

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

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

Explicit when-to-use guidance: read-only unless `apply` is passed, `apply:['search_terms']` is the named safe default, `dry_run` previews, `issues[].fixable_by` gates action, and the tool must be re-run LATER due to async re-grading. It also routes the agent to update_product for manual title writes.

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

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

Annotations already declare readOnlyHint=true, but the description goes well beyond them: it discloses that the call is read-only against the fulfillment provider with no order placed, that Printify stores return a refusal (not an error worth retrying), and that variants must already be synced. These are non-obvious failure modes an agent could not infer from structured fields.

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

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

Front-loaded with the core behavior in the first clause, and subsequent sentences all carry distinct, useful constraints. It runs long and ends with a stray artifact token ('[#a2bd48]') that adds no value, which keeps it out of the top band.

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 5-parameter read-only estimator with no output schema, the description covers purpose, preconditions, provider limits, and even the returned cost components. Nothing an agent needs in order to call it correctly or interpret a refusal is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it names the three inputs to supply (store, recipient, variants + quantities), stresses that country_code AND address1 are both required because the platform rejects street-address-less requests, and introduces the out-of-schema constraint that variants must be pre-synced.

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

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

States a specific verb and resource ('Estimate production + shipping + tax + total for an order') and immediately scopes it as non-creating ('WITHOUT creating it'). An agent can distinguish this from submit_order_to_fulfillment or add_order_item without opening any schema.

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

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

Explicit when-to-use ('preview landed cost before placing an order') plus hard when-not guidance: Printify has no pre-order estimate, so it refuses — do not retry, and do not present a cross-provider comparison that silently omits Printify. This is exactly the alternative-routing an agent needs.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the trailing 'Read-only.' adds little. However the description discloses substantive behavior beyond annotations: a ranked shortlist with confirmed capability first, the `providers_searched` field for honest coverage reporting, and the crucial semantics that an empty result is not proof of nonexistence (echoed in warnings).

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?

Dense but front-loaded: the imperative and scope come first, then the sibling contrast, then defaults and return semantics. Nearly every sentence earns its place, though a stray trailing artifact and the redundant 'Read-only.' sentence are minor waste.

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

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

With no output schema, the description carries the return contract (ranked shortlist, providers_searched) and the empty-result interpretation, which is exactly what an agent needs for a 9-parameter open-world search tool. Nothing material is missing.

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

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

Schema coverage is 89%, so the baseline is 3, but the description adds real meaning: the default provider scope and when to override it, the role of accepts_photoreal as the 'can this design go on this thing' filter, and the rationale for include_unknown's default. This goes beyond restating the schema.

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

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

States a specific verb+resource+scope: searches EVERY fulfillment provider on the account for garments matching a capability. Explicitly distinguishes itself from the sibling browse_catalog ('what does THIS provider carry' vs 'what on this ACCOUNT can take this design'), so the agent can route without opening either schema.

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

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

Gives an explicit imperative when-to-use ('USE THIS BEFORE TELLING A USER AN ITEM CANNOT BE BUILT'), the reasoning behind it (capability limits are provider-scoped, not category-scoped), the named alternative browse_catalog, and the condition for narrowing scope via `providers`. Nothing is left to inference.

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

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

The only annotation is openWorldHint=true, so the description carries nearly the full behavioral burden, which it does well: it discloses that the operation is quota-free and does NOT consume an image-generation credit, and that it returns a NEW design (uuid + url). However, it doesn't state authorization requirements, whether the source image is left untouched, or any size/format limits, so it stops short of full disclosure.

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

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

Front-loads the core action and the quota-free guarantee, then elaborates on modes and the generate_image alternative. It is information-dense rather than padded, though the trailing '[#9ca805]' token is stray noise and the parenthetical alternatives make it longer than strictly necessary.

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

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

With no output schema, the description compensates by specifying the return shape (uuid + url), and it covers mode semantics, the quota implication, and the sibling alternative. An agent has everything needed to call 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 coverage is 80%, so most parameters are already documented. The description still adds genuine value by mapping aspect ratios to real use cases (tall 9:16 for phone cases, wide 16:9 for mugs) and by re-explaining pad vs crop in outcome terms (nothing cropped vs trims the edges).

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

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

States a specific verb and resource ('Fit an EXISTING design image to a target aspect ratio without generating a new one') and explicitly negates the adjacent generative operation, so it is unmistakable against generate_image. The scope ('reshapes an existing image') is front-loaded and unambiguous.

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

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

Gives concrete when-to-use context (adapt a square design to a product's print area, with 9:16 phone case / 16:9 mug examples) and names the alternative explicitly: use generate_image for outpainting instead of flat pad/crop. Both the routing condition and the exclusion are 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 only openWorldHint=true in the annotations, the description carries the behavioral burden and does so well: it discloses the return value shape ('raw generated image'), the three-way rate-limit error taxonomy (model_rate_limited vs platform_rate_limited vs request_not_sent), and the fallback_trail substitution signal. This is exactly the kind of operational context an agent cannot get from the schema.

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

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

Purpose is front-loaded, then the follow-up workflow rule, then error semantics — a sensible ordering with dense but non-padded prose. The stray trailing '[#e8fffe]' token is unexplained clutter that costs it a point.

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

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

For a 7-parameter, multi-model generation tool with no output schema, the description adequately covers what comes back, what to do next, and the failure modes. It is silent on the cost/credit implication of a generation and on the workspace/style parameters, which prevents a 5.

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 57%, so the schema already documents size, source, no_fallback, and augment_prompt_for_transparency in detail, while style, prompt, and workspace are undocumented in both places. The description touches transparency indirectly (via process_transparency) and mentions fallback_trail, but adds no new parameter-level meaning beyond what structured fields provide, so the baseline 3 applies.

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

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

States a specific verb+resource ('Generate a design image') and positions itself as the split primitive of design_apparel, which helps an agent separate it from the higher-level pipeline tool. It does not, however, distinguish itself from other image-producing siblings such as generate_listing_image or iterate_design, so the differentiation is real but partial.

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

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

Gives one concrete sequencing rule: follow with process_transparency for apparel needing a transparent background. That is genuine conditional guidance, but there is no statement of when to prefer this over design_apparel (the pipeline it belongs to) or when not to use it at all, leaving the alternative-selection reasoning largely implied.

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

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

Annotations only carry openWorldHint, so the description must do the heavy lifting — and it does: it discloses the refusal-on-missing-mockup behavior, that it edits the existing mockup rather than inventing a product, that generation spends account quota, and that the result is returned but not attached by default.

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

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

Front-loaded with the what, then labeled HOW IT WORKS, a bolded warning, COST, and default-behavior sections. Efficient for the amount of risk it must convey, though the cost paragraph and warning overlap slightly and the trailing marker token is noise.

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

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

For a 7-parameter mutating/generating tool with no output schema, the description covers refusal conditions, cost, default-vs-attach semantics, and sibling contrast. An agent has everything needed to call it correctly and safely.

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 already 100%, but the description still adds meaning: `guidance` is additive and cannot override product fidelity, `attach` appends rather than replaces, and `source_image_url` must be an existing listing image and defaults to the best mockup. This goes beyond the schema text.

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

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

States a specific verb and resource — generating listing photography for an existing product — and enumerates the four styles (on-model, detail, flat lay, lifestyle). It crucially distinguishes itself from text-to-image and from from-scratch generation, which an agent cannot infer from the name alone.

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

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

Gives explicit when-not (no mockup → refused, use ship_product/create_product first), names the sibling it contrasts with (set_product_images replaces the gallery, this appends), and explains how to use `guidance` correctly. Even includes a cost/looping caution for catalogue-wide use.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' simply repeats that. The genuinely additive parts are the credential requirement (account-wide key) and the plan gating (Agency/Enterprise), which an agent needs before invoking and cannot get from annotations. No return format or freshness detail is given, but the auth/plan context carries real weight.

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 content is dense and front-loaded: returned fields first, then eligibility/credential constraints, with almost no filler. The stray trailing token '[#bf5472]' is noise that should not be in the definition, which keeps it from a perfect score.

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 present, the description correctly compensates by enumerating the returned fields, and it states plan eligibility and key scope. It is complete enough to call the tool safely, though it omits any note on how seat figures are scoped or whether the agency flag can be absent.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead spends its space describing outputs (account name, role, agency flag, seat counts), which is appropriate and adds no conflicting parameter information.

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 enumerates exactly what the tool returns at account level: account name, caller's role, agency-feature flag, and seat accounting (used/included/billable). That is specific and distinguishes it from account-adjacent siblings like list_account_members or get_role_matrix, though it never states an explicit verb such as 'retrieve'.

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 supplies applicability context ('Agency / Enterprise; needs an account-wide key'), which tells an agent the plan tier and credential scope required. However, it names no alternatives and gives no when-not-to-use condition against the many sibling account/settings tools, so usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds meaningful context beyond that: the return shape (endpoint index plus a `connector` object with version and tool names) and the critical interpretation rule about stale tool lists vs. unbuilt features. It omits any auth or rate-limit notes, keeping it at 4.

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

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

Purpose and the api_request handoff are front-loaded, which is correct. The second paragraph is somewhat repetitive (stale list / reconnect / don't report missing are restated), and the trailing '[#5dc40c]' token is unexplained noise that dilutes an otherwise tight definition.

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, but the description compensates by explaining both return components (endpoint index and connector block). For a discovery tool with one optional param and read-only annotations, everything an agent needs to call and interpret it is present.

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

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

Schema description coverage is 100% and the single `filter` param is fully documented in the schema (substring match with examples). The description adds no extra syntax or semantics for it, so baseline 3 applies.

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

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

States a specific verb and resource ('Discover the full ApparelHub agent API') and precisely describes the payload: 'a compact index of every endpoint (path, methods, summary) from the live OpenAPI spec.' It is clearly distinguishable from its sibling api_request, which it explicitly feeds.

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

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

Gives an explicit trigger — 'Use this when no dedicated tool covers what you need' — and names the follow-up tool ('then call it with api_request'). It also states what to do if a capability is missing, which is real routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description's 'Read-only' merely restates that. It does add value by disclosing the returned contents (member products, per-channel sync status), but says nothing about permissions, whether a missing uuid errors versus returns empty, or freshness of the sync data.

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 the scope and payload front-loaded, no filler. Slightly marred by the stray trailing artifact '[#71cbae]' that carries no meaning for an agent.

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