zuckpay-mcp

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

Annotations already provide readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds that capture is effective after approval and that it is idempotent on PayPal's side, reinforcing these traits. No contradictions, and adds context about required flow.

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

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

Two concise sentences, no wasted words. The first states purpose, the second gives usage condition and idempotency. Efficiently 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?

Given the tool's simplicity (one parameter, no output schema), the description covers when to call and idempotency. Could mention the effect on the order or expected return, but it is reasonably complete for this low complexity.

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%, with orderId described as the ID returned by createPayPalOrder. The description does not add additional meaning to the parameter beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the action (capture) and resource (PayPal order already approved). It distinguishes from the sibling createPayPalOrder by specifying it is for already approved orders, providing specific verb+resource+scope.

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

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

Explicitly states to call only after the payer has opened the approval link and completed the PayPal flow, providing clear context. Also notes idempotency, implying safe retries. Lacks explicit when-not or alternatives, but the condition is well-defined.

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 this is not read-only and not destructive. Description adds that it returns an approval link and that a subsequent capture step is required. It does not elaborate on side effects, persistence, or rate limits, adding only marginal value beyond annotations.

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

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

Three concise sentences front-load the main purpose and return value, followed by currency support and next step. 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?

Given 9 parameters and no output schema, the description covers the essential two-step flow and mentions the approval link. It could benefit from describing the return structure more explicitly, but overall it is sufficiently complete for a simple payment creation tool.

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

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

Schema covers 100% of parameters with descriptions. The overall description adds context about currency default (BRL) and the purpose of the return link, but does not explain parameter semantics beyond what the schema already provides.

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

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

Description clearly states it creates a PayPal order and returns an approval link, specifying integration via ZuckPay. It distinguishes from the sibling capturePayPalOrder by indicating the next step after approval.

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 mentions when to use (to create an order) and directs to capturePayPalOrder after approval. Does not explicitly state when not to use, but the presence of sibling tools for other payment methods (e.g., createPixCharge, createSpeiCashin) implies context.

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

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

Description claims idempotency support via external_id_client, but annotation 'idempotentHint' is false, creating a contradiction. No other contradictions found, but this is a serious inconsistency.

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?

Description is a single, front-loaded sentence that efficiently conveys the tool's purpose and key features. It is concise but could be broken into multiple sentences for better readability.

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 no output schema, the description partially explains what it returns (code, QR, link) but does not detail the response structure or mention required fields. It covers major features but leaves gaps for a complex tool with 26 parameters.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra context (e.g., 'Valor em reais com até 2 casas decimais') but does not significantly enhance understanding beyond the schema.

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

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

The description states a specific verb (cria) and resource (cobrança PIX), and specifies the outputs (copia-e-cola, QR code, link de checkout). It clearly distinguishes this as the PIX creation tool among siblings like createSpeiCashin and createPayPalOrder.

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 usage for PIX payments but does not explicitly say when to use this tool versus alternatives. It lacks guidance on when not to use it or which sibling tools to prefer in specific contexts.

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 indicate a write operation (readOnlyHint=false) and the description confirms it creates a charge and returns a CLABE. It adds the XPAG minimum caveat for the 'valor' parameter, but could further disclose synchronous behavior or post-creation steps.

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 concise sentences front-load the core purpose and output, then quickly cover requirements and document details with no 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?

Given the simple parameter structure and no output schema, the description adequately covers creation, output, and requirements. It could mention how to use the returned CLABE, but overall is fairly complete for a straightforward creation tool.

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

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

With 100% schema description coverage, the baseline is 3. The description adds minor semantic value by clarifying document types (RFC or CURP) and the XPAG minimum for 'valor', but largely reiterates schema information.

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

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

The description clearly states the action ('Cria uma cobrança SPEI'), the currency (MXN), and the output (18-digit CLABE), distinguishing it from siblings like createPixCharge or createPayPalOrder which target other payment systems.

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 specifies prerequisites ('Requer conta ZuckPay com SPEI habilitado') and acceptable documents (RFC or CURP), but does not explicitly direct when to use this tool versus alternatives, although the sibling list provides implicit context.

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

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

Annotations already declare readOnlyHint and openWorldHint; the description adds valuable detail about which balances are returned (available, blocked with release timing, total) and that limits/rates are included. This goes beyond annotations to inform the agent of output contents and meaning.

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, front-loaded with the main action. However, it packs many details (three balance types, two release explanations, limits, rates) which could be slightly overwhelming. Still, it is concise overall and contains 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?

Given there is no output schema, the description fully explains the return information (available, blocked with release specifics, total, limits, rates). It also confirms read-only and no parameters, leaving no ambiguity for a parameterless tool.

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

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

With zero parameters and 100% schema coverage, the description simply confirms 'sem parâmetros'. Per guidelines, baseline for 0 params is 4; the description does not add extra semantic detail beyond stating there are none.

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?

Description explicitly states the tool checks balances of the authenticated ZuckPay account, listing specific components (available, blocked, total) and additional info (limits, rates). The verb 'consulta' and resource 'saldos' are clear. No sibling tool duplicates this purpose.

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?

Description notes the tool is read-only and has no parameters, implying it is used solely for balance inquiry. While it doesn't explicitly contrast with siblings, the lack of similar balance tools makes the usage context clear. A higher score would require explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by explaining the security reason for not exposing card charging and specifying that it returns public keys (publishable keys). 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?

The description is a single, well-structured sentence in Portuguese. It includes the core purpose, the type of data returned, and an important security note. Every word serves a purpose, 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?

Given no output schema, the description adequately explains what the tool returns (list of gateways with publishable keys). It also provides context about the account and security. For a simple listing tool with no parameters, the description 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?

There are zero parameters, so the description does not need to explain them. The baseline for 0 parameters is 4, and the description appropriately mentions the account context (ZuckPay) implicitly. No additional parameter info 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 clearly states the tool lists available card gateways with their publishable keys, specifying the scope (ZuckPay account) and types (Stripe international and/or national BRL card). It distinguishes itself from siblings by being a read-only listing tool, not involved in charging or creating payments.

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 explicitly states the tool is read-only and advises against using it for direct card charging due to PCI security; it directs users to use ZuckPay's hosted checkout instead. This provides clear when-to-use and when-not-to-use guidance, with a named alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds context about the authenticated account scope and explicitly states 'Somente leitura' (read-only), which is consistent. No contradictions. It could mention behavior when ID is not found, but given annotations, this is adequate.

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, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and constraints.

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

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

For a simple read-only tool with one parameter and no output schema, the description is complete. It covers what the tool does, input, and read-only nature. The annotations complement well.

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% with a good description of the 'id' parameter. The description adds no additional parameter meaning beyond 'pelo ID', so it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Retorna os detalhes'), specific resource ('produto específico da conta ZuckPay autenticada'), and method (by ID). It distinguishes from siblings like listProducts which lists all products.

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 usage for fetching a single product's details by ID. It does not explicitly mention when not to use or alternatives, but the sibling listProducts provides a clear alternative for listing. Could be improved by stating that this tool is for individual item retrieval.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds critical behavioral context: strict scoping to the authenticated seller, exclusion of ranking and other sellers' data, and a detailed list of returned fields (total referrals, commissions by status, list, history). This goes beyond what annotations provide and helps the agent understand the exact nature of the tool.

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

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

The description is a single sentence that efficiently conveys the tool's purpose, output fields, and constraints. It is front-loaded with key information and contains no redundant or unnecessary 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?

The tool has no inputs and no output schema, so the description must compensate. It fully covers the output by listing the major categories (total, commissions, list of referrers, history) and the scope constraints. This is sufficient for an agent to understand what the tool returns without needing 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?

There are no parameters, so schema coverage is 100%. The description does not need to add parameter information; the baseline score of 4 applies. The description does not mention any inputs, which is appropriate.

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

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

The description clearly states the tool returns referral program statistics for the authenticated seller, listing specific data (totals, commissions breakdown, list of referrers, history). It also distinguishes itself from sibling tools by explicitly stating it is read-only and scoped only to the own seller, never returning ranking or other sellers' data.

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

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

The description provides clear context: it is read-only and restricted to the own seller. It explicitly states what it does NOT do (never returns ranking or other sellers' data), which helps an agent avoid misuse. However, it does not name specific alternative tools for cases where other sellers' data or rankings are needed.

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

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

Annotations already provide readOnlyHint and openWorldHint. The description adds specificity: read-only nature, timezone (Brasília), and that it returns only aggregate data. This adds value beyond annotations without contradiction.

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

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

The description is a single, efficient sentence that front-loads the core purpose, includes key details, and avoids redundancy. Every word contributes clarity.

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 no parameters and no output schema, the description covers the return fields explicitly (total pago, contagem, ticket médio, breakdown, total pendente). It lacks explanation of the exact structure or format, but the listed fields provide sufficient context for an agent.

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?

No parameters exist, and schema coverage is 100%. The description explains what the tool returns, fulfilling the need for parameter semantics since there are none to describe.

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 it provides an aggregate summary of daily sales (Brasília time) for the authenticated ZuckPay account, specifying included metrics (total paid, count, average ticket, payment method breakdown, pending total) and explicitly excluding individual transactions and buyer data. This distinguishes it from sibling tools like listTransactions.

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 usage for a quick daily sales overview and explicitly states what it does not return (individual transactions or buyer data), guiding the agent to alternatives. However, it does not explicitly name those alternatives, leaving some inference needed.

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

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

Annotations declare readOnlyHint and openWorldHint. The description adds that it is read-only ('Somente leitura') and explicitly lists what is not returned (código customizado, config de pagamento), providing behavioral transparency beyond annotations.

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

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

Two sentences with no wasted words. The first sentence states the purpose and returned fields; the second adds exclusions. All information is front-loaded and concise.

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 no output schema, so the description bears the burden. It lists return fields and scope (authenticated account). While it omits error conditions, for a simple read-only tool this is fairly 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?

There are no parameters (schema coverage 100% baseline 4). The description adds meaning by listing the returned data fields, which the input schema cannot convey.

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 specifies the verb 'retorna' and resource 'dados da loja' along with a list of specific fields (nome, status, slug, domínio, descrição, redes sociais). It clearly distinguishes from siblings by stating it returns store data, while no other sibling tool does the same.

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

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

The description states the tool is for the authenticated ZuckPay account, implying contextual use. However, it does not explicitly state when to use it vs alternatives, but there are no close sibling alternatives.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the tool is clearly non-destructive. Description adds value by listing possible statuses and the ID constraint, complementing 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 concise sentences; first covers purpose and constraints, second enumerates statuses. No unnecessary 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?

No output schema, but description lists possible statuses, giving the agent an expectation. For a simple status check, this is adequate. Could mention other potential return fields, but not critical.

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 covers 100% of parameters with descriptions. The description adds the crucial constraint that exactly one parameter must be provided, which is not in the schema constraints.

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?

Description clearly states the verb ('Consulta'), resource ('status de transação'), and identifiers (transactionId or externalIdClient). It distinguishes from siblings like listTransactions by being a specific lookup tool.

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

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

Explicitly states the constraint that exactly one of the two IDs must be provided. However, no explicit mention of when not to use or alternative tools for listing all transactions.

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?

Description adds value beyond annotations by stating it never returns credentials, is filtered by account config, and lists specific fields. Annotations already indicate readOnly and openWorld, but description enriches with behavioral details.

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

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

Two sentences, no wasted words, front-loaded with verb and resource. Every sentence provides essential 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?

Despite no output schema, description fully explains what the tool returns (PSP, domain, rate) and what it doesn't (credentials). For a simple list tool, this 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?

No parameters exist, so schema coverage is 100%. Description does not need to add parameter info; baseline 4 is appropriate.

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

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

Description clearly states it lists acquirer routes for the authenticated account, specifying data types (PSP, checkout domain, conversion rate) and filtering. It distinguishes from siblings like getCardGateways by focusing on route availability and read-only nature.

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?

Description provides context for when to use (to see available routes for the account) but does not explicitly mention when not to use or alternative tools. However, the filtering and read-only hints give clear usage boundaries.

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 (readOnlyHint, openWorldHint), the description adds that the tool is read-only and does not return enrolled student data. It provides context about the data it does return (counts). This is useful behavioral information not captured in 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 consists of two concise sentences. The first sentence front-loads the main purpose and scope, and the second adds a critical limitation. No redundant or excessive text.

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

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

Given the simplicity of the tool (one optional parameter, no output schema), the description covers the essential aspects: what is listed, ownership, counts, and exclusions. It could mention pagination or sorting behavior, but the open world hint suggests more data exists, which is not clarified. Still, it is largely 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?

The input schema fully describes the limit parameter (range, default). The description does not add new meaning to parameters, but the schema coverage is 100%, so the baseline of 3 is appropriate.

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

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

The description clearly states it lists courses owned by the seller in the authenticated account, includes counts of modules/lessons/students, and explicitly excludes student enrollment data. It distinguishes itself from sibling tools like listProducts or listSubscriptions by specifying the resource type and scope.

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 usage for listing courses but does not provide explicit guidance on when to use this tool versus alternatives. No when-not-to-use or alternative recommendations are given.

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

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

Annotations already declare readOnlyHint=true, and the description confirms this with 'Somente leitura'. It adds specific behavioral details: buyer document and email are always masked, and the token and internal AI triage fields are never returned. This goes beyond the annotations.

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

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

The description is extremely concise, consisting of two short sentences that convey all essential information without any fluff. It is front-loaded with the main action.

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 no output schema, and the description does not detail the return structure or fields. It mentions data that is masked or withheld but lacks full completeness regarding what is returned. For a listing tool, this is a moderate gap.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any additional parameter semantics beyond what is already in the input schema; it merely restates the parameter names.

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

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

The tool name and description clearly indicate it lists chargebacks and refund requests (infractions and MED) from the authenticated ZuckPay account. This distinguishes it from sibling tools like 'listTransactions' and 'getSalesToday', which handle different data.

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

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

The description states the tool is read-only and lists specific infractions, but does not explicitly compare it to alternatives or provide when-to-use guidance. Usage is implied by the tool's specific function.

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 (readOnlyHint, openWorldHint), the description adds that it never returns client_secret and lists the specific fields returned, enriching behavioral understanding.

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

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

The description is a single, well-structured sentence that conveys all critical information efficiently without redundancy.

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

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

For a zero-parameter, read-only list tool without output schema, the description provides complete context: input (none), output (specified fields), behavior (read-only, no secret), and tool ecosystem (no key management tools).

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

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

With no parameters, the description adds meaning by detailing the output fields (nome, domínio, client_id, data de criação), compensating for absence of output 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 it lists metadata of integration keys (name, domain, client_id, creation date) and explicitly distinguishes from any tool that would reveal secrets.

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 specifies the tool is read-only, never returns client_secret, and states that no MCP tool exists for revealing, creating, rotating, or deleting keys, providing explicit when-not-to-use guidance.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, so the description's read-only disclosure adds no new safety info. It does add context about the scope (authenticated account) and listed fields, but this is marginal beyond annotations.

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

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

Single sentence, front-loaded with the verb 'Lista', includes key details without any unnecessary words. Every part of the description carries meaning.

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

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

Given the simple input schema (one parameter), complete annotations, and no output schema, the description covers the essential behavior. Minor gap: does not describe the return format (list of objects) or pagination details, but these are inferred from the action and parameter.

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

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

The only parameter (limit) has 100% schema description coverage, fully explaining its range and default. The tool description does not add any extra meaning beyond the schema, so baseline score 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?

Description clearly states it lists payment links from the authenticated ZuckPay account, specifying fields (nome, valor, status, slug, visualizações). This is a specific verb+resource scope that distinguishes it from sibling tools like createPixCharge or listTransactions.

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

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

Explicitly states 'Somente leitura — não cria nem edita links' (read-only — does not create or edit links), giving clear when-to-use and when-not-to-use guidance. While it does not name alternative tools, the context from sibling names provides implicit differentiation.

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 value beyond annotations by specifying the exact fields returned (name, price, status, type) and the scope (authenticated ZuckPay account). Annotations already provide readOnlyHint and openWorldHint, but the description offers concrete output context without contradicting any 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 only two sentences, front-loaded with purpose and key details. Every word adds value: first sentence lists the resource and returned fields, second sentence clarifies read-only nature. No wasted content.

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 list tool with one optional parameter, the description covers purpose, scope, read-only nature, and output fields. However, it does not explicitly explain pagination behavior (e.g., that 'limit' controls page size) or mention that multiple pages may exist. The schema covers the parameter, but a brief note on pagination would improve completeness.

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%, with the 'limit' parameter fully described in the schema (min, max, default). The description does not mention the parameter, but since the schema already provides complete semantics, the description adds no extra parameter meaning. Baseline of 3 is appropriate.

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

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

The description clearly states the tool lists registered products from the authenticated ZuckPay account, specifying the included fields (name, price, status, type). It distinguishes itself from the sibling 'getProduct' which likely retrieves a single product, though not explicitly. The read-only clarification further differentiates it from write 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 indicates read-only use for listing products, which implies when to use it, but it does not provide explicit guidance on when not to use it or alternatives (e.g., 'getProduct' for single product). Usage context is implied rather than clearly 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?

Description discloses the read-only nature (matches readOnlyHint annotation) and adds specific behavior: subscriber data is masked. Provides more context than annotations alone.

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?

Single sentence effectively conveys purpose, resource, and returned fields. Could be slightly more structured (e.g., bullet points), but it is concise without being terse.

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 listing tool with one optional parameter and no output schema, the description covers the returned data and read-only nature. Annotations provide open world hint, making it sufficiently 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?

The only parameter (limit) has 100% schema coverage with a clear description in the schema. The tool description adds no additional parameter information, so baseline score is appropriate.

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

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

Description clearly states the tool lists subscriptions (recurrences) with specific fields (product, status, value, periodicity, masked subscriber data) and identifies the account context (autenticada ZuckPay). Differentiates from siblings like listTransactions and listProducts by resource.

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

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

Description does not explicitly state when to use or when not to use. It implies read-only usage with 'Somente leitura' but lacks guidance on alternatives or prerequisites.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds significant behavioral context: ordering (newest first), pagination via cursor with limits, timezone (Brasília), and a strong warning against bulk loading. 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?

Description is relatively concise (one long sentence) and front-loaded with the core purpose. It efficiently packs ordering, filters, pagination, cursor, timezone, and a warning. Slight improvement possible by breaking into shorter sentences or bullet points, but it remains clear and readable.

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 8 parameters, no required params, 100% schema coverage, no output schema, and 18 sibling tools, the description covers all essential usage aspects: what is listed, ordering, all filter dimensions, pagination mechanics, timezone, and explicit guidance against loading all data at once. Highly complete for an agent to use 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 100% with detailed descriptions. The tool description restates the filtering capability (status, type, payment method, external ID, period) but does not add new semantic meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

Clearly states the tool lists transactions (vendas e saques) from the authenticated ZuckPay account, ordered newest to oldest, with multiple filters. Differentiates from sibling tools like getSalesToday or getTransactionStatus by listing all transactions with pagination and extensive filtering.

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 instructs to use cursor pagination, load one page at a time, and not attempt to load all at once. Provides clear usage context (filters, timezone). However, does not explicitly state when to prefer this over sibling tools like getSalesToday (specific focus) or getTransactionStatus (single transaction). A short 'when-to-use' would improve differentiation.

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 and openWorldHint. The description adds useful context that webhook creation/deletion is not available via MCP at this phase, enhancing behavioral understanding beyond annotations.

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

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

Two sentences, front-loaded with purpose, no redundant words. Every sentence adds value.

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

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

Given no parameters and no output schema, the description completely covers purpose, scope, limitations, and read-only nature. No gaps for a simple list tool.

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

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

Input schema has zero parameters, so description does not need to add meaning. Baseline score of 4 applies per rules.

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 it lists webhooks configured on the authenticated ZuckPay account, specifying included fields (name, URL, events, status). It differentiates from siblings by noting read-only nature and lack of create/delete capability.

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

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

Explicitly states it is read-only and that creation/deletion is not available, telling the agent when not to use it. Provides clear context but does not name specific alternative tools.

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