Meu Ecommerce

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts beyond that: it does not reauthenticate, does not persist/save the contract, and is scoped to the single authenticated store. Those are real operational details an agent would not otherwise know.

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

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

Two short sentences with no filler, and the scope limitation is front-loaded in the second sentence. It is efficient, though the brevity is partly the cause of the missing coverage rather than a virtue.

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 diagnostic tool with an enum parameter, an undocumented UUID parameter, no output schema, and no usage guidance, the description is too thin. It covers side effects and scope but leaves the agent without enough to decide when to call it or how to populate its arguments.

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% for two parameters, including a source enum (wix/mcp) and a UUID supportCode. The description mentions no parameters at all, so it fails to compensate for the schema gap; an agent gets no hint about what source selects or when supportCode is needed.

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

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

The description states a specific action ("Consulta evidências registradas por etapa") but never names the contract-configuration diagnosis that the tool name and title promise, so the resource is only loosely identified. It also gives no signal distinguishing it from sibling diagnose_label_issue or diagnose_quote_issue beyond the implicit subject. Purpose is inferable but vague.

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 when-to-use guidance, no condition that selects this tool over the other diagnose_* siblings, and no exclusions. The only scoping statement ("Limitado à loja autenticada") is a constraint, not 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 a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false). The description adds real interpretive value beyond them: the 10-record default cap and the warning not to equate an absent record with an absent issuance, which directly affects how the agent reads results.

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

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

Three compact sentences, front-loaded with what the tool does, followed by scoping and the two cautionary rules. Little waste; each sentence carries a distinct instruction.

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, zero-required-parameter diagnostic tool with full schema coverage, no output schema, and annotation-covered safety, the description covers invocation, scope, the result-interpretation caveat, and the key misuse to avoid. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents source, orderId, instanceId, and supportCode. The description restates the source/orderId pairing and the supportCode fallback behavior, adding slight emphasis but no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource: query label issuance attempts for the authenticated store, either by supportCode or the 10 most recent. This is clearly a diagnostic/read tool distinguishable from generate_label and the other diagnose_* siblings by name and content, though it does not explicitly name an alternative 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?

Explains how to invoke it (by supportCode, or default to the 10 most recent) and when apps are in scope (Wix/Shopify only via a server-configured link). It adds a clear when-not: do not create another label to resolve a pending PDF, steering the agent away from generate_label/recover_label_pdf. It lacks explicit routing against the sibling diagnose_contract_issue/diagnose_quote_issue 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?

Tool has no description.

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?

Tool has no description.

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

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

Tool has no description.

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

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

Tool has no 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?

Tool has no 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?

Tool has no description.

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 destructive=true, idempotent=false and openWorld=true; the description adds genuinely new context, namely that a store-authenticated Correios contract is required, that the returned PDF link works before rendering completes, and that re-emission must not be attempted on an uncertain result. It stops short of describing failure modes or downstream side effects of an emission.

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?

It is front-loaded with the action and the returned artifacts, then layered with parameter guidance, auth requirement, and exclusions. Four sentences carry real information each, though the closing exclusion sentence is dense and slightly long.

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 9-parameter nested mutation tool with an output schema, the description covers purpose, auth prerequisite, return handoff to the merchant, parameter selection, and the retry/recovery boundary. Nothing essential to correct invocation is missing.

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

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

Schema coverage is 100%, so the per-parameter baseline is 3; the description adds the cross-parameter rule that NF-e (invoiceKey) and DC-e (declaredItems) are the two mutually exclusive declaration paths. The dimensions fallback behavior is left to the schema, but the either/or synthesis is useful beyond the individual field texts.

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+resource pair ('Create a Correios pré-postagem and generate its shipping label (etiqueta) as a PDF') and immediately names the artifacts produced. It is clearly distinguishable from siblings like get_label_pdf and recover_label_pdf, which handle retrieval rather than creation.

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 explicit when-not guidance ('Never use this tool to retry an uncertain emission or recover a PDF') and routes the agent to the correct alternatives (diagnose_label_issue, recover_label_pdf). It also supplies the condition for choosing between invoiceKey and declaredItems.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the auth requirement (store's own authenticated Correios contract) and that a fresh link is produced, but says nothing about link expiry, idempotency, or how it differs behaviorally from recover_label_pdf.

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, purpose front-loaded, then the usage trigger, then the prerequisite. Minimal waste, though the second sentence is slightly circuitous in phrasing.

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 an output schema present, return values need no explanation, and schema coverage is full. What remains missing is behavioral edge detail (link lifetime) and disambiguation from recover_label_pdf, but the core is 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 100%, so both parameters are already documented in the schema. The description only echoes 'by its id', adding no syntax, format, or sourcing detail beyond what the schema provides. 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 a fresh download link) plus the exact resource (PDF of a Correios pré-postagem) and how it's keyed (by id). It references generate_label but does not distinguish itself from the similarly named sibling recover_label_pdf, which appears to overlap.

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

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

Gives an explicit trigger: use when generate_label's link reason was label_pdf_timeout to obtain a new link or re-check status. This is clear context, but it does not state when NOT to use it or name recover_label_pdf as an alternative for the same need.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only calculation and summarizes the response (enabled services, BRL price, delivery estimate, free shipping), but omits plan-dependent behavior visible only in the schema (Advanced-plan dimension memory), idempotency expectations, and any auth/rate constraints.

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

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

Two tightly written sentences with no filler. The purpose and carrier scope come first, and the return summary follows, so 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?

An output schema exists and the input schema is fully annotated, so the description does not need to explain return values or parameter details. It covers what the tool does and what comes back, leaving only usage timing and plan-gated behavior 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 all four parameters (destinationCep, items, requestId, instanceId) are already documented in detail. The description adds only the framing that items represent a cart; it contributes no new syntax or format meaning beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource ('Calculate Brazilian Correios shipping rates') and names the carrier services (SEDEX, PAC) plus the input unit ('for a cart'). The siblings (label diagnostics, tracking, label PDFs) are clearly in a different domain, so there is little ambiguity, but the description never explicitly contrasts itself with 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?

There is no statement of when to use this tool versus alternatives, no prerequisites (e.g., must be called before checkout or before generate_label), and no exclusions. 'For a cart' only loosely implies a pre-purchase quoting stage, which is inference rather than 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 it is a non-destructive, non-open-world write (readOnlyHint=false, destructiveHint=false). The description adds genuinely useful context beyond them: no ticket is created and no external message is dispatched, so the side effect is confined to a local association. It stops short of stating permission requirements or reversibility.

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

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

Two short sentences, zero waste, and the positive action is front-loaded ahead of the negative constraints. Nothing is repeated from title or 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?

No output schema exists, but for a modest four-parameter linking tool the description plus well-described schema fields cover what an agent needs to invoke it. The main residual gap is auth/permission expectations, which the schema only hints at via 'a credencial determina a loja'.

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 75%, with source, ticketRef, and instanceId all carrying inline descriptions, so the schema largely does the work. The description contributes no parameter-level meaning (no format, source semantics, or supportCode guidance), so it sits at the baseline rather than adding value.

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

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

States a specific verb+resource pair ('Associa uma referência de chamado à tentativa da loja autorizada') and immediately bounds it with what it does not do. The agent can tell it apart from the diagnose_* and generate_label siblings because it is clearly a linking/association operation, 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?

'Não cria chamado nem envia mensagens externas' gives partial when-not guidance by excluding two adjacent behaviors, but it never says when this tool should be chosen over the diagnose_* or recover_* siblings, nor what prerequisites (e.g. an existing supportCode) must hold.

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

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false, which is not self-explanatory for a PDF fetch. The description adds real context: it preserves access controls and existing download limits, and is scoped to the credential-determined store. It does not explain what 'readOnlyHint=false' means here (e.g., session consumption), so it is good but not complete.

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

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

Three short sentences, front-loaded with the core action, then the exclusion, then the behavioral note. Every sentence carries distinct 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?

With an output schema present, return-value explanation is unnecessary, and the description covers scope, exclusion, and access behavior. The remaining gap is the unresolved overlap with get_label_pdf, which an agent must disambiguate to choose correctly.

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

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

Schema coverage is only 50%: instanceId is documented in the schema as ignored, but supportCode has no description. The description only obliquely ties supportCode to a 'pré-postagem confirmada' and adds no format or lookup semantics beyond the schema, so it does not fully compensate for the gap.

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

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

States a specific verb and resource ('Recupera apenas o PDF de uma pré-postagem confirmada') plus a scope constraint (authenticated store's attempt). However, it does not differentiate from the sibling get_label_pdf, which appears to retrieve the same artifact, leaving the agent to guess which one to call.

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

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

Explicitly carves out the negative case: 'Não cria etiqueta nem refaz emissão' tells the agent not to use this for issuing or reissuing a label. It stops short of naming the alternative tool (generate_label) for those cases, but the boundary is clearly drawn.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It does reveal the shape of the result set (per-code event history, status, delivered flag), which implies a read-only operation, but it never states that explicitly nor mentions rate limits, error behavior for unknown codes, or authentication implications beyond what the schema already says about instanceId.

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

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

Two tight sentences, correctly front-loaded with the action and resource before the return description. The trailing clause enumerating return fields slightly duplicates the existing output schema, which is the only minor 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?

With an output schema present, the description need not enumerate return fields, and the input schema fully covers both parameters, so the core call path is covered. What remains thin is operational context (limits, failure modes) for a batch network-facing lookup, but nothing essential to invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so both parameters (codes, instanceId) are already fully documented, including the 50-code batch cap and the tracking-code format. The description's example code and 'each code's' phrasing only restate 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?

States a specific verb (Track), a specific resource (Brazilian Correios objects), the identifying input (tracking code with a concrete example), and the payload returned (event history, current status, delivered flag). No sibling among diagnose_*/label tools performs tracking, so the scope is unambiguously distinguishable.

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 this is the tool for looking up shipment status, but the description gives no when-to-use framing, no prerequisites, and no alternatives (e.g. what to use for label issues vs. tracking issues). Adequate but with clear gaps.

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