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

Annotations already flag mutation and non-idempotency, and the description adds genuinely useful context: the required write_orders scope and the target API version. It stops short of saying whether an existing coupon on the checkout is replaced or added alongside another, which matters for a non-idempotent call.

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

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

The purpose sentence is front-loaded and the endpoint/scope metadata follows in a compact block. The API version line is boilerplate that arguably doesn't help an agent decide or invoke, but nothing is bloated.

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 small non-idempotent mutation with no output schema, the description covers what it does and the auth scope, but omits what response or effect to expect and how repeated application behaves, which the agent must infer.

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 id and coupon_id are already documented in structured form, and the description adds no format or constraint detail beyond them. The opaque additional_fields escape hatch is likewise left 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 (attach) and resource (coupon on an abandoned checkout), plus the exact HTTP route POST /checkouts/{id}/coupon. An agent can distinguish this from coupons_create or carts_delete_coupon 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 parenthetical '(recovery campaigns)' implies the scenario in which this is used, but there is no explicit statement of when to prefer this over tiendanube_coupons_create or tiendanube_carts_delete_coupon, nor any prerequisite or exclusion.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered elsewhere. The description usefully adds the required OAuth scope (read_orders) and API version, but says nothing about behavior when the ID is unknown or about payload size 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?

Four short lines with the operation stated first, followed by endpoint, scope and API version — no filler. It is efficient, though the metadata lines are terse and could be consolidated.

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

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

For a simple read-by-ID tool with a fully documented 3-parameter schema and no output schema, the description covers what is needed to invoke it correctly, including endpoint and auth scope. Error/not-found behavior is the only notable omission.

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 id, fields and response_format each documented in the schema, so the baseline of 3 applies. The description adds no meaning beyond repeating {id} as a path placeholder — it does not explain the fields projection or the markdown/json choice.

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

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

States a specific verb and resource ('Get one abandoned checkout') and the underlying endpoint GET /checkouts/{id}, so it is clearly a single-resource fetch. The 'one' plus the {id} path implicitly distinguishes it from the sibling tiendanube_abandoned_checkouts_list, though the sibling is never named.

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 required 'id' in the path implies the tool is for retrieving a known checkout, and usage is implied by the list/get split. However, there is no explicit when-to-use or when-not-to-use guidance and the alternative list tool is not referenced.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description earns credit for what it adds: the required read_orders scope, the pinned API version, and the exact response envelope shape — the latter matters because no output schema exists. It stops short of noting rate limits or how the 6-hour/30-day window interacts with the created_at filters.

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 lines: what it lists and its scope first, then endpoint, scope requirement, API version, and return shape. No filler, and the most decision-relevant information is front-loaded.

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

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

For a read-only list tool with zero required parameters and a well-documented schema, this is nearly complete — the missing output schema is compensated by the explicit response envelope. The remaining gap is the unresolved interaction between the fixed abandonment window and the caller-supplied date filters.

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 and the description adds no per-parameter detail. It does implicitly constrain the date semantics (only checkouts abandoned > 6 hours and within 30 days), but leaves ambiguous whether created_at_min/created_at_max can reach outside that window — which is exactly the clarification an agent would need.

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

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

States a specific verb and resource ('List abandoned checkouts') plus the defining domain criteria: abandoned > 6 hours ago and up to 30 days back. An agent immediately knows what this returns. It does not explicitly contrast with the singular tiendanube_abandoned_checkouts_get sibling, but the list/get distinction is conventional enough to infer.

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 definition — the time window tells the agent this is for recent-abandonment reporting — but there is no explicit 'use this instead of X' or when-not guidance. With a singular get sibling and related carts/orders tools present, naming the alternative would have removed guesswork.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=false, openWorldHint=true), the description adds genuinely useful behavior: the HTTP verb/path and, critically, the required OAuth scope write_charges, which determines whether the call will even authorize. It stops short of saying whether the charge is billed immediately, is immutable, or what a duplicate call does.

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

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

Four short lines, front-loaded with the action, then endpoint, scope, and version. Nothing is padded and every line carries operative information an agent needs before calling.

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 carry return-value expectations, and it doesn't say what a created charge returns or how billing/proration works. For a money-moving mutation on an app service this leaves a meaningful gap, though the auth scope and endpoint partially compensate.

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 both parameters; the description only reconfirms service_id as a path segment via 'POST /services/{service_id}/charges'. The 'charge' payload is an opaque anyOf object whose real semantics live in the external Billing API reference, and the description adds no field-level meaning.

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

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

Specific verb+resource: 'Create a one-off or usage charge for an app service' tells the agent exactly what is produced and at what scope (app service billing). No sibling tool covers billing charges, so there is nothing to disambiguate against, which caps it 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 states the prerequisite ('Required scope: write_charges') and the target surface (app service), which implicitly frames when this applies, but it names no alternative tool and gives no when-not guidance (e.g. subscriptions vs one-off charges, or which sibling billing plan/subscription endpoint to use 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 disclose readOnly=false, openWorld=true, idempotent=false and destructive=false, so the safety profile is covered. The description adds useful operational context (POST /plans, write_plans scope, API version 2025-03) that the annotations do not, but it says nothing about what happens on duplicate plans or error behavior for a non-idempotent create.

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

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

Four short lines, front-loaded with the action, then HTTP path, scope and API version — no filler. It is terse to the point of being an API stub, but nothing is wasted.

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

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

For a non-idempotent create with a single completely opaque required body parameter and no output schema, the description should explain what a plan definition contains and what the response provides. It supplies solid operational metadata (endpoint, scope, version) but leaves the payload effectively undocumented.

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 nominally 100%, so the baseline is 3. However, the schema's 'plan' is an unconstrained anyOf object/array and the schema text just points to 'the Billing API reference'; the description adds no field names or shape details, so the agent learns nothing beyond what the schema already fails to say.

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

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

States a specific verb and resource ('Create an app billing plan') and is clearly separable from siblings like tiendanube_billing_plans_update, tiendanube_billing_plans_delete and tiendanube_billing_charges_create. It does not explicitly name those siblings, but the resource boundary is unambiguous.

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

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

The description gives a prerequisite (required scope write_plans) and the backing endpoint, which implies when the tool is callable, but it never states when to use this versus update/charge tools or what preconditions the plan requires.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not required to carry the safety profile. It usefully adds the required auth scope ('write_plans'), the HTTP verb/path, and API version — context not present in the annotations. It stops short of describing the consequence for subscriptions bound to the plan.

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

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

Four short, front-loaded lines with the purpose first, then endpoint, scope, and version. Zero filler, and each line 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 single-parameter destructive delete whose annotations already flag destructiveness and idempotency, the description covers the essentials: action, endpoint, auth scope, and version. The one meaningful gap is the downstream effect on existing billing subscriptions.

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

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

With a single parameter at 100% schema description coverage, the schema already carries the semantics of plan_id. The description only shows it as a path segment ({plan_id}), adding format/location context but no meaning beyond the schema — 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?

The description states a specific verb and resource ('Delete an app billing plan'), which immediately distinguishes it from the billing_plans_create and billing_plans_update siblings. An agent can route to it 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?

Usage is implied by the name and by the presence of create/update siblings, and the required 'write_plans' scope acts as a prerequisite signal. However, there is no explicit statement of when to prefer this over alternatives or of any preconditions such as whether active subscriptions must be removed first.

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

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

Annotations already declare readOnly=false, idempotent=true, and destructive=false, so the mutation semantics are covered. The description adds genuinely useful operational context — the write_plans scope requirement and the 2025-03 API version — but says nothing about partial-update behavior or what happens to omitted fields on a PATCH.

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

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

Five short lines, zero filler, with the action stated first and the endpoint/scope/version metadata trailing. Every line carries distinct information an agent can act on.

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, the description covers the auth scope and API version but leaves the most consequential unknown unaddressed: which fields the free-form 'plan' object accepts and whether the update is partial or full. An agent can invoke it but cannot construct a correct body without outside knowledge.

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 both plan_id and plan. The description adds the {plan_id} path binding and the PATCH method, which clarifies how plan_id is used, but the free-form 'plan' object remains opaque in both places. Baseline 3 plus the path-binding detail lands at 4.

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 ('Update an app billing plan'), which cleanly separates it from its siblings tiendanube_billing_plans_create and tiendanube_billing_plans_delete. It stops short of naming those siblings explicitly, so it lacks the differentiation language a 5 would require.

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 the HTTP verb, path, and required scope, which implies when the tool applies, but never states the conditions under which an agent should update versus create or delete a plan. Usage is therefore inferable rather than 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?

The annotations provide high transparency regarding safety (readOnlyHint, destructiveHint). The description primarily adds technical metadata (HTTP path, scope, version) rather than explaining behavioral constraints like rate limits or failure modes. The description adds marginal value beyond what the structured fields already communicate.

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 definition is appropriately sized and highly efficient. It immediately front-loads the purpose and then follows with concise technical implementation details without extraneous language.

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

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

Given the high richness of the annotations and the comprehensive input schema coverage, the description provides a complete operational overview. It specifies the technical context (API path, scope) necessary for an agent to confidently execute the 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?

The descriptions for the parameters add meaningful context beyond the schema. Specifically, it clarifies the origin of the 'service_id' (Partner Portal) and provides usage examples for the 'fields' parameter to reduce payload size.

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

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

The description clearly identifies the resource ('subscription(s)') and the context ('app service') using a specific action verb ('Get'). It is highly descriptive, though it could be slightly clearer by contrasting it with related subscription tools (e.g., those for orders).

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 resource name and API path, but the description provides no explicit guidance on when to use this tool versus alternatives. An agent might confuse 'app service' subscriptions with customer 'order' subscriptions present in the sibling tools list.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description does add genuinely useful non-annotation context: the required write_subscriptions scope and the API version. However, it says nothing about what a PATCH does when fields are omitted, whether the update is partial or a replace, or what happens on an invalid service_id.

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

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

Four short lines, action statement front-loaded, with supporting metadata below. Nothing is padded, though 'API version: 2025-03' contributes little to an agent's decision to call the 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?

Only two required parameters and no output schema, so the bar is low, but the core payload (subscription fields) is completely opaque in both schema and description. For a mutation whose argument is an untyped free-form object, pointing at an external 'Billing API reference' leaves a real gap an agent cannot resolve from the definition alone.

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 are already documented, and the endpoint line reinforces that service_id is a path parameter. The subscription parameter's schema is an unconstrained anyOf object/array, and the description does nothing to clarify its shape beyond deferring to 'the Billing API reference'. 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 (Update) and resource (the store's subscription for an app service), and pins the exact endpoint PATCH /concepts/app-cost/services/{service_id}/subscriptions. That clearly separates it from sibling reads like tiendanube_billing_subscriptions_get and from tiendanube_billing_plans_update or tiendanube_billing_charges_create, though it never says so 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?

There is no guidance on when to choose this over the sibling tiendanube_billing_subscriptions_get or the plans/charges tools, and no stated preconditions beyond the scope string. The agent must infer the use case entirely from the name and endpoint.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description usefully adds the required OAuth scope ('read_content'), the pinned API version (2025-03), and the full response envelope {count, page, per_page, total?, has_more, next_page?, items[]}, which matters since there is no output schema.

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

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

Five short lines, front-loaded with the verb and resource, followed by endpoint, scope, version and return shape. No filler or repetition of the title.

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

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

For a read-only list tool with 100% schema coverage and full annotations, the description supplies the missing pieces: auth scope, API version, and return envelope in the absence of an output schema. Only pagination-walking guidance 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?

Schema description coverage is 100% and every parameter (page, per_page, fields, response_format, blog_id) is documented in the schema, so the baseline of 3 applies. The description adds no extra semantics about parameter interaction, such as the page*per_page cap, which the schema already carries.

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

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

States a specific verb and resource ('List posts of a blog') plus the exact HTTP route, so an agent can tell it apart from tiendanube_blogs_list and tiendanube_pages_list by resource alone. It does not explicitly call out the sibling boundary, which keeps it just below 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?

Usage is only implied: the required scope 'read_content' and the mandatory blog_id signal a read operation on an existing blog, but there is no guidance on when to prefer this over tiendanube_blogs_list or how to paginate across large result sets. Adequate but leaves the routing decision 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 already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful context beyond them: the required read_content scope, the API version, and the pagination envelope returned. The only gap is it doesn't state filtering/sorting behavior, which for a plain list is minor.

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?

Extremely compact and front-loaded: the purpose sentence comes first, followed by endpoint, scope, version, and return shape in that order. The terse field-list style is efficient rather than wasteful, though the return-shape line is somewhat notation-dense.

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

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

For a simple read-only list tool with no output schema, the description supplies the missing pieces an agent needs – auth scope, API version, and the exact response envelope including pagination fields. It stops short of 5 only because the relationship to blog posts endpoints is unaddressed.

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 page, per_page, fields, and response_format are already fully documented in the schema. The description adds nothing about parameter semantics, which is the baseline-3 case when the schema carries the load.

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

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

The description opens with a specific verb and resource ('List blogs of the store'), which an agent can immediately map to the blogs collection. It does not explicitly contrast with the nearest sibling tiendanube_blog_posts_list, so the list-blogs vs list-posts distinction must be inferred from the names.

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 'List blogs of the store' – an agent can reasonably infer this is the read operation for blogs – but there is no explicit statement of when to use it instead of tiendanube_blog_posts_list or which prerequisites must hold beyond the scope line.

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

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

Annotations cover the safety profile (idempotent=true, destructive=false, openWorld=true), and the description adds genuinely new context: this is a PUT upsert, so 'replace' means the prior rule configuration for that domain is superseded, plus the exact HTTP route and API version. It does not spell out what the response contains or whether other domains' rules are untouched.

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 purpose sentence followed by compact structured lines for route, scopes, and version. Every line carries operational information with no filler.

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

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

For a two-parameter mutation tool with no output schema, the description supplies the route, auth scopes, API version, and upsert semantics — enough to invoke it correctly. The main gap is the opaque 'rules' payload shape and the absence of any note on return values or partial-failure behavior.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description only partially adds meaning by mapping the 'domain' enum values to their required scopes. The 'rules' payload is a freeform object/array and neither schema nor description explains its structure, so no additional semantic detail is contributed there.

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

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

Specific verb phrase ('Create or replace') paired with a precise resource ('conditional business rules') and the concrete checkout objects those rules filter (payment methods, carriers, locations, cart behaviour). No sibling tool covers business rules, so the scope statement alone makes it 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?

It names the domain-specific prerequisites up front via per-domain required scopes (write_shipping, read_payment_options, write_locations, write_orders), which tells an agent whether it can call the tool for a given domain. It stops short of stating exclusions or when-not-to-use conditions, but there is no competing sibling to route against.

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 disclose destructive=true, idempotent=true, openWorld=true, readOnly=false, so the safety profile is covered. The description usefully adds the required OAuth scope (write_orders) and API version, which are genuine additions, but it doesn't say whether totals are recalculated, whether a missing coupon errors, or what state the cart ends in.

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 purpose is front-loaded in the first line, followed by compact metadata lines (endpoint, scope, version) that each carry distinct information. No filler sentences, though the metadata block is dense shorthand rather than 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?

For a two-parameter destructive call with rich annotations and no output schema, the definition covers identity, endpoint, and auth scope adequately. It is still thin on outcome: an agent doesn't know whether the call returns the updated cart, an empty body, or an error condition.

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

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

With 100% schema description coverage, both id and coupon_id are already documented in the schema. The description only restates them indirectly through the path template (/carts/{id}/coupons/{coupon_id}) and adds no format, type, or resolution guidance beyond that, 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?

The description uses a specific verb and resource ("Remove a coupon applied to an active cart"), which separates it in practice from tiendanube_coupons_delete (deletes the coupon definition) and tiendanube_abandoned_checkouts_apply_coupon. It doesn't explicitly name those siblings, so an agent must infer the boundary, keeping it 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 mention of "active cart" implies the applicable context, but there is no explicit when-to-use / when-not-to-use guidance and no named alternative. Nothing tells an agent what to do if the cart is inactive or the coupon isn't 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 already declare destructive=true, idempotent=true and openWorld=true, so the mutation profile is covered. The description adds genuinely new context: the required scope "write_orders" and the API version, which the agent needs to know before attempting the call and 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?

Four short lines with the action front-loaded, followed by endpoint, scope and version metadata. Nothing is padded, though the HTTP verb/path line largely restates the tool name.

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

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

For a destructive two-parameter mutation, the description covers the endpoint, scope and version, which is adequate given annotations handle the safety profile and both params are fully documented. It omits what the response contains or whether the cart total is recalculated, leaving a small but real gap for a write operation.

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

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

Schema description coverage is 100%, so both parameters (cart id, line_item_id) are already documented, including the 64-bit/pass-as-string caveat. The description's HTTP path echoes the parameters without adding format or edge-case 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?

"Remove one line item from an active cart" gives a specific verb (remove) and resource (line item within a cart), distinguishing it from carts_get and carts_delete_coupon. It stops short of explicitly naming which sibling applies to a different granularity of removal, but 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?

The phrase "from an active cart" implies a precondition (the cart must be active), but there is no explicit when-to-use/when-not guidance and no mention of alternatives such as emptying the whole cart. An agent gets no help choosing between this and other cart mutation siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuine context beyond that: the HTTP verb/path, the required OAuth scope (read_orders), and the pinned API version 2025-03, which matters for behavior stability. It stops short of describing pagination or error conditions (e.g. cart not found / expired).

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

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

Four short lines, front-loaded with the purpose followed by the endpoint, scope, and version. Every line carries usable information for an API wrapper; the only mild redundancy is the HTTP line restating the verb already in the first sentence.

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 getter with full schema coverage and four annotations, this is close to self-sufficient: method, path, scope, and version are all present. The one remaining gap is that with no output schema, 'state and contents' is the only hint at the return payload, so an agent can't predict the shape of the cart object.

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 ID, fields projection, and response_format enum are fully documented in the schema itself. The description adds no parameter-level meaning (no format for id, no guidance on when to use fields). Baseline 3 applies when the schema carries the burden.

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

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

States a specific verb and resource ('Get the state and contents of an active cart') with a scope qualifier ('active'), which is more than a restatement of the title. It doesn't explicitly contrast with the cart-related siblings (carts_delete_line_item, carts_delete_coupon), but those are obviously mutating operations whose names diverge enough that confusion is unlikely.

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 — retrieve a cart by ID — and the 'Required scope: read_orders' line gives a real prerequisite. However, there is no statement of when to prefer this over e.g. abandoned_checkouts_get or orders_get, and no note on what to do when a cart is no longer active. Adequate but not guiding.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context by stating the required scope and API version, but it does not describe the response, error behavior, or side effects beyond what annotations already 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?

The description is extremely concise and front-loaded: it states the action first, then provides practical HTTP, scope, and version details in compact lines. Every sentence earns its place with no wasted words.

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

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

For a create tool with annotations covering safety and a fully documented 8-parameter schema, the description gives the essential invocation context: endpoint, required scope, and API version. It lacks any note about the returned resource or error handling, but no output schema exists, so that omission is a minor gap rather than a critical one.

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 parameters (including nested i18n objects and parent) are already documented in the schema. The description only reiterates parent usage for nesting, which is already described in the schema's parent field description. Baseline 3 is appropriate when the schema carries the 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?

The description states a specific verb and resource: "Create a category." It also adds "set parent for nesting," which clarifies the nesting behavior. It does not explicitly differentiate this tool from its siblings (e.g., categories_update or categories_list), though the create intent is clear from the name and description.

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 a useful usage hint ("set parent for nesting") and states the required scope (write_products), which is a prerequisite. However, it provides no explicit guidance on when to use this tool versus alternatives such as categories_update or categories_list, nor does it state exclusions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful operational context the annotations don't: the HTTP endpoint, the required write_products scope, and the API version. It stops short of stating side effects like what happens to child categories or products referencing the deleted category.

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 compact metadata lines (HTTP method, scope, version). No filler, though the endpoint line partly duplicates the schema's path parameter.

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 one-parameter delete, the scope and endpoint are helpful, but the description omits cascade/side-effect behavior and confirmation expectations. An agent would still be unsure what breaks when the category is removed.

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 id parameter is documented as "Category ID", so the baseline is 3. The description only restates the path template (DELETE /categories/{id}) without adding format or type meaning beyond the schema.

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

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

States a specific verb and resource ("Delete a category"), which is unambiguous on its own. It does not differentiate itself from sibling category tools (get/list/create/update) or name alternatives, leaving that to the tool name.

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

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

No guidance on when to use this versus categories_update or categories_list, and no warnings such as preconditions (e.g., deleting a parent category with children, or categories still assigned to products). The agent must infer the usage context entirely.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds valuable non-annotation context: the required OAuth scope ('read_products') and the pinned API version ('2025-03'), which an agent needs to predict auth failures.

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 verb+resource, followed by terse HTTP endpoint, scope, and version lines. Every line carries useful information with no filler, though the label-style formatting is slightly dry rather than 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?

For a simple single-resource read with full schema coverage, functional annotations, and the scope/version metadata provided, the definition is nearly complete. Output shape is left unspecified (no output schema), but the annotated read semantics make this 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 all three parameters (id, fields, response_format) are already documented in the schema. The description only references the id via the path template and adds nothing about fields or response_format, 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 ('Get') and resource ('one category'), making it clearly distinct from the sibling tiendanube_categories_list. It does not explicitly name alternatives, but the singular 'one' plus the id path makes the differentiation self-evident.

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 'Get one category' requiring an id, but there is no explicit statement of when to use this versus categories_list or categories_update. An agent can infer intent but gets no stated exclusions or prerequisites beyond the scope note.

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

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

Annotations already declare readOnly, idempotent, non-destructive, but the description adds genuine value on top: the concrete endpoint, the required OAuth scope, the pinned API version, and the exact pagination envelope returned. It does not discuss rate limits or how filters interact, which keeps it short of a 5.

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

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

Front-loaded with the action, then a compact metadata block where each line carries information (endpoint, scope, version, return shape). The 'HTTP: GET /categories' line is marginally redundant with the name, but nothing else is filler.

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

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

For a 12-parameter read-only list tool with full schema coverage and no output schema, the definition covers safety (via annotations), auth scope, and the return envelope — enough to call it correctly. It is slightly thin on pagination strategy and on disambiguating from the price-table category listings.

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

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

Schema description coverage is 100%, so every one of the 12 parameters is already documented, making 3 the baseline. The description adds no parameter-level insight, such as how parent_id interacts with pagination or when to prefer since_id over page, and instead spends its space on the response envelope.

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

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

States a specific verb and resource ('List categories') that is clearly separable from the sibling tiendanube_categories_get (single category). It does not explicitly name or contrast the sibling, and does not mention tiendanube_price_tables_categories_list, which is a different kind of category listing an agent could confuse it with.

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

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

No guidance on when to use this versus tiendanube_categories_get or the price-table category listings, and no note on when filters (parent_id, since_id, date ranges) matter. The only prerequisite-style information is the required scope 'read_products', which is useful but is an auth constraint, not usage direction.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), matching PUT semantics. The description adds the auth scope requirement (write_products) and API version, which is real value, but it omits partial-vs-full update semantics — whether omitted fields are preserved or cleared — which matters for a 9-param 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 with the verb+resource, and the HTTP/scope/version lines are terse. However, the raw endpoint and API version lines are boilerplate that add little decision value for an agent.

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 not need to explain returns, and the schema fully documents the 9 params including nested i18n objects. Annotations cover safety, so the primary remaining omission is update semantics, which is a modest gap against otherwise complete structured data.

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 documents all 9 params, including the i18n nested object pattern, so the schema carries the parameter burden. The description adds nothing about parameters, 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?

"Update a category" states a specific verb and resource, and the PUT endpoint confirms a full-update operation. It distinguishes cleanly from the sibling CRUD operations (create/get/list/delete) by the verb alone, though it does not explicitly name those alternatives.

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

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

The required scope (write_products) is a useful precondition, but there is no explicit guidance on when to use this versus categories_create or how it differs from a partial update. Usage is only implied by the "Update" verb and the {id} path.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely useful context beyond them — the required write_coupons scope, the POST /coupons endpoint and the API version — but says nothing about failure behavior (e.g. duplicate coupon codes are rejected, invalid date ranges), which matters for a non-idempotent create.

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

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

Four short, front-loaded lines with no filler; the verb+resource leads and the operational metadata follows. Slightly more could be trimmed (API version is of marginal use to an agent deciding how to call it).

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 15-parameter nested create with no output schema, the description is adequate but thin: it doesn't say what comes back (a coupon object with an id), nor flag conditional parameter dependencies beyond what the schema hints at. An agent can call the tool, but lacks a behavioral picture of the result and error path.

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

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

Schema description coverage is 100%, so every one of the 15 parameters is already documented in the schema, including the shipping/percentage value nuance. The description adds no parameter-level meaning, 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 ('Create a discount coupon'), which is unambiguous and matches the coupons_* family of siblings. It does not, however, distinguish this from the adjacent tiendanube_promotions_create or explain the coupon-vs-promotion 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?

The required write_coupons scope implies the precondition for calling it, but the description never says when to use this versus promotions_create / discounts_callbacks_upsert, nor any when-not condition. Usage is inferable from the name rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds genuinely new behavioral context: the required write_coupons scope, the HTTP verb/path, and the API version — all of which affect whether the call can succeed.

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

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

Four short lines, front-loaded with the action and followed by endpoint, scope, and version. Nothing is padded, though the API version line contributes little to invocation decisions.

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

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

For a one-parameter delete with no output schema, the description plus annotations cover what an agent needs: action, target, auth scope, and idempotency/destructiveness. A brief note on irreversibility or on retrieving the ID would make it complete.

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

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

With 100% schema description coverage and a single 'id' parameter documented as 'Coupon ID', the schema carries the burden. The description's `{id}` path reference adds nothing beyond what the schema already says, 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 ('Delete') and resource ('a coupon'), which cleanly separates it from the sibling coupons_list/get/create/update tools. It is clear but minimal — no scope qualifiers beyond the resource name.

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

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

No guidance on when to use this versus coupons_update or how to obtain a coupon ID first. There is also no warning about irreversibility, which matters for a permanently destructive operation.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is clear. The description adds useful operational context—required scope 'read_coupons' and API version '2025-03'—but does not describe error behavior or response characteristics.

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

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

The description is short and front-loaded with the core action, followed by HTTP method, required scope, and API version. There is no filler, though the HTTP path line is slightly redundant with the tool name and schema.

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

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

For a simple single-resource GET tool with full schema coverage and complete annotations, the description provides enough context to call it correctly. The required scope and API version are helpful additions, and no output schema means return values need not be explained.

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 coupon ID, fields filter, and response_format enum. The description adds no parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Get one coupon.' The singular 'one coupon' implicitly distinguishes it from the sibling tiendanube_coupons_list, though it does not explicitly name that sibling.

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

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

There is no guidance on when to use this tool versus tiendanube_coupons_list, nor any exclusions or prerequisites beyond the required scope. The agent must infer that this is for fetching a single coupon by ID.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful operational context beyond annotations: the required read_coupons scope, API version 2025-03, and return envelope. It does not discuss rate limits or pagination nuances, so 4 is appropriate.

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, followed by compact and relevant operational metadata. There is no filler; every line (endpoint, scope, version, return shape) is useful.

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

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

For a filtered-list tool with 18 optional parameters and no output schema, the description supplies the endpoint, required scope, API version, and return envelope. The schema handles filters and annotations handle safety, but the description lacks sibling-routing guidance for get vs list, leaving 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?

All 18 parameters have schema descriptions, so the schema carries the parameter semantics. The description adds no parameter-specific meaning; it only describes the response shape and endpoint. Baseline 3 fits when schema coverage is 100%.

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

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

States a specific verb and resource ('List coupons') and includes the HTTP endpoint, so the core operation is clear. It does not explicitly differentiate from the sibling tiendanube_coupons_get or clarify filtering scope, so it falls 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?

Provides no when-to-use guidance, prerequisites, or alternatives. An agent must infer that this is for browsing/filtering coupons rather than fetching one by ID, and no exclusion points to tiendanube_coupons_get is given.

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

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

The description adds the HTTP method, required write scope, and API version beyond the annotations, which already declare idempotent, non-destructive, and open-world behavior. It does not explain partial-update semantics or how omitted optional fields are treated, which are important behavioral details for a 16-parameter update 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 four short lines, front-loads the purpose, and then gives endpoint, scope, and API version without wasted prose. Each line provides some actionable metadata.

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

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

The definition is adequate because the schema fully documents the many optional fields and annotations cover safety traits. However, for a mutation tool with 16 parameters, it leaves out whether this is a partial update or replacement and how omitted fields behave.

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 16 parameters in detail. The description adds no parameter-level meaning beyond the schema, which is acceptable given full coverage but does not exceed baseline.

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

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

The description clearly states a specific verb and resource: "Update a coupon." It does not explicitly differentiate this tool from siblings such as coupons_create, coupons_get, or coupons_delete, but the update purpose is unambiguous.

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

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

Usage is only implied by the verb "Update"; there is no explicit guidance on when to use this versus coupons_create, coupons_get, or coupons_delete. The required scope line adds useful access context but not selection 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=false, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is largely covered. The description adds genuinely useful non-schema context: the auth scope (write_customers) and API version (2025-03). It does not disclose what happens with a duplicate email, whether send_email_invite triggers side effects, or any response/error 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?

Four short lines, front-loaded with the action, followed by endpoint, scope and version in a scannable order. No filler, though the structured metadata style means it reads as reference data rather than explanatory 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?

For a 10-parameter mutation with nested objects and no output schema, the description covers the endpoint and auth requirement but omits the important operational details: what the response contains, whether the created customer is returned, and how duplicate-email conflicts are handled. Annotations cover the mutability profile, so the gap is moderate rather than severe.

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% across all 10 parameters, including nested addresses and the pass-through additional_fields, so the schema already carries the semantic burden. The description contributes nothing about parameters, which is acceptable given full coverage but yields the baseline 3.

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

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

The description gives a specific verb and resource ("Create a customer"), which is unambiguous and clearly distinct from siblings like tiendanube_customers_update, tiendanube_customers_get, and tiendanube_customers_delete. It stops short of explicitly naming those siblings or stating scope boundaries, so it lands at a solid 4 rather than 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?

Usage is only implied by the verb "Create" and the required scope "write_customers", which is a useful prerequisite. There is no guidance on when to prefer this over other customer tools, no preconditions (e.g., duplicate email handling), and no mention of what to do afterward such as fetching the created record.

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

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

Annotations already mark this as destructive, non-read-only, idempotent, and open-world, so safety is covered structurally. The description adds genuinely useful behavioral context beyond that: the no-orders precondition and the required write_customers scope.

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

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

The description is front-loaded with the action and its key constraint, then provides compact operational context: HTTP method/path, required scope, and API version. Every line is short and useful.

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

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

For a single-parameter delete tool with annotations covering destructive/idempotent behavior and no output schema, the description supplies everything needed to call it correctly: the target resource, the precondition, the scope, and the API version.

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

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

There is one required parameter with 100% schema description coverage, so the schema already defines the ID input. The description shows the path template /customers/{id}, but adds no further meaning about the ID format or behavior.

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

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

States a specific verb and resource (delete a customer) and adds the critical scoping rule that the customer must have no orders. This clearly distinguishes it from sibling tools such as customers_get, customers_update, and customers_create.

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 a clear precondition for use: deletion is only possible if the customer has no orders. It does not name any alternative or fallback behavior for customers with orders, which keeps it short of full 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?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new operational context the annotations do not: the underlying HTTP verb/path, the required OAuth scope read_customers, and the API version — an agent can predict auth failures before calling.

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

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

Four short lines, front-loaded with the purpose, and nothing is padded or repeated. The trailing HTTP/version metadata is templated but still carries usable 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?

Three parameters are all documented, annotations cover safety, and the scope/version lines round out the operational picture, so an agent can call this correctly. Some minor gaps remain around not-found behavior and what a customer object contains, but no output schema was promised.

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 'id', 'fields' and 'response_format' all documented in the schema, so the baseline is 3. The description adds no extra meaning about accepted ID formats or fields syntax beyond what the schema already states.

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?

"Get one customer" states a specific verb and singular resource, which cleanly separates it from the sibling tiendanube_customers_list. It stops short of explicitly naming the list/update/delete siblings as alternatives, so it is clear but not fully differentiated.

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

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

The singular framing implies the use case (fetch a known customer by ID), and the required scope is stated, but there is no explicit when-to-use or when-not guidance and no pointer to tiendanube_customers_list for browsing or tiendanube_customers_update for changes.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely useful context they don't carry: the required read_customers scope and the pinned API version 2025-03. It also discloses the return envelope (count, page, per_page, has_more, next_page, items[]), which no output schema provides here.

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

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

Five short lines, front-loaded with the verb+resource, followed by endpoint, scope, version, and return shape — each line earning its place. The telegraphic style drops connective context (e.g. what 'count' counts against) but wastes no words.

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

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

With no output schema, the description usefully spells out the response envelope including pagination fields, and it names the required OAuth scope for a 13-parameter read tool. It falls short only on pagination guidance for a 10000-record page ceiling and on distinguishing itself from sibling customer tools.

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 13 well-documented parameters, so the schema does the heavy lifting and baseline 3 applies. The description adds nothing about filter semantics — notably it never explains cursor pagination via since_id or how date cursors interact with page — so it neither compensates nor detracts.

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

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

States a specific verb and resource ('List customers') plus the underlying endpoint GET /customers, so the operation is unambiguous. It does not explicitly contrast with siblings such as tiendanube_customers_get or tiendanube_price_tables_customers_list, but the verb/resource pairing is distinct enough to be told apart by name.

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

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

The description gives no when-to-use / when-not-to-use guidance and never references an alternative tool. An agent must infer from the name alone that this is the bulk-retrieval path versus customers_get for a single record; nothing in the text states that routing rule.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context beyond them: the required write_customers scope and the API version. However, it omits the critical behavioral detail that PUT commonly replaces the resource, leaving unclear whether omitted fields are cleared.

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 tightly packed lines with the operation stated first, followed by endpoint, scope, and API version — no filler. It is deliberately telegraphic, though the boilerplate formatting leaves no room for the one sentence of semantics that would matter most.

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 11-parameter mutation with nested objects and no output schema, the definition covers identity, auth, and version but not merge/replace semantics or what the response contains. An agent can invoke it correctly but may not predict the side effects of omitting fields.

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

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

Schema description coverage is 100%, so every one of the 11 parameters is already documented in the schema, including nested addresses and the additional_fields escape hatch. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the work.

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 ("Update a customer") plus the exact HTTP endpoint PUT /customers/{id}, which pins down the operation unambiguously. It does not explicitly differentiate from siblings like tiendanube_customers_create or tiendanube_customers_get, but the name and endpoint make the distinction obvious.

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

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

There is no guidance on when to use this instead of customers_create or customers_get, and no mention of whether this is a full replace (PUT semantics) or a partial update — a decisive detail for an agent deciding which call to make. The only usage-adjacent information is the required scope, which is an authorization prerequisite rather than selection 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 safety (readOnlyHint=false, destructiveHint=false), and the description adds genuinely useful operational context beyond them: the API is flagged as unstable, the required OAuth scope is named, and the HTTP verb/path is disclosed. It does not mention that idempotentHint=false means repeating the call may append a duplicate capability, which is the main behavioral risk here.

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 in the first clause, followed by compact metadata lines (endpoint, scope, version). No filler; the only slight redundancy is repeating 'unstable' twice when once would suffice.

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 annotations covering safety, no output schema, and full schema coverage, the description supplies the remaining operational essentials: endpoint shape, auth scope, and API stability. The one substantive gap is that a 'capability' is never defined in either the description or schema.

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

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

Schema description coverage is 100%, so all four parameters (entity, namespace, slug, capability) are already documented in the schema, including the entity enum. The description only mirrors the path structure and adds nothing about the shape or semantics of the 'capability' payload, which the schema also punts on with 'per the API reference'.

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: adding a capability to a custom field definition, with the exact HTTP endpoint showing the path parameters. It is distinguishable from the sibling capabilities_list/_remove and custom_field_defs_* tools by the verb, though it never names those 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?

Usage is implied by the endpoint and the required scope (read_products/write_products), but there is no explicit statement of when to call this versus custom_field_defs_create/update or when a capability should be attached rather than set at definition creation.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds real context the annotations do not carry: the endpoint is marked unstable, the API version is unstable, and the required scopes are stated, which matters for an agent deciding whether to depend on it.

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 purpose is front-loaded in the first line, followed by endpoint, scope, and version — a tight, scannable shape with no filler. Minor redundancy: instability is signalled twice, in '(unstable API)' and 'API version: unstable'.

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, fully-described 4-parameter lookup with no output schema, the description covers what an agent needs to invoke it correctly. It stops short of describing what a 'capability' looks like in the response, which is the one substantive gap given no output schema exists.

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

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

Schema coverage is 100%, so all four parameters are already documented, including both enums; the baseline of 3 applies. The HTTP path template does clarify that entity/namespace/slug compose the definition identifier, but that is marginal value beyond the schema's own 'Definition namespace/slug' descriptions, and response_format is never discussed.

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

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

States a specific verb and resource: list the capabilities of a custom field definition, identified by entity/namespace/slug. That clearly separates it from the mutating siblings (custom_field_capabilities_add/remove) and from custom_field_defs_get, though it never names an alternative 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?

Usage is only implied — an agent must infer it should call this before adding or removing capabilities, or to introspect what a definition supports. The required OAuth scope (read_products/write_products) is a useful prerequisite, but there is no explicit when-to-use or when-not-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 already flag destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior context: the required OAuth scope (read_products/write_products) and the fact that this hits an unstable API version, both of which affect whether an agent should call it at all.

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

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

Four short, front-loaded lines that each carry information: purpose, endpoint, scope, version. The only waste is the mild redundancy between '(unstable API)' and 'API version: unstable'.

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

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

For a 4-parameter mutation with no output schema and rich annotations, the description supplies the auth requirement, the endpoint shape, and the stability caveat. What it omits is the effect of the removal itself — whether the capability payload is required and whether removal is reversible.

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 entity/namespace/slug are documented and the path template in the description reinforces their roles. The optional `capability` parameter is not mentioned anywhere beyond 'Capability to remove per the API reference', so how it is transmitted (body vs. query) and whether it may be omitted for a bulk removal remains unclear.

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 ('Remove a capability from a custom field definition') and gives the exact HTTP path, so the target object is unambiguous. It never names its siblings (capabilities_list / capabilities_add), so the differentiation is left to the naming convention rather than made explicit in the text.

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

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

There is no explicit 'use this when…' or 'do not use this when…' guidance, nor a pointer to capabilities_add for the inverse operation. Usage is only implied by the verb and by the required scope line, which at least tells the caller what permission is needed.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the bar is lower. The description adds genuinely useful facts beyond the annotations: the required OAuth scope, the unstable API version, and the exact POST path with the {entity} path segment.

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 lines, front-loaded with the action, then operational metadata. Zero filler; the API-version note is slightly redundant since 'unstable' already appears in the first line.

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-param mutation with no output schema, the description plus the rich schema covers scope, endpoint and payload expectations adequately. It does not describe the response body or whether the created definition can be updated later, which would be a modest improvement.

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 required parameters are documented there, including the entity enum and the definition shape hint. The description adds only the {entity} path templating, 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?

Specific verb+resource: 'Create a custom field definition' with the HTTP endpoint spelled out. It implicitly distinguishes itself from tiendanube_custom_fields_create (which sets values) by naming 'definition', though it never explicitly contrasts with that near-identical sibling name.

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 unstable-API caveat and required scope give useful context, but there is no statement of when to use this versus tiendanube_custom_fields_create or the defs_list/get/delete siblings. Usage must be inferred from the name alone.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the operation targets an unstable API version (a real risk for a destructive call), requires a specific OAuth scope, and maps to DELETE /{entity}/custom-fields/{namespace}/{slug}. It does not state whether deletion cascades to stored values or what happens when the definition is not found.

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

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

The description is front-loaded and four short lines long, with no filler. It loses a point because "(unstable API)" in the first line is repeated verbatim as "API version: unstable" in the last line, which is redundant within such a compact 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?

This is a three-parameter destructive tool with no output schema, and the definition covers the endpoint, the required scope, and the instability warning, while the annotations carry the destructive/idempotent flags. It falls short of complete because it does not say whether the deletion is permanent, whether attached field values are removed, or what a successful response returns.

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 entity enum is fully documented in the schema, so the schema already carries the burden of explaining parameters. The path template /{entity}/custom-fields/{namespace}/{slug} tells the agent how the three parameters are bound into the request, but it adds no format, validation, or lookup details. The baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: "Delete a custom field definition." This is distinguishable from the sibling tools `tiendanube_custom_fields_delete`, which deletes field values, and `tiendanube_custom_field_defs_create/get/list`, which manage definitions. An agent can select the correct sibling 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 states the required scope (read_products/write_products) and contains a useful warning that the API is unstable, but it does not say when to prefer this tool over `tiendanube_custom_fields_delete`, nor does it give any preconditions such as whether the definition must be unused or empty before deletion. Usage is therefore implied by the name rather than guided.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, yet the description still adds real operational context: the API is flagged as unstable, the exact HTTP route is given, and the required scope (read_products/write_products) is named. It stops short of describing error behavior or response shape for a read 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?

Three short, front-loaded lines: one for purpose, one for the endpoint, one for scope and API version. Every line carries actionable information and nothing is repeated or padded.

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 read tool with full schema coverage and an explicit annotation profile, the definition covers what an agent needs to address and authorize the call. The only gap is that it does not hint at what the returned definition contains, which matters somewhat since there is no output schema.

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

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

Schema coverage is 100%, so entity, slug, namespace, fields, and response_format are all documented in the schema itself. The description's path template reinforces that namespace and slug are path-level identifiers, but adds nothing about the fields or response_format options, 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 (Get) plus a precise resource (a custom field definition) and the exact key pair (namespace/slug) that addresses it, which cleanly separates it from the sibling list/delete/build tools of the same family.

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 the precondition for calling (you must have namespace and slug) and the required scope, but never states when to prefer this over tiendanube_custom_field_defs_list or how it differs from tiendanube_custom_fields_get. Usage is implied by the identifier-based addressing 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?

Beyond the annotations (which already say readOnly/idempotent, non-destructive), the description contributes real operational context: the required OAuth scope (read_products/write_products), that the API surface is unstable, the HTTP route, and the response envelope with pagination fields. Since there is no output schema, the return-shape note is genuinely useful. Only the 'unstable' label is left unexplored in terms of what could break.

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

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

Five short lines, purpose first, then route, scope, version and return shape. Nothing is repeated and every line carries a distinct fact an agent would otherwise have to discover.

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 naming the response fields, and with 100% schema coverage the five parameters need no further explanation. The remaining gap is conceptual: it never says how a 'definition' relates to the values returned by tiendanube_custom_fields_list, which would help an agent pick correctly.

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

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

Schema description coverage is 100%, so page, per_page, entity, fields and response_format are all documented in the schema itself. The description only echoes the path parameter via /{entity}/custom-fields and adds no format, default, or constraint detail of its own. 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?

Specific verb+resource: 'List custom field definitions', which clearly separates it from sibling mutation tools (custom_field_defs_create/get/delete) and from tiendanube_custom_fields_list, which deals with field values rather than definitions. It does not explicitly name those siblings, so it stops 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?

No indication of when to use this versus tiendanube_custom_fields_list, tiendanube_custom_field_defs_get, or tiendanube_custom_fields_get_by_entity_id. The only context offered is an API-stability caveat, not usage guidance or prerequisites.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds real value the annotations cannot: the exact HTTP method/path, per-entity OAuth scope requirements, and the pinned API version. It stops short of disclosing behavior on duplicate field names or what happens to existing values, so it is strong rather than 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?

Four tight lines: purpose first, then endpoint, scopes, and version. Every line carries operational information, with only the API-version line being near-boilerplate across sibling tools.

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

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

For a 7-parameter mutation with nested objects (values array, additional_fields) and no output schema, the definition covers auth and endpoint but says nothing about uniqueness constraints, validation rules per value_type, or what identifier is returned. Adequate to invoke, insufficient to predict 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 100%, so every parameter including the entity and value_type enums is already documented in the schema. The description's scope table loosely maps entities to permission scopes, adding marginal meaning but no format, default, or interaction details beyond the schema baseline.

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 ('Define a custom field for an entity') plus the concrete HTTP path POST /{entity}/custom-fields, so the operation is unambiguous. It does not, however, differentiate itself from the close sibling tiendanube_custom_field_defs_create, leaving the agent to guess which of the two overlapping 'create' tools to use.

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

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

No explicit when-to-use vs. when-not guidance and no mention of the custom_field_defs / set_values siblings. Usage is only implied by the endpoint path and the required-scope table, which tells the agent what permissions are needed but not when this tool is the right choice.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the deletion cascades to stored values, and it lists the exact OAuth scopes required per entity type, which the agent needs to know before attempting the call.

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

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

The destructive effect is stated first, followed by compact endpoint, scope, and version lines. No filler sentences, though the HTTP path line is largely boilerplate for an agent.

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, annotation-covered operation with full schema coverage, the description covers effect, cascade, and permissions adequately. It still leaves open whether deletion is recoverable and how this differs from the custom_field_defs_delete sibling, which matters for correct selection.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes further by mapping which read/write scope pair applies to each entity value (categories, products, customers, orders), giving semantics the enum list in the schema does not convey. It adds nothing for custom_field_id beyond the schema.

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

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

States a specific verb and resource ('Delete a custom field definition') and adds the crucial cascade detail that its values go with it. It does not, however, distinguish itself from the sibling tiendanube_custom_field_defs_delete, which an agent could easily confuse with this tool.

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

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

There is no guidance on when to use this versus tiendanube_custom_field_defs_delete or custom_fields_set_values; the description is purely descriptive plus endpoint metadata. The agent must infer the distinction from tool names 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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds required scope information and the API version, but does not describe errors, rate limits, or response behavior beyond what the annotations provide.

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

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

The description is compact and front-loaded: the core action appears first, followed by the endpoint, scopes, and API version. Every line carries relevant operational information and there is no redundant 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?

The description covers the endpoint, required scopes, and API version, which is good for an authenticated GET tool. However, there is no output schema, and the description does not explain what the returned custom field definition contains or how the fields parameter affects the response, leaving a notable 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 four parameters are already documented in the input schema. The description adds the endpoint path and maps entity types to required scopes, which is mildly helpful, but it does not add syntax or meaning beyond what the schema already provides for fields and response_format.

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

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

The description clearly states a specific verb and resource: "Get one custom field definition," and reinforces it with the HTTP endpoint. It does not differentiate this tool from close siblings such as tiendanube_custom_field_defs_get or tiendanube_custom_fields_get, leaving some ambiguity about which getter to choose.

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

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

It provides useful access context by listing the required OAuth scopes per entity, which implicitly tells the agent what permissions are needed. However, it does not say when to use this tool versus sibling retrieval tools or describe any exclusions or alternatives.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's job is the extra context it does provide: required OAuth scopes broken out per entity family and the API version (2025-03). It does not mention rate limits or response/pagination behavior, but the auth requirement is a real addition 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?

Front-loaded with the purpose, then the HTTP route, then scope requirements and API version as separate lines. Four lines with no filler; the scope line is dense but each element is actionable.

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 4-parameter lookup with full schema coverage and complete annotations, the description supplies exactly the missing operational context: route, per-entity scopes, and API version. No output schema exists, but a keyed lookup's result shape is implied by the purpose statement.

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 (entity enum, entity_id, fields, response_format) is already documented in the schema. The description adds no syntax or format detail beyond echoing example entity values, 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 and resource: 'Get the custom field values of one entity instance', with a concrete example (one product). Combined with the endpoint path it clearly separates this from definition-oriented siblings, 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?

The per-entity scope list implies which entity types are readable and under what permissions, but there is no explicit 'use this when…' guidance or a named alternative such as custom_fields_list or custom_field_defs_get. The agent must infer the choice from the name and the endpoint line.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful context beyond those: required OAuth scopes per entity, API version, and the return shape (count, page, per_page, has_more, next_page, items). It does not explain pagination behavior or rate limits, but given the annotation coverage this is a solid addition.

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 front-loads the purpose and then adds scopes, version, and return shape in a compact block. Some lines (HTTP endpoint, API version) are technical metadata that may not help an agent decide how to call it, but overall it is efficient and well-structured.

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

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

Given the rich schema and annotations, the description covers purpose, auth scopes, and return shape. The main gap is sibling disambiguation—it never explains how this differs from tiendanube_custom_field_defs_list or tiendanube_custom_fields_get_by_entity_id—so an agent may still hesitate. This is adequate but incomplete 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—including enums for entity and response_format—are fully documented in the schema. The description only implicitly references the entity parameter and adds no extra meaning for fields, page, per_page, or response_format. Baseline 3 is appropriate when the schema carries the 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?

The description clearly states a specific verb and resource: 'List custom field definitions of an entity.' However, it does not differentiate from sibling tools like tiendanube_custom_field_defs_list, which sounds nearly identical, so an agent may not know which one to choose.

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

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

There is no guidance on when to use this tool versus alternatives such as tiendanube_custom_field_defs_list or tiendanube_custom_fields_get_by_entity_id. The required scopes are helpful for authentication but do not explain selection criteria.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower. The description adds genuinely useful behavior context: the per-entity OAuth scope required (read_products for categories/products/products-variants, read_customers, read_orders) and the pinned API version 2025-03, which tells the agent an authorization failure is likely if the wrong scope is missing.

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

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

Four short, front-loaded lines: purpose first, then route, then scope, then response envelope. Nothing is repeated from the schema, though the raw HTTP path is somewhat incidental for an agent that already has the tool bound.

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, no output schema and no nested objects, the description does the needed work by disclosing the return envelope {count, page, per_page, has_more, next_page, items[]} and the scope prerequisites. It stops short of saying what an 'owner' item actually contains, but the pagination and auth picture is complete enough 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 description coverage is 100%, so the schema already documents entity, custom_field_id, page, per_page, fields and response_format. The description adds only the entity-to-scope mapping, not format, allowed values or interpretation of the ID types, 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 -- list the entity instances that hold a value for a given custom field -- and backs it with the concrete HTTP route GET /{entity}/custom-fields/{custom_field_id}/owners. It is distinguishable from custom_fields_list (lists the field definitions) and custom_fields_set_values, though the description never explicitly contrasts them.

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 only implied: an agent can infer it should call this when it needs to know which products/customers/orders actually carry a value for a field. There is no explicit when-to-use or when-not, and no sibling alternatives are named (e.g. custom_fields_get_by_entity_id for the reverse lookup).

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 write, idempotent, non-destructive, open-world behavior. The description adds genuinely useful context beyond that — per-entity scope requirements, the exact endpoint, and the API version — but leaves the key behavioral question unanswered: whether the values payload replaces all existing values or merges/patches them.

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

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

Four short lines, zero filler, with the core action front-loaded and the endpoint/scope/version details as scannable follow-ups. Nothing is repeated or padded.

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 definition covers auth scope and endpoint but omits overwrite/merge semantics and any indication of what the call returns. Adequate to invoke, thin on consequences of invoking.

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 entity, entity_id and values with an example payload. The description's only addition is mapping entity/entity_id onto the URL template, which is marginal; no extra semantics about payload shape or id limits.

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: 'Set custom field values on one entity instance', reinforced by the concrete HTTP path PUT /{entity}/{entity_id}/custom-fields/values. It is distinguishable from the sibling definition tools (custom_fields_create/update/delete), though it never explicitly contrasts itself with tiendanube_custom_fields_update.

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 supplies prerequisites (required OAuth scopes per entity) but no when-to-use guidance, no exclusions, and no pointer to alternatives such as tiendanube_custom_fields_update or the corresponding *_get_by_entity_id read tool. An agent must infer selection from the name alone.

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

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

Beyond the safety markers in annotations, the description adds crucial technical context: the specific HTTP method used (PUT), the API version (2025-03), and the required scope structure. These details are vital behavioral constraints that influence how the agent must formulate the request.

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 definition is highly condensed and efficient, placing the primary function in the opening line. The subsequent technical data follows a logical progression (Endpoint -> Scope -> Version) without unnecessary filler.

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

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

Given the complexity of an API integration tool, the description is quite complete. It satisfies the need to define the operation's boundaries (API version, required permissions, URL structure) which are essential for correct invocation, even if the parameter details are in the schema.

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

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

With schema description coverage at 100%, the description provides little semantic value over the structured input. It defines the tool's existence but does not elaborate on the meaning or acceptable values of the parameters themselves.

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

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

The description clearly identifies the action ('Update') and the resource being acted upon ('custom field definition'). The inclusion of the HTTP method and path (PUT /{entity}/custom-fields/{custom_field_id}) provides even greater specificity, distinguishing it immediately from related list or create actions.

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

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

While it does not compare usage against sibling tools, it explicitly defines the required scopes (e.g., read_products/write_products) necessary for execution. This provides a clear operational guideline on the tool's applicability within the system context, ensuring the agent knows the permissions needed to use it.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, so the description is not obligated to restate mutability. It adds genuinely useful context beyond that: the API surface is flagged 'unstable' (a real risk of breaking changes) and the required OAuth scope plus API version are given. It stops short of noting whether retries are safe given non-idempotency or what happens on duplicate entries.

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

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

Four short lines, front-loaded with the action and the instability caveat, followed by machine-actionable metadata. Every line carries information an agent needs; there is no filler.

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

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

With only 3 required params, full schema coverage and annotations present, the basics are covered. But the 'entry' payload is left entirely unspecified (anyOf object/array with free-form properties, deferred to an external API reference), so an agent cannot construct a valid call from this definition alone, and with no output schema the description also omits any hint of the created entry's identifier.

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 namespace, slug and entry are already documented in the schema, setting the baseline at 3. The description confirms the path mapping (/custom-objects/{namespace}/{slug}/entries) but adds no insight into the shape of 'entry', which is the genuinely ambiguous parameter — it defers to 'the API reference'.

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

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

States a specific verb and resource ('Create an entry in a custom object') and scopes it to a namespace/slug pair, which cleanly separates it from the sibling update/get/delete/list entry tools and from custom_objects_create. An agent knows exactly what is produced 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?

Prerequisites are supplied (required scope read_products/write_products, API version, endpoint), which helps an agent decide whether the call is permitted. However, there is no guidance on when to use this versus tiendanube_custom_objects_create (define the object) or how it relates to custom_fields_set_values, so selection between similar write paths 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 already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely non-derivable context: the required OAuth scope (read_products/write_products) and the fact that this is an unstable API surface, which affects whether an agent should rely on it.

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

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

Four short, front-loaded lines with the verb+resource first, then endpoint, scope, and stability. Nothing is padded, though the HTTP line partially duplicates information already carried by the schema.

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

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

For a destructive delete with no output schema, the description covers the essentials: what is removed, which credentials are needed, and the endpoint. It omits post-delete effects (cascading, error on missing entry), but annotations already flag destructiveness and idempotency.

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 all three parameters are described in the schema, so the baseline is 3. The HTTP path template confirms namespace/slug/entrySlug are all path segments and shows their nesting order, but adds no format or validation detail beyond the schema.

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

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

The description gives a specific verb and resource ("Delete a custom object entry") plus the exact HTTP route, which clearly separates it from the sibling entries_get/list/update/create tools. It does not name a sibling explicitly, but the verb+resource 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?

There is no guidance on when to use this versus alternatives, no precondition that the entry must exist, and no warning about irreversibility or confirmation. The only contextual cues are the scope requirement and the "unstable API" tag, which are constraints rather than usage guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds non-obvious context beyond them: the API is flagged as unstable, the required OAuth scope is given, and the API version is named. That is real value on top of the structured hints, though return behavior is not described.

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

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

Four short lines: purpose, endpoint, scope, version. Nothing is redundant and the operation is front-loaded, with the 'unstable' caveat placed immediately next to the purpose.

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-resource GET there is no output schema, and the description says nothing about what an entry returns or how the fields/response_format options shape the payload. Parameters and safety are adequately covered, but the return-side context is missing.

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

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

Schema description coverage is 100%, so the five parameters including the fields selector and response_format enum are already fully documented. The description only echoes the three required slugs via the path template, adding no syntax or format detail beyond the schema.

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

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

States a specific verb and resource ('Get one custom object entry') and reinforces it with the exact HTTP path template. The singular 'one entry' implicitly distinguishes it from tiendanube_custom_object_entries_list, 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?

Usage is only implied: the path template shows you must supply namespace, slug and entrySlug to fetch a single entry, and the required scope is stated. There is no explicit guidance on when to use this versus the list or other entry tools.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the marginal value here is the 'unstable API' warning, the required scope, and the explicit response envelope. That unstable-version caveat is behavioral context the annotations cannot express.

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 compact labeled lines — purpose, HTTP route, scope, return shape. Front-loaded with the verb and resource, zero filler.

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

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

With no output schema, the description steps in with the return shape {count, page, per_page, total?, has_more, next_page?, items[]}, plus scope and stability. What's missing is any note on pagination behavior or the fields projection, though the schema covers those.

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 page, per_page, slug, namespace, fields and response_format are already documented. The description adds no syntax or constraint detail 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 ('List entries of a custom object') and nails the endpoint. Against sibling tools like tiendanube_custom_object_entries_get/create/delete, the list semantics are unambiguous from the first three words.

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 a prerequisite (required scope read_products/write_products) which genuinely helps routing, but it never says when to use this versus entries_get for a single entry or custom_objects_list for the parent definitions. Usage is implied by the name rather than stated.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the required scope (read_products/write_products) and flags instability, but is silent on whether PUT replaces the whole entry or merges fields, and on what happens to unspecified existing 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?

Four short lines, front-loaded with the action, then route, scope and version. No filler, though the HTTP line is largely redundant with the tool name and schema.

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

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

For a straightforward mutation tool with full schema coverage and rich annotations, the description covers the essentials: operation, route, scope and stability caveat. The only missing piece is the structure of the free-form 'entry' object, which the schema deliberately leaves open.

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 four parameters (namespace, slug, entrySlug, entry) are documented in the schema; baseline 3 applies. The description only restates the three path parameters via the HTTP route and adds nothing about the shape or semantics of the 'entry' payload.

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 ('Update a custom object entry'), which cleanly separates it from the sibling create/get/list/delete entry tools. The 'unstable API' qualifier and HTTP route add precision, though nothing explicitly contrasts it with the other entry operations.

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

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

Usage is only implied by the verb 'update' — the agent can infer this modifies an existing entry rather than creating one. There is no explicit when-to-use, no prerequisites, and no pointers to alternatives such as the create or get entry tools; the only real guidance is the 'unstable API' warning.

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

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

Annotations already declare this is a non-readonly, open-world, non-idempotent, non-destructive write. The description adds real context beyond them: the endpoint is explicitly flagged as an unstable API version, and the required OAuth scope (read_products/write_products) is stated, which is exactly the kind of operational prerequisite an agent needs. It stops short of describing what happens on name collisions or whether the definition can be modified afterward.

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 lines, front-loaded with the purpose, then endpoint, scope, and version. No filler, though the terse format leaves little room for the one thing an agent would most need (definition shape).

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 whose single required argument is an unconstrained free-form object (anyOf object/array with no properties), the description gives no indication of what the definition must contain, which is the hardest part of calling it correctly. The scope and API-version warnings help, but the gap on the payload shape keeps this at minimum-viable.

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 coverage is 100%, so the schema itself carries the documentation burden. The description adds nothing about the shape or required fields of the `definition` object, deferring entirely to 'per the API reference'. Baseline 3 is appropriate 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+resource (create a custom object definition), which is distinguishable from the sibling entries endpoints (tiendanube_custom_object_entries_create) and the list/get/update/delete custom_objects siblings. It does not explicitly name those siblings, so differentiation is inferred from the resource name rather than spelled out.

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

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

No guidance on when to use this versus creating custom object entries or the custom_field_defs family, and no prerequisites beyond the required API scope. The only usage-adjacent signal is the '(unstable API)' warning, which doesn't route the agent between alternatives.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context: the API is unstable (a real risk signal for production use) and the required OAuth scope. It still doesn't say whether deletion cascades to existing custom object entries or is irreversible.

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

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

Four short lines, front-loaded with the action, then the endpoint, scope, and API version. Nothing is wasted or repeated.

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 mutation with no output schema, the description covers endpoint, scope and stability but omits cascade behavior, permanence, and error cases. Annotations partially compensate for the destructive framing, leaving a moderate 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% and both parameters carry descriptions, so the schema does the heavy lifting. The description only reinforces parameter placement via the route template /custom-objects/{namespace}/{slug}; it adds no format or constraint detail beyond that.

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