Cakto

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

The description adds useful behavior beyond the annotations: config header yields a permanent connection, while passing a token yields a session-only login, and no args returns a link. It does not fully spell out side effects or success/failure return values, but annotations already cover idempotency and non-destructiveness.

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

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

The description is dense and front-loaded, with no fluff, but the long single sentence with parenthetical clauses and multiple alternatives could be structured into clearer separate instructions. Still, every part adds necessary 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 one-parameter auth tool with no output schema, it covers the no-arg return (the link), the token-paste path, and the persistent-config alternative. It doesn't state the response on a token success/failure, but the invocation guidance is sufficient for an agent 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?

With 0% schema coverage, the description carries the full burden for the optional `token` parameter. It explains that token is a JWT/access token pasted by the user and how to pass it, compensating well for the bare schema.

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

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

The description clearly identifies the tool as MCP.AI authentication for IDE agents, with a concrete browser-login + access-token flow and two invocation paths (no args for a link, token for login). This specific verb+resource is unambiguous and easily distinguished from the unrelated calculo_* sibling tools.

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

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

It explicitly differentiates the persistent config-header approach ('best... permanent, non-expiring') from the session-only paste/login path, and states exactly when to call with no args versus with { token }. This gives the agent clear selection criteria for both setup and invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds useful context: it is for analysis/CRM, get returns purchase history, and customer_ids enables batched execution. However, it does not explain behavior when called without customer_id despite schema marking all parameters optional.

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 uses a short action breakdown with a clear flattened-action marker. Some redundancy/confusion remains because the list action is documented even though the tool is flattened to get, but the overall structure is efficient.

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

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

For the get use case, the description provides the core requirements: customer_id, return content (profile + purchase history), and bulk support. Missing pieces include the meaning of account, the behavior with no parameters, and more detail on response shape—especially since 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 0%, so the description carries the burden. It gives meaning to search and page (list filters), customer_id (single get), and customer_ids (bulk). The account parameter is completely unexplained, and the relationship between customer_id and customer_ids is only partially described.

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

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

States a specific resource (Cakto customers) and a definite action: get returns 'perfil de UM cliente + histórico de compras' requiring customer_id. The inclusion of a list action in the same description creates some ambiguity with sibling cakto_customers_list, but the flattened-action note clarifies the actual mode is get.

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

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

Implies when to use get (single customer profile/history with customer_id) and when to use bulk (customer_ids), but does not explicitly steer the agent to cakto_customers_list for list queries. The presence of list documentation inside a get tool further blurs the usage boundary.

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 by structure rather than description. The description adds value by noting bulk execution via customer_ids and identifying the supported filters (search, page). It aligns with the annotations (read-only, non-destructive) and adds the batching behavior, but does not describe the return format or pagination semantics, so it is adequate but not rich.

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

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

The description is compact and front-loads the core purpose effectively. Some structure is wasted documenting the 'get' action that is not this tool (flattened to list), which is redundant given the separate get sibling. The '[Flattened action: list]' note helps disambiguate but adds a maintenance burden that could be avoided by simply documenting list-only behavior.

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

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

For a 5-parameter tool with 0% schema coverage and no output schema, the description should clarify every parameter and the return behavior. It covers search, page, customer_id, and customer_ids in intent but leaves 'account' undocumented and does not describe what the list response contains. The get/list conflation further undermines completeness. Adequate for a read-only tool whose safety is carried by annotations, but gaps remain.

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

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

With 0% schema description coverage, the description must fully compensate, and it partially does: it explains search and page as list filters, customer_id as the get selector, and customer_ids as the bulk parameter. However, the 'account' parameter is left entirely unexplained, and the dual list/get framing conflates which parameters apply to this flattened tool. The description covers most parameters but not all.

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 opening line 'Leitura de clientes na Cakto (para análise/CRM)' states a clear verb (read) and resource (Cakto customers) with a stated use-case (analysis/CRM), which distinguishes purpose well. However, the description documents both 'list' and 'get' actions while declaring '[Flattened action: list]', so the dual-action framing somewhat muddies what this specific tool actually does.

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

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

The description implies a list-vs-get distinction ('get requer customer_id') and notes bulk support via customer_ids, but never explicitly routes to the natural sibling cakto_customers_get. Given that a dedicated single-customer sibling exists, the in-description 'get' instructions are borderline misleading — an agent might try to fetch a single profile through this tool instead of the sibling. No explicit when-to-use vs alternatives guidance is provided.

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

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value beyond those by specifying the install-scoped nature of the listing and the returned fields. It does not mention pagination or authentication, but the safety profile is already covered by annotations.

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

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

The description is a single efficient sentence that front-loads the verb and resource, then packs in scope and returned fields. There is no filler or redundant 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 read-only list tool with strong annotations, the description covers purpose, scope, and returned fields well. However, it completely omits the semantics of the optional 'account' parameter and says nothing about defaults or pagination, leaving a meaningful gap for non-default calls.

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

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

The schema has one optional 'account' parameter with no description, and the tool description never mentions it. With 0% schema description coverage, the agent has no way to know whether 'account' filters the list, selects a context, or has specific format requirements.

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 ('Lista'), a distinct resource ('contas Cakto/apps do painel'), an explicit scope ('vinculadas a este install'), and the fields returned (id, label e apelido). This clearly differentiates it from sibling list tools like cakto_customers_list or cakto_offers_list.

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

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

The phrase 'vinculadas a este install' gives useful context for when this tool is relevant, but there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives. For a simple list operation, the usage is implied rather than fully 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?

The description adds useful behavioral context beyond annotations: it requires the 'write offers' scope and notes the product must already exist. It does not describe error behavior, side effects, or return values, but it does not contradict the annotations.

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

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

Two focused, front-loaded sentences. The first states the core action and resource; the second provides purpose and required scope. 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?

Despite a complex 15-parameter schema and no output schema, the description only covers purpose and scope. An agent cannot reliably construct a valid request because required fields, parameter semantics, and behavioral outcomes are not 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 0% and there are 15 parameters, with only names, types, and enums provided. The description gives no parameter-level guidance, failing to compensate for the schema's lack of descriptions.

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

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

The description states a specific verb and resource: 'Cria uma oferta (preço alternativo) para um produto existente na Cakto.' It clearly differentiates the create action from sibling list/get/update tools by emphasizing creation of an alternative-price offer as a prerequisite for order bumps.

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

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

It gives clear context for when to use the tool: 'É o passo necessário para ter o que oferecer num order bump com preço diferente do principal.' However, it does not explicitly mention when not to use it or compare it with alternatives such as cakto_offers_update.

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, and the description aligns by saying 'Leitura de ofertas'. It adds useful behavioral context beyond annotations: the concept of an offer as a price unit and order-bump target, plus bulk execution support.

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

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

The description is well organized: a one-line purpose, a brief domain concept explanation, and bulleted actions. It is not overly verbose, and every part adds context, though the list-action section is somewhat redundant given the flattened-get framing and sibling list 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?

For a read tool with 10 optional-looking schema parameters and no output schema, the description covers the main use cases and bulk behavior. It leaves gaps: the relationship between get/list is muddled, the account parameter is undocumented, and the response shape is not described.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It maps most parameters to their roles: product, status, type, search, ordering, limit, and page for filtering; offer_id for single detail; offer_ids for bulk. It omits the 'account' parameter and doesn't explain enum values, but it compensates reasonably for the schema's lack of descriptions.

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

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

The description states the tool reads Cakto offers and clearly identifies the get action as retrieving details of ONE offer requiring offer_id, with bulk support via offer_ids. It distinguishes single-offer retrieval from listing, though it also documents the list action and there is a sibling cakto_offers_list, which introduces some ambiguity.

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

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

The description implies the get path should be used when offer_id is available and says offer_ids are accepted for batch execution, giving some contextual guidance. However, it never explicitly says 'use cakto_offers_list for listing/searching' and actually lists list-related filters even though the tool is flattened to the get action.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds the bulk execution capability (accepts offer_ids for batched execution) and provides domain context about offers being the price unit targeted by order bumps. However, it does not disclose pagination behavior, default ordering, or any rate limitations. The note 'Flattened action: list' clarifies behavior but is already implied by the tool name. Overall, it adds some context beyond annotations without contradicting them.

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

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

The description is moderately concise but includes a domain lecture (what an offer is, how bumps point to offers) that is tangential to how to call the list tool. The purpose is front-loaded, but the 'Ações' section could be streamlined. The flattened action note and bulk support note are useful but add to the length. Overall, it is somewhat verbose for a simple list endpoint, but not excessively so.

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

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

With no output schema and 10 parameters, the description should provide richer guidance. It lists the filters but does not explain response format, pagination details (e.g., how many results per page), or default ordering. The bulk support is mentioned but not how offer_ids interacts with other filters. The domain explanation is helpful but does not compensate for missing operational details. An agent would likely need to experiment or consult other documentation to use the tool effectively.

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

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

Schema description coverage is 0%, so the description carries the full burden. It lists filter names (product, status, type, search, ordering, limit, page) but does not explain their semantics beyond the names. It adds value for offer_ids by mentioning bulk support, but other parameters like 'status' and 'type' are only covered by enums in the schema, not the meaning or expected usage. Pagination parameters (limit, page) are not described in terms of defaults or max values. No parameter gets a full explanation, leaving the agent to infer.

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 'Leitura de ofertas na Cakto' (reading offers), which clearly states a specific verb and resource. It also explains the domain concept of an offer, and the flattened action note clarifies that this tool performs the 'list' action, distinguishing it from the sibling 'get' action. However, the 'Ações: list, get' section initially presents both actions, which could confuse an agent about whether this tool handles both, though the flattened action disambiguation mitigates that.

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

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

The description does not explicitly state when to use this tool versus alternatives like cakto_offers_get. It mentions that 'get' requires offer_id, but does not say 'use this tool for listing multiple offers, use get for a single offer'. The guidance is implied by the existence of separate sibling tools, but there is no explicit exclusion or routing directive. The bulk support note hints at batched use cases but does not clarify when batch vs. single filtering is appropriate.

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

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

Annotations already indicate a non-read-only, non-idempotent mutation. The description adds meaningful behavioral context beyond annotations: partial update semantics, status='disabled' as a non-deleting deactivation path, required OAuth scope, and bulk execution support.

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

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

Three tight, front-loaded sentences. Every sentence earns its place: purpose/partial mode, status guidance, scope requirement, and bulk support. No filler or repetition.

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

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

Given the high parameter count, zero schema descriptions, and no output schema, the description covers only a small portion of what an agent needs for correct invocation. It omits semantics for most fields, return behavior, and any caveats around bulk or destructive state changes.

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

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

Schema description coverage is 0%, and the description only adds semantic value for status and offer_ids. With 16 parameters, most fields like interval, trial_days, max_retries, and recurrence_period remain unexplained, so the description only partially compensates for the schema gap.

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

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

The description states a specific verb ('Atualiza'), a specific resource ('uma oferta existente na Cakto'), and key behavior (partial update, bulk support). It clearly distinguishes from sibling tools like cakto_offers_create by targeting existing offers.

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

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

The description gives clear context for usage: partial updates, how to disable via status='disabled', required scope, and bulk support. It does not explicitly name sibling alternatives or exclusion cases, but the existing-offer framing makes the intended use clear.

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

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

Annotations already mark it as a mutating, non-idempotent operation. The description adds useful behavioral context beyond that: it requires the 'write products' scope, supports bulk execution via product_ids and offer_ids, and clarifies the semantical attachment of an offer to a product checkout. No contradiction with annotations.

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

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

Three sentences, each earning its place: the core semantics, the prerequisite/scope, and bulk support. The main concept is front-loaded and there is no filler or repetition.

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

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

The description covers the essential required-parameter semantics, the lookup prerequisite, scope, and bulk behavior, which is enough to make a basic valid call. However, with 11 parameters and no output schema, it omits the meaning of all optional fields and says nothing about response/return behavior or duplicate/bulk error handling, leaving meaningful gaps.

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

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

With 0% schema description coverage, the description carries a heavy burden and does explain the two required parameters plus the bulk array variants product_ids and offer_ids. However, it leaves the optional display/positioning parameters (cta, title, position, show_image, description, reference_price, account) completely unexplained, so compensation is only partial.

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 ('Cria um order bump') and precisely defines the roles of product_id and offer_id: the checkout where the bump appears vs. the complementary offer being sold. This clearly differentiates the create action from sibling tools like cakto_order_bumps_get, cakto_order_bumps_list, and cakto_order_bumps_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 gives concrete usage guidance: use cakto_offers (action=list) to discover the offer_id, and it states the required scope 'write products'. It does not explicitly enumerate when not to use this tool, but the create-vs-read/update sibling split makes the intended use clear enough.

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 establish read-only, idempotent, non-destructive behavior, so the description only needs to add nuance. It adds the distinction between single and bulk ID execution, which is useful beyond the schema, and nothing contradicts the annotations.

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

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

The description is front-loaded with the core purpose and uses a compact action list; the bulk-support note adds useful information. The cryptic '[Flattened action: get]' line adds noise but does not seriously undermine scannability.

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 tool with no output schema, it fails to describe the response format or content beyond 'detalhe' and 'lista'. It also omits account semantics and the relationship to the sibling list tool, leaving an agent to infer several call conventions.

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

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

Schema description coverage is 0%, so the description must compensate. It maps product_id and order_bump_id to actions and explains the plural bulk variants, but it leaves 'account' unexplained and does not clarify precedence or combination rules when singular and plural parameters are supplied together.

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 that this tool reads order bumps and distinguishes list versus get behavior. However, it does not explicitly differentiate itself from the sibling cakto_order_bumps_list, and the name 'get' conflicts slightly with also describing list behavior.

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

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

It provides concrete within-tool guidance: list requires product_id, get requires order_bump_id, and bulk IDs are accepted for batch execution. It does not say when to prefer this tool over cakto_order_bumps_list or the create/update siblings, and the '[Flattened action: get]' note is ambiguous.

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 by structured data. The description adds the action semantics and bulk-execution behavior, which goes beyond annotations and is genuinely useful. However, it doesn't disclose how batched results are returned or what the response format is, so the added value is modest given annotations already carry the burden.

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 logically organized: purpose statement first, then actions, then bulk support. Every sentence earns its place, and the action list is easy to scan. Minor artifact — '[Flattened action: list]' — reads like an internal note rather than user-facing guidance, slightly detracting from structure.

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

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

For a read-only tool with five undocumented parameters, no output schema, and a sibling doing an overlapping action, the description covers list/get and bulk but leaves two gaps: the unexplained 'account' parameter and the unresolved relationship to cakto_order_bumps_get. Since annotations handle the safety profile and there's no output schema to describe, the missing pieces are the sibling differentiation and account semantics — both material enough to keep this from being complete.

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

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

Schema description coverage is 0%, so the description carries the full burden of documenting parameters. It explains product_id (required for list), order_bump_id (required for get), and the bulk arrays product_ids/order_bump_ids. Critically, the 'account' parameter is never mentioned at all, leaving one of five parameters undocumented in both the schema and the description. Partial compensation, but a clear gap.

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

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

The description clearly states the resource (order bumps — 'ofertas complementares exibidas no checkout') and the verb (reading/listing). It defines what an order bump is, which is helpful context. It distinguishes two actions (list vs get) even though the tool name says 'list', which is a slight mismatch but explicitly documented. A small deduction because the purpose is somewhat muddled by the name implying only list while the tool also handles get.

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

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

The description explains when each action applies: list requires product_id, get requires order_bump_id, and bulk accepts arrays. However, it never differentiates this tool from its sibling cakto_order_bumps_get — which appears to do the same 'detalhe de UM order bump' action. No exclusions or 'when not to use' guidance is given, leaving an agent to guess why both tools exist.

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, the description discloses important behavior: position 1 appears first, IDs not belonging to the product are ignored, bulk execution is supported, and the 'write products' scope is required. It does not detail the output or what happens to omitted order bumps, but it provides solid behavioral context.

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

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

The description is compact, front-loads the core operation, and every sentence adds value: main behavior, ordering rule, invalid-ID handling, scope requirement, and bulk support. No filler or redundant restatement of the tool name.

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

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

The definition is complete enough for the agent to call the tool correctly: it explains the required payload, ordering semantics, tolerated invalid IDs, required permission scope, and bulk option. Missing output details and account parameter semantics are minor given the absence of an output schema.

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

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

With 0% schema description coverage, the description compensates well: it explains the items structure ({order_bump_id, position}), the meaning of position, the product_id/product_ids distinction, and the bulk behavior. The optional 'account' parameter is not explained, preventing a 5.

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

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

The description starts with a specific verb+resource ('Reordena os order bumps de um produto'), states the complete-list semantics, and clarifies positional ordering. This distinguishes it from sibling tools like cakto_order_bumps_update, create, get, and list.

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

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

It clearly explains when to use it: to reorder order bumps for a product in a single call, passing the full list of {order_bump_id, position}. It also adds practical context like required scope and bulk execution via product_ids, though it does not explicitly compare against 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 only indicate the tool is not read-only. The description adds the required authorization scope, partial-update semantics, and bulk behavior via order_bump_ids/offer_ids. There is no contradiction with the annotations; the write nature implied by 'Atualiza' matches readOnlyHint=false.

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

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

Two compact sentences with zero filler. The core action and partial-update behavior are front-loaded, followed by the scope requirement and bulk support, which is the ideal structure for a tool 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?

For a mutation with 11 parameters, minimal annotations, and no output schema, this description is helpful but incomplete. It does not clarify whether bulk calls still require order_bump_id, and account/position are not explained, leaving some ambiguity for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the parameter-documentation burden. It maps 'oferta' to offer_id/offer_ids, 'preço de referência' to reference_price, 'imagem' to show_image, and mentions bulk IDs. However, account, position, cta/title/description, and the relationship between order_bump_id and order_bump_ids are left unexplained.

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

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

The description opens with 'Atualiza um order bump existente', a specific verb and resource, further narrowed by '(parcial: envie só o que muda)'. It enumerates what can be changed (offer, reference price, copy, image), which clearly distinguishes this update operation from list/get/create siblings.

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

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

It clearly says this is for existing order bumps, explicitly limits updates to partial changes, and states the required 'write products' scope. It does not explicitly name create/list as alternatives, but the 'existente' qualifier plus bulk guidance gives an agent enough context for the common update-vs-create decision.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds genuinely useful behavioral details beyond those annotations: date format 'DD-MM-YYYY neste endpoint,' return values as strings with decimal precision, and '(unclassified)' grouping for sales without UTM.

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

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

The description is a single compact paragraph with no filler. It front-loads the tool's purpose, then gives grouping/filtering instructions, return fields, and an edge-case behavior, with every sentence contributing necessary 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?

With no output schema, the description responsibly lists the returned metrics and their string/decimal nature, and it documents the main grouping and date parameters. Still, the omission of offer, account, and product semantics leaves part of the invocation contract unexplained, so an agent may not know what those parameters control.

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 0% schema description coverage, the description carries the burden of explaining parameters. It usefully explains group_by with its allowed enum values and start_date/end_date with format, covering 3 of 6 parameters. However, offer, account, and product are completely unexplained in both the schema and the description.

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

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

The description opens with 'Analytics de vendas na Cakto: métricas financeiras agregadas por canal/campanha,' clearly identifying the tool as sales analytics with aggregated financial metrics by channel/campaign. This distinguishes it from sibling raw-order tools like cakto_orders_list or cakto_orders_get.

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

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

The description gives clear usage context: group by group_by values and filter by start_date/end_date, with the date format explicitly called out. It does not explicitly name alternatives or state when not to use the tool, but the aggregation focus makes the intended use reasonably clear.

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

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the description does not need to restate that. It adds valuable behavioral context: it returns raw Cakto data with pagination fields and supports batched execution. No contradiction with annotations was 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 bullet structure is efficient and front-loaded, and nearly every line earns its place. The cryptic '[Flattened action: get]' line and the Portuguese/English mix are minor structural distractions, but the description remains compact and scannable.

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

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

For a 12-parameter read tool with no output schema, the description is fairly complete: it covers the two actions, most filters, value formats, pagination, and bulk behavior. The missing 'account' parameter and lack of explicit routing to sibling tools keep it from being fully complete.

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

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

With schema description coverage at 0%, the description carries the full burden and succeeds: it documents 11 of 12 parameters, including allowed values for type, offer_type, status CSV format, date formats for paid_at_gte/paid_at_lt, page, order_id, and order_ids. Only 'account' is left undocumented. This substantially compensates for the empty schema.

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

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

The description clearly states the resource ('pedidos na Cakto') and the specific operations: list with filters and get one order by order_id. It does not, however, explicitly differentiate itself from the sibling 'cakto_orders_list', so an agent may still be unsure which list tool to prefer.

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 internal usage guidance: list for listing with filters, get for a single order requiring order_id, and bulk support via order_ids. It does not state when to use this tool vs alternatives like cakto_orders_list or cakto_orders_analytics, and the '[Flattened action: get]' note adds ambiguity about which action is actually active.

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, and non-destructive behavior; the description adds useful runtime details: raw Cakto data with count/next/previous/results pagination, the flattened action note, and bulk execution support. There is no contradiction with the annotations.

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

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

The description is compact and front-loaded with the overall purpose, then uses scannable action and filter lists. The '[Flattened action: list]' note is useful but makes the structure slightly fragmented.

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

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

The tool has 12 optional parameters, no parameter descriptions, and no output schema, so the description carries substantial weight. It covers filters, date formats, pagination, and bulk behavior, but the account parameter is unexplained and the get-action return shape is not described.

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 0% schema description coverage, the description compensates by explaining most parameters: status as CSV, type as unique|subscription, offer_type as main|upsell|downsell|orderbump, paid_at_gte/paid_at_lt as YYYY-MM-DD, page, and order_ids for bulk. It omits the account parameter, which appears in the input schema, so the coverage is not complete.

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

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

The description clearly identifies the tool as reading Cakto orders and enumerates two actions: list (with a rich set of filters) and get (single order by order_id). It is specific about the verb and resource, but it does not explicitly distinguish the get action from the sibling tool cakto_orders_get.

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

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

The description gives practical context for the list action with filter formats and for the get action by requiring order_id, plus bulk support via order_ids. However, it does not provide explicit when-to-use versus when-not-to-use guidance relative to sibling tools like cakto_orders_get.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond annotations by disclosing pagination structure (count/next/previous/results) and bulk execution support. No contradictions with annotations.

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

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

The description is concise, with the primary action and pagination behavior front-loaded, followed by a compact filter list and a clear bulk-support note. Every sentence adds value and nothing is redundant.

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 listing tool with no output schema, the description provides essential context: pagination shape, optional filters, and bulk behavior. It is slightly incomplete because the account parameter is not mentioned in the prose and response object fields are not described, but the core calling context is covered.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It enumerates most filters by name and clarifies the important semantics of product_id, including comma-separated values and its use for reading one product. However, the 'account' parameter is omitted from the description, and some filters like ordering/status are only named without deeper explanation.

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

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

The description begins with a specific verb and resource: 'Lista produtos da conta na Cakto', clearly identifying this as a read operation on products. It also distinguishes itself from sibling tools like cakto_products_create and cakto_products_update by indicating this is the listing endpoint.

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

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

The description gives clear context for when to use the tool: listing products, including reading a specific product via product_id or performing bulk reads via product_ids. It does not explicitly mention exclusions or name alternative tools for create/update operations, so it stops short of full routing guidance.

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

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

Beyond annotations, the description reveals key side effects: it auto-generates the default offer and checkout, and it requires the 'write products' scope. This adds meaningful behavioral context that annotations do not 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 short and front-loaded with the core action, followed by important side-effect and authorization details. Every sentence adds value with no redundancy.

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

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

While it covers the main action, side effects, and auth, it leaves the meaning of several parameters undocumented and does not describe the return value. For a tool with eight parameters and no output schema, this is a significant 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 0%, and the description provides no explanation for the eight parameters. It does not compensate for the missing schema descriptions by clarifying fields like price, type, account, guarantee, or sales_page.

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

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

The description clearly states the action and resource: 'Cria um produto na Cakto.' It also distinguishes itself from sibling tools by explaining that creation automatically generates the default offer and checkout, making the purpose unambiguous.

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

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

It explicitly notes that no separate checkout endpoint exists, guiding the agent to use this tool for checkout creation. It also implies that the default offer is handled here rather than via cakto_offers_create, though it does not name alternatives explicitly.

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

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

Annotations provide only negative hints (not read-only, not idempotent, not destructive), so the description carries the behavioral burden. It adds valuable context: the update is partial rather than full replacement, blocked is a non-deleting removal mechanism, a specific OAuth scope is required, and bulk execution is supported. This goes beyond the annotations without contradicting them.

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

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

The description is tight and front-loaded: the core action appears first, followed by the most important behavioral qualifier (partial update), then the critical blocked-status behavior, scope requirement, and bulk support. Every sentence earns its place with no filler or repetition.

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

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

Despite covering partial updates, blocked status, scope, and bulk support, the description is incomplete for a 21-parameter mutation tool with no output schema and 0% schema description coverage. It does not clarify whether product_id is still required when product_ids is used, what the response looks like, or how the many un-documented parameters should be valued. This leaves meaningful invocation ambiguity.

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

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

Schema description coverage is 0%, so the description must compensate for 21 parameters. It adds meaning for status (blocked semantics) and product_ids (bulk mode), but the other 19 parameters remain unexplained beyond their names and types. For ambiguous fields like account, affiliate, guarantee, payment_methods, and invoice_description, the agent gets no additional semantic guidance.

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

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

The description states a specific verb and resource: 'Atualiza um produto existente na Cakto' (updates an existing product). It clarifies the update is partial and positions this tool against creation and deletion by noting products can be blocked 'sem apagá-lo'. This clearly distinguishes it from sibling tools like cakto_products_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 explicit usage guidance: send only changed fields, use status="blocked" to take a product out of circulation, requires the 'write products' scope, and supports bulk via product_ids. It does not explicitly name alternatives like cakto_products_create, but the 'existing product' framing and the partial-update semantics make the intended use clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only safety profile is covered. The description adds churn-specific behavior and aggregate metrics, but does not disclose return structure, pagination behavior, or how 'value at risk' is computed.

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

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

The description is a single compact sentence that communicates scope, outputs, and optional filters without filler. It is front-loaded with the core concept ('Assinaturas perdidas'), though it does not use structure to separate list, metrics, and filter details.

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

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

With no output schema, the description bears more responsibility for return-value expectations, but it only vaguely names metrics and does not explain fields, date formats, account scoping, or the relationship to sibling subscription tools. An agent would still need to infer several details before calling it confidently.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions optional period filters, roughly covering start_date and end_date, but leaves page and account unexplained, and provides no format or semantics for any parameter.

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 as lost/canceled/inactive subscriptions and states the concrete outputs: a list plus aggregate metrics (value at risk, affected customer count). This distinguishes it from generic subscription tools like cakto_subscriptions_list, though it does not name or contrast the sibling explicitly.

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

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

The tool's purpose implies it is used for churn analysis, and the optional period filters give context. However, there is no explicit guidance on when to prefer this over cakto_subscriptions_list or cakto_subscriptions_get, and no exclusions or fallback conditions are stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about the flattened action being 'get' and bulk execution via subscription_ids, which goes beyond the annotations without contradicting them.

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

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

The description is compact and uses a clear action list, but it spends significant space describing the 'list' action even though the tool is flattened to 'get'. This reduces focus and could confuse the agent about the actual behavior.

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

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

For a tool with 10 parameters and no output schema, the description gives only partial guidance. It lacks important invocation details such as how subscription_id is supplied, expected response shape, error conditions, and parameter value formats, making it incomplete for reliable autonomous use.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not define most parameters such as account, ordering, status, or search semantics. It mentions subscription_id as required for get, but the visible input schema does not include subscription_id, creating a critical gap for correct invocation.

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 this is for reading Cakto subscriptions and explicitly identifies the flattened action as 'get' for the detail of ONE subscription. This distinguishes it from the sibling cakto_subscriptions_list, though the inclusion of a full 'list' action in the same description causes some ambiguity.

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

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

The description implies the tool is for getting one subscription by subscription_id and mentions bulk support, which is useful. However, it does not explicitly instruct the agent to use cakto_subscriptions_list for listing subscriptions or state when not to use this get tool.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description is consistent with them. It adds useful behavioral context by documenting bulk support via subscription_ids and clarifying that the effective action is 'list'.

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, front-loaded with the resource and purpose, and uses a clear bullet structure. Each sentence adds useful information without restating schema types or repeating 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 10-parameter read tool with no output schema and no property descriptions, the description covers the main invocation paths but leaves gaps: response shape, pagination defaults, ordering syntax, and the role of the 'account' parameter are not explained. It is adequate for basic list usage but not fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It enumerates most filters (status, payment_method, current_situation, search, ordering, limit, page), maps subscription_id to the get action, and mentions subscription_ids for bulk. However, it omits the 'account' parameter and does not explain search/ordering formats or defaults.

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

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

The description clearly states the tool reads Cakto subscriptions and explicitly identifies the main action as 'list: lista assinaturas' with relevant filters. It is clear about the resource and operation, though it does not explicitly differentiate itself from the sibling cakto_subscriptions_get.

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

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

The description gives action-level guidance: list for listing with filters, get for a single subscription requiring subscription_id, and bulk execution with subscription_ids. However, since the tool is flattened to 'list' and a dedicated sibling cakto_subscriptions_get exists, it does not explicitly tell the agent to use that sibling for single-subscription reads, so alternative selection is only implied.

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

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

Annotations already establish this is read-only, idempotent, and non-destructive. The description adds useful behavioral detail beyond that by specifying the two main response states: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This helps an agent predict what to expect.

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

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

The description is compact, front-loads the core purpose, and then adds only the essential conditional details. Every sentence contributes meaningful information, and there is no waste.

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

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

For a zero-parameter read-only status tool with no output schema, the description is complete enough. It tells the agent what information will be returned, what the success condition looks like, and what happens when credentials are missing. The low complexity means no additional guidance is required.

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

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

The tool has zero parameters, so the description does not need to explain any input semantics. The baseline of 4 applies because there is no parameter burden at all.

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

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

The description clearly states the tool's purpose: returning connection status and URLs. It distinguishes connect from its sibling authenticate by framing it as a status/read operation rather than an action, and the conditional output descriptions reinforce this.

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

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

The description makes clear that this is the tool to call when checking connection state or getting URLs. It does not explicitly mention alternatives like authenticate, but the context strongly implies connect is for status checking rather than initiating authentication, so usage is clear without being fully 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?

Beyond the annotations, the description discloses important behaviors: invoke runs an MCP even when it is not installed, does a one-off run without adding the MCP to the toolkit, returns a connect link when credentials are needed, returns a checkout/top-up link when payment is needed, and requires workspace owner/admin for write operations. The description enriches the annotations and does not contradict them.

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

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

The description is front-loaded with identity and the core flow, and nearly every sentence carries useful guidance. However, it is one dense, wall-of-text paragraph with mixed language ("pontualmente") and heavy inline emphasis, which makes the many action alternatives hard to scan and parse.

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

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

For a complex 23-parameter, 14-action facade with no output schema, the description is remarkably complete: it covers the core flow, one-off invoke semantics, auth/credential/payment behavior, permission requirements, installed flags, the prompt library, and most action outcomes. The main gaps are the resume action and return-shape details for a few actions, but the overall guidance is sufficient for correct invocation in most cases.

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

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

With 0% schema description coverage, the description does a lot of compensating work: it maps action values such as search, describe, invoke, install, list_tools, publish_prompt, and explains tool_id, arguments, and prompt-related intent. However, several parameters and enum actions remain unexplained, including resume, limit, immediate, tier_slug, cancel_reason, report_context, conversation, request_name, and request_details, leaving agents under-specified for those paths.

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

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

The description clearly identifies the tool as the official mcp.ai marketplace: the in-platform catalog of MCPs/tools and the way to run them. It states the core discovery→describe→invoke flow, distinguishes the prompt-library subdomain from the MCP flow, and makes it clear this is a marketplace orchestrator rather than one of the sibling calculator/authenticate tools.

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

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

The description gives explicit when-to-use guidance: use install only to make an MCP permanent, prefer invoke for one-off use, use list_tools to see what is callable now, use subscribe/cancel for billing, and use request_mcp when nothing fits. It also explains what to do when invoke returns a connect link or checkout link, including retry behavior.

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

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

Annotations already carry the safety profile with idempotentHint=true and destructiveHint=false. The description adds that conversation data is needed for reproduction, which is useful context. However, it does not disclose what happens after submission, such as whether a ticket is created or whether the report is asynchronous, though the annotations lower the burden.

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

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

The description consists of two tight sentences: the first states the purpose, the second gives the key usage instruction. There is no filler, repetition, or irrelevant detail.

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

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

For a simple three-parameter reporting tool with annotations already covering idempotency and destructiveness, the description is mostly sufficient. The main gaps are the unexplained `context` parameter and the absence of any indication of what the response or outcome will be, though no output schema is expected.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It only clarifies the `conversation` parameter via 'conversation array with recent messages,' leaving the required `message` and optional `context` undefined. The agent must guess at their intended content.

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 the verb 'Report' and explicitly enumerates three targets: 'bug, missing feature, or send feedback'. This makes the tool's purpose unmistakable and easily distinguishable from the sibling calculo_* and authentication tools, which serve entirely different functions.

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

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

The description establishes a clear context: use when a user reports a problem or wants to provide feedback. It also adds practical guidance to 'Include the conversation array with recent messages for reproduction.' It does not name alternatives, but none of the sibling tools overlap with bug reporting, so exclusions are unnecessary.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, non-mutating call. The description adds little beyond that—it names the output as versions but doesn't specify the format (e.g., semver strings, JSON object) or whether the output is human-readable. Since the annotations carry the safety profile, a 3 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?

The description is a single sentence of 9 words, front-loading the action ('Show') and the object ('version'). There is zero waste, and it fully conveys the tool's purpose within its scope. This is a model of conciseness.

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

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

For a zero-parameter, read-only, idempotent tool with no output schema, the description is nearly complete. An agent can confidently invoke it without additional context. The only minor gap is that the return format is unspecified, but since there is no output schema, a brief note on the output structure (e.g., 'returns a plain-text summary') would elevate completeness. Still, the description is sufficient for correct invocation.

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

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

The tool has zero parameters, and the schema coverage is 100% (no properties). The description doesn't need to explain parameters. The baseline for zero-parameter tools is 4, and the description is consistent with that—it correctly implies that no input is required.

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

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

The description clearly states the tool's purpose: 'Show the current MCP platform and adapter versions.' This is a specific verb-resource pair that distinguishes it from sibling tools, which are all calculation or authentication tools. It could be slightly more explicit about what 'show' returns (e.g., a text summary vs. structured data), but the 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?

The description implies that this tool is for checking version information, which makes sense in contexts where an agent needs to confirm platform/adapter versions before proceeding. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention whether version information is needed for authentication or compatibility checks. Given the sibling tools are all calculations, the usage context is reasonably clear, but not explicitly delineated.

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 establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds value by detailing what kind of state is returned, including connection status and account bindings, which helps the agent understand the tool's informational 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?

A single tightly packed sentence with the main action front-loaded, followed by a colon-delimited list of return contents. Every phrase earns its place with no repetition or 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 zero-parameter, read-only introspection tool, the description fully covers what the agent needs to know before calling: what information it will receive. No output schema exists, but the description essentially provides a light output contract by enumerating the returned components.

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

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

The input schema is empty with zero parameters, and schema description coverage is 100%, so the description has no parameter burden. Per calibration, zero-parameter tools receive a baseline of 4; the description's output-focused content is more than sufficient.

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 ('Returns') and resource ('current toolkit state'), then enumerates exactly what is included: installed MCPs, connection status, connected accounts, and catalog tool counts. This is specific enough to distinguish it from computational siblings like calculo_* and action tools like authenticate or connect.

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

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

The description clearly conveys that this is the tool to call when an agent needs an overview or snapshot of the toolkit's current state. It does not explicitly list exclusion criteria or name alternatives such as show_version, but the context is clear enough for routine selection.

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