Pagar.me

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

Discloses two authentication modes (permanent via config, session via token). Annotations indicate idempotentHint=true, which description does not contradict. Adds context 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?

Description is moderately sized, front-loaded with purpose, and organized into two main options. A bit wordy but effective.

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 authentication tool with one optional parameter and no output schema, the description covers both modes and usage context adequately.

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% but description explains the 'token' parameter is a JWT and can be omitted. Adds meaning beyond 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 states the tool is for authenticating a user by logging in via browser and copying a token. It distinguishes from sibling tools which are mostly pagarme operations.

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

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

Provides explicit instructions on when to use with token (session login) and without token (get login link). Also explains the permanent configuration option.

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=true and destructiveHint=false, indicating a safe read operation. The description supplements this by detailing the response structure (authenticated:true, empty pending[], connect_urls) and the conditions that lead to different responses, adding value 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 two sentences long, with no wasted words. The first sentence front-loads the purpose, and the second provides clear conditions. Every sentence earns its place.

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

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

Given the tool has no parameters and no output schema, the description fully explains the two primary response scenarios. It provides enough context for an agent to understand what to expect without needing additional details.

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 no parameters, and the schema coverage is 100%. According to guidelines, 0 parameters warrants a baseline of 4. The description correctly adds no parameter info since none exist.

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 connection status and URLs. It explains two distinct cases (all connected vs credentials missing), making the purpose very specific. This differentiates it from the 'authenticate' sibling, which likely performs authentication rather than checking status.

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

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

The description provides clear context on when to use the tool: to check if all providers are connected or to get URLs when credentials are missing. However, it does not explicitly exclude use cases or compare with alternatives like 'authenticate', so it lacks 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?

Description goes far beyond annotations by detailing specific behaviors: invoke runs one-off without installation, returns connect link if credentials needed, returns checkout link if wallet empty, writes require specific roles, search/describe flag installed status. 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 long and dense, packed with useful information. However, it is a single paragraph without structure (e.g., bullet points for different actions), making it harder to parse quickly. It could be more concise and better organized.

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 complexity (15 parameters, many actions, no output schema), the description covers the overall purpose, workflow, permission requirements, and edge cases like credential/payment handling. It lacks explicit parameter documentation but provides enough context for an AI agent to use it 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 coverage is 0%, but the description explains the action enum and key parameters (mcp_id, tool_id, arguments) through the workflow. However, many parameters (limit, immediate, tier_slug, conversation, request_name, cancel_reason, cancel_comment, report_context, request_details) are not described at all, leaving them unclear.

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

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

The description clearly identifies the tool as the official marketplace for discovering and running MCPs, with a specific verb 'marketplace'. It distinguishes itself from sibling tools like specific pagarme tools and other utility tools by being the central hub for MCP management.

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

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

Explicit guidance on when to use this tool: 'use THIS tool FIRST, before any external/generic registry' for capability search. Describes core flow (search → describe → invoke) and contrasts install vs invoke: 'prefer invoke for a single/occasional use'. Also covers subscribe/cancel, report_bug, request_mcp, and notes writes require owner/admin.

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

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

Annotations already declare destructiveHint=true, and the description reinforces with 'Irreversível'. It adds context about batch deletion (customer_ids, card_ids) and version V5. 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?

Two concise sentences: first defines core purpose and requirements, second adds bulk support. Front-loaded and efficient with no wasted words.

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

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

For a simple delete tool with clear annotations, the description covers essential aspects (purpose, parameters, irreversibility, bulk). No output schema exists, but return values are typically implied for deletes. Could mention success/error behavior, but adequate.

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 explains the required parameters (customer_id, card_id) and adds bulk parameters (card_ids, customer_ids). However, the 'account' parameter is left undocumented, leaving a minor 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 action ('Remove um cartão salvo'), the resource (card), the API version (Pagar.me V5), required parameters (customer_id + card_id), and irreversibility, distinguishing it from sibling tools like get, list, create, and renew.

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 when to use the tool (to delete a card) and required parameters. It mentions bulk support, guiding users for batched execution. However, it lacks explicit alternatives or when-not conditions.

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 and idempotent. The description adds context about the flattened action and bulk support, which are behavioral traits beyond annotations. 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 concise, front-loads the purpose, and covers key points: what it is, actions, flattened action, and bulk support. No wasted words, though structure could be slightly improved.

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 has 5 parameters, 0% schema coverage, no output schema, and no nested objects, the description covers main use cases but does not explain return data or bulk execution details. The presence of sibling list tool reduces completeness slightly.

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?

Despite 0% schema coverage, the description explains that customer_id is required for actions, card_id is for get, and customer_ids/card_ids are for bulk execution. This adds meaning beyond the schema, though the 'account' parameter is not 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?

The description clearly states it handles saved cards of a client in Pagar.me V5, and defines two actions (list and get) with a flattened action of get. It distinguishes between listing all cards and getting a specific card by ID. However, the dual purpose might cause confusion with the sibling pagarme_cards_list tool, but the description attempts to clarify.

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 mentions that actions require customer_id and lists list/get sub-actions, but does not explicitly state when to use this tool vs the sibling pagarme_cards_list tool. Bulk support is mentioned, but no guidance on when to use bulk vs single card 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 indicate read-only, idempotent, not destructive. The description adds that the tool supports batched execution via customer_ids and card_ids, which is useful. However, it does not explain behavior when both customer_id and card_id are provided, nor does it mention pagination or error handling.

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 relatively short and structured: resource, actions, bulk support. However, the redundancy of listing both 'list' and 'get' actions and then noting 'Flattened action: list' could be streamlined. Still, it is not overly verbose.

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 list tool with 5 parameters and no output schema, the description lacks critical details such as the format of the returned cards, pagination, maximum batch size, or error scenarios. While it mentions bulk support, it is insufficient for complete agent understanding.

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 clarify parameters. It partially explains customer_id (required) and mentions bulk support for customer_ids and card_ids. However, the account parameter is not described, and the role of card_id is unclear (used for get but flattened to list). No description of the remaining parameters.

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 identifies the tool as listing saved cards of a customer in Pagar.me V5. It mentions list and get actions but notes 'Flattened action: list', which is somewhat confusing. It distinguishes from siblings like pagarme_cards_delete and pagarme_cards_get, but the role of the 'get' action in a list tool adds 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 states that list and get require customer_id and mentions bulk support, but it does not clarify when to use this tool versus pagarme_cards_get for single card retrieval. No explicit guidance on when not to use the tool or alternatives.

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

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

Annotations already indicate a write operation. The description adds that it tokenizes/saves card and supports bulk execution, but the inclusion of a renew action that conflicts with a sibling tool reduces clarity.

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 structured with headings and bullet points, but it is somewhat lengthy and includes ambiguous terms like 'Flattened action: create'. Some redundancy exists.

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 6 parameters and no output schema, the description covers API version, required key, parameter details, and bulk support. However, it lacks expected output format and does not resolve the ambiguous sibling relationship.

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%, but the description adds significant meaning by explaining the 'data' field can contain card details (number, holder_name, etc.) and mentions card_id for renew and bulk parameters. This compensates well for the sparse 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 it creates or renews cards, but there is a sibling tool 'pagarme_cards_write_renew' specifically for renewal, creating ambiguity. The 'Flattened action: create' note suggests it is primarily for create, but the description lists both actions.

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

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

No explicit guidance on when to use this tool vs the sibling 'pagarme_cards_write_renew'. The description mentions required customer_id and key, but does not differentiate contexts or provide 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 are minimal (no readOnlyHint or destructiveHint). The description mentions the write operation and bulk execution, but lacks details on side effects, idempotency, or authorization requirements beyond requiring customer_id.

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

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

The description is cluttered with line breaks, redundant action lists, and a '[Flattened action: renew]' note that adds noise. It could be more streamlined and front-loaded with the key 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?

Given the complexity of two actions and bulk support, and no output schema, the description covers basic usage but omits information about return values, error conditions, and what happens after renewal (e.g., new card token).

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%. The description adds meaning by listing data fields for create and specifying card_id for renew, but the structure of the 'data' parameter is described inconsistently (as a string but with multiple fields), which may cause confusion.

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 'Criar/renovar cartões de um cliente' and specifies that 'renew' is the action for this tool, distinguishing it from the sibling tool 'pagarme_cards_write_create' which likely handles only 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?

The description provides usage context: 'renew' requires card_id, and bulk support is noted with array parameters. However, it does not explicitly state when not to use or contrast with alternatives, which would improve 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 indicate destructiveHint=true. Description adds 'Irreversível' (irreversible) which is critical behavioral context. Does not detail other behaviors like auth needs or rate limits, but the added context is valuable.

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

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

Two sentences with no waste. First sentence front-loads main purpose and key params. Second sentence adds bulk support. Efficient and well-structured.

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

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

For a medium-complexity tool with 4 params and no output schema, the description covers the main operation, partial refund, and bulk. No mention of error handling or prerequisites, but annotations provide additional context.

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

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

With 0% schema description coverage, the description compensates well: explains charge_id as required, data as optional with amount for partial refund, and charge_ids for bulk. Only 'account' parameter is left unexplained, giving ~75% 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 tool cancels/refunds a charge on Pagar.me V5, specifies required charge_id and optional data with amount for partial refund. It distinguishes from sibling tools like capture or confirm by focusing on cancellation/refund.

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

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

Provides explicit usage context: requires charge_id, optional data for partial refund, and bulk support via charge_ids. Does not explicitly state when not to use or provide alternatives, but context is clear enough for an agent to infer appropriate use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which describe safe read behavior. However, the description adds confusion by listing all actions, potentially misleading an agent into thinking it can list or summarize. It does not clarify the scope of the tool or any behavioral traits 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 overly broad and includes a bullet list of actions that are not all performed by this tool. The note '[Flattened action: get]' adds confusion. It could be concise and focused on the get operation only, but instead it is cluttered with extraneous 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 complexity of 6 parameters, 0% schema coverage, no output schema, and multiple sibling tools, the description is incomplete. It does not explain the output format, nor does it instruct on how to use charge_id effectively. The lack of clarity on which parameters apply to this specific action makes it insufficient for correct tool selection and 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 coverage is 0%, so the description must compensate. It mentions parameters for each action (e.g., charge_id for get) but does not explain how the parameters relate to the tool's actual 'get' function. It omits semantics for charge_id (e.g., format, requiredness) and does not clarify that list-related parameters (page, size, data) are likely irrelevant.

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 lists multiple actions (list, summary, get, get_many) but identifies the tool as '[Flattened action: get]'. This conflates different operations and fails to clearly state that this tool is specifically for retrieving a single charge by ID. Sibling tools like pagarme_charges_list, pagarme_charges_summary, and pagarme_charges_get_many exist for the other actions, yet the description does not distinguish.

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

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

No explicit guidance on when to use this tool versus alternatives. There are dedicated siblings for list, summary, and batch retrieval, but the description does not advise that this tool should only be used for single charge retrieval via charge_id.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate a safe read operation. The description adds minimal behavioral context: it mentions 'lote' (batch) but does not explain result format, limits, or that charge_ids is required despite being optional in schema. 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 decently sized but includes extraneous information about other actions (list, summary, get) that are not relevant to this specific tool. The key detail is at the end and could be presented more directly.

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 6 parameters, 0% schema coverage, and no output schema, the description fails to provide a complete picture. It leaves many parameters unexplained and does not address return format or usage nuances, relying on the agent to infer from sibling tool names.

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%, placing the burden on the description. Only charge_ids is explained ('vários por charge_ids' – multiple by IDs). Other parameters (data, page, size, account, charge_id) lack any description, causing ambiguity as they may belong to other actions listed but not to get_many.

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 identifies the tool as for retrieving multiple charges by charge_ids (bulk), which distinguishes it from siblings like list (filtered) and get (single). However, the inclusion of other actions (list, summary, get) creates noise and reduces clarity slightly.

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 when multiple charge IDs are available ('vários por charge_ids'). It does not explicitly state when to avoid this tool or compare it to alternatives (e.g., list for filtered queries). Usage is implied but not explicit.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, so the tool's safety profile is clear. The description adds useful details about pagination and filters, but includes contradictory action enumeration that may mislead about behavior.

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

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

The description is front-loaded but includes extraneous action details that bloat it. The note about flattened action adds confusion. It could be much shorter and clearer by focusing solely on the list action and its parameters.

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 6 parameters, no output schema, and no nested objects, the description should provide comprehensive usage context. It fails to explain the 'data' parameter format, the 'account' parameter, or any return structure, leaving significant gaps for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must carry parameter info. It mentions page, size, data (filters), charge_id, and charge_ids, but does not explain the 'account' parameter or the format of 'data' (likely JSON). The explanation is incomplete for effective use.

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 lists multiple actions (list, summary, get, get_many) and notes 'Flattened action: list', creating ambiguity about whether this tool handles only list or multiple operations. This confuses the tool's specific purpose compared to sibling tools like pagarme_charges_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?

No guidance on when to use this tool versus the many sibling charge tools (e.g., pagarme_charges_get, pagarme_charges_summary). The description implies multiple actions but does not explain selection criteria, leaving the agent without clear direction.

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

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

Annotations already indicate readOnly and non-destructive behavior. The description adds that it provides aggregated data, but does not explain what the summary returns (e.g., grouped statuses, counts) or behavioral traits like pagination limit for summary.

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 relatively short and uses bullet points, but the inclusion of multiple actions for a tool that may only support one is structurally inefficient. Each sentence is somewhat earned but could be more focused.

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

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

No output schema exists, yet the description does not describe what the summary output contains (e.g., fields, aggregation type). Given the tool's focus on aggregated data, this omission leaves the agent without critical context.

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

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

Schema has 0% description coverage. The description partially explains parameters for each action (e.g., 'data' for filters, 'charge_id' for get), but the conflicting action list makes it unclear which parameters apply. It compensates minimally but not sufficiently.

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 lists multiple actions (list, summary, get, get_many) but ends with '[Flattened action: summary]', creating confusion about the actual purpose. The name suggests a summary-only tool, but the description includes other actions without clarification.

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

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

No explicit guidance on when to use this tool versus sibling tools like pagarme_charges_list or pagarme_charges_get. The description implies summary is for aggregates, but doesn't differentiate or provide context for choosing.

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 behavioral context beyond annotations: it states the tool is non-destructive (matching destructiveHint: false) and limited to 'contas sk_'. It also mentions bulk execution via charge_ids. However, it does not disclose authentication requirements, rate limits, side effects, or what happens on failure. The mixed-language note about 'não-destrutivas' is helpful but the flattening note is confusing.

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 poorly structured: it mixes Portuguese and English, uses dashes without consistent formatting, and includes a confusing 'Flattened action: capture' line. The list of actions and optional data is helpful but presented in a cluttered manner. It could be significantly condensed and clarified.

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 multi-action nature of the tool (as described), the lack of output schema, and minimal annotations, the description is incomplete. It does not explain how to select an action (no action parameter), what the return value looks like, error cases, or whether actions are idempotent. The bulk support mention is good but insufficient for an agent to use the tool reliably.

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 partly compensates by explaining that charge_id is the key identifier, data can include fields like amount or due_at, and charge_ids enables bulk. However, the 'account' parameter is not mentioned, and the mapping between actions and data content is incomplete. The description adds value but not comprehensive semantic 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 tool name 'pagarme_charges_write_capture' implies a single action (capture), but the description lists multiple actions (capture, retry, confirm, update_due_date, etc.) without clarifying which one this tool performs. The 'Flattened action: capture' line conflicts with the listed actions, making the purpose vague. Sibling tools exist for specific actions (e.g., pagarme_charges_write_confirm), yet this description lumps them together.

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 provide clear guidance on when to use this tool versus its siblings. It mentions bulk support and required charge_id but fails to explain why one would choose this over, say, pagarme_charges_write_retry. No when-not-to-use or alternative suggestions 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?

Beyond annotations (destructiveHint=false), the description adds context: 'só contas sk_' (account restriction) and 'Bulk support: accepts charge_ids for batched execution.' It also indicates actions require charge_id and data is optional. This provides useful behavioral insight beyond the schema and 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 somewhat verbose, listing all possible actions when the tool is specifically for confirm. This information is better placed in the respective sibling tools. The flattened action note and bulk support are relevant, but the extra action list could be trimmed for focus.

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 should explain return values or expected outcomes. It does not. Also missing are prerequisites (e.g., charge must exist) and effects of confirmation. For a 4-parameter tool, this leaves significant 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?

Input schema has 0% description coverage, so the description must compensate. It mentions charge_id (required), data (optional for some actions), account, and charge_ids (bulk), but does not explain data or account fields. The parameter semantics are minimally described, leaving ambiguity.

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 operates on charges in Pagar.me V5 with a confirm action (flattened action: confirm). It also notes it's non-destructive and for accounts with sk_. However, it lists other actions (capture, retry, etc.) which may cause confusion about this tool's specific role, especially since sibling tools exist for those actions.

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

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

The description implies usage for confirming charges and mentions bulk support via charge_ids, but does not explicitly state when to use this tool versus alternatives like pagarme_charges_write_capture or pagarme_charges_write_retry. Lack of when-not or explicit comparison reduces clarity.

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 non-destructive, and the description confirms that. It adds bulk support detail but lacks further behavioral traits like idempotency or side effects. Minimal 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?

Description is somewhat lengthy and mixes Portuguese and English. The list of actions is redundant with the tool's actual purpose and could be trimmed. Structure is organized but could be more 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?

Despite no output schema, the description should clearly convey what the tool does. The ambiguity about which action is performed undermines completeness. Important context like whether it modifies state or just triggers a retry is unclear.

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 has 0% description coverage. The description mentions 'data opcional' for some actions and bulk charge_ids, providing some context. However, the mapping of 'data' parameter to specific sub-fields (amount, due_at) is unclear given the schema defines data only as a string.

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 lists multiple actions (capture, retry, confirm, etc.) but then states 'Flattened action: retry.' This is contradictory and confusing. The tool name suggests retry, and sibling tools exist for the other actions, so the purpose is unclear.

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

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

No explicit guidance on when to use this tool vs alternatives like pagarme_charges_cancel or pagarme_charges_write_capture. The constraint 'só contas sk_' is noted but doesn't differentiate from siblings.

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

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

Annotations indicate non-destructive, and description confirms 'não-destrutivas'. Description adds account restriction ('só contas sk_') and bulk support via charge_ids. However, it lacks detail on side effects per action (e.g., what happens to the charge).

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 short but includes a bullet list of actions. The '[Flattened action: update_card]' note is confusing and adds clutter. Front-loads the main verb but lacks a clear summary.

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

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

Given the complexity (multiple actions, bulk, sibling overlap), the description is incomplete. It does not differentiate from sibling tools, explain return values (no output schema), or provide enough detail for correct invocation. Agents are likely to misuse the tool.

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

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

Schema coverage is 0%, so description must compensate. It explains that charge_id is required and lists optional data meanings per action (e.g., capture: amount, update_due_date: { due_at }). But it does not specify the format or constraints for the 'data' parameter, and bulk behavior for data is unclear.

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

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

The description lists multiple actions (capture, retry, confirm, etc.) but the tool is named 'update_card' and includes a '[Flattened action: update_card]' note, causing confusion. Sibling tools like pagarme_charges_write_capture exist for specific actions, so the purpose of this catch-all tool is ambiguous.

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 says 'Operar cobranças' and lists actions, but provides no guidance on when to use this tool versus the specific sibling tools (e.g., pagarme_charges_write_capture). No explicit when-to-use or when-not-to-use information.

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 readOnlyHint=false and destructiveHint=false. The description adds that operations are 'não-destrutivas' (non-destructive) and clarifies account prefix restriction. No additional details on error handling, rate limits, or idempotency 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 front-loaded with the main action and uses bullet points for clarity. However, it includes details about other actions that are not core to this specific tool, making it somewhat less 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?

Given the complexity (4 parameters, no output schema), the description covers the main action, required parameters, and bulk support. It lacks information on return values, error conditions, and precise data formats, leaving some gaps 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?

With 0% schema description coverage, the description compensates by explaining that 'data' should contain 'due_at' for update_due_date, and that 'charge_ids' is for bulk execution. However, it does not specify formats, constraints, or elaborates on all parameters (e.g., 'account').

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 explicitly states it operates on Pagar.me V5 charges and lists the specific action 'update_due_date' (flattened). It distinguishes from sibling tools like capture, confirm, retry by naming the action, though the inclusion of other actions may cause slight confusion.

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 context: it is for accounts starting with 'sk_', requires charge_id, and supports bulk via charge_ids. However, it does not explicitly state when to use this tool over alternatives or when not to use it.

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

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

The description states 'não-destrutivas' (non-destructive) which aligns with annotations (destructiveHint=false) and mentions account type constraint ('só contas sk_'). However, it does not disclose other behavioral traits like side effects, permission requirements, or what happens on failure. Annotations provide no extra help, so the description carries the burden but falls short.

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 verbose and includes a list of unrelated actions (capture, retry, etc.) that are not relevant to this tool. This dilutes the focus and wastes space. The flattened action note helps, but overall it could be much more 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?

Given the tool has 4 parameters, no output schema, and annotations that are minimal, the description should provide more context. It lacks details on the expected format of 'data', what the tool returns, error handling, and prerequisites beyond charge_id. The mention of bulk support and account filter is useful but insufficient for a write operation.

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

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

The input schema has 4 parameters with 0% description coverage. The description adds that 'data' is used for the action ('update_payment_method: altera meio de pagamento (data)') and mentions 'charge_ids' for bulk support. It partially explains the purpose of 'charge_id' and 'charge_ids', but 'account' remains unexplained. This adds some value beyond the schema but does not fully compensate for the low 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 lists multiple actions (capture, retry, confirm, etc.) but the tool is specifically for update_payment_method. The flattened action line clarifies, but the overall purpose is muddled and does not clearly distinguish this tool from its siblings that handle other actions.

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

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

No explicit guidance on when to use this tool versus alternatives like pagarme_charges_write_update_card or pagarme_charges_write_capture. The description implies the action requires a charge_id but does not specify when update_payment_method is appropriate or when not to use it.

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

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

Annotations correctly indicate readOnly, idempotent, and non-destructive behavior. The description adds 'Bulk support' which is a behavioral trait not in annotations. However, it doesn't mention error handling (e.g., if customer not found) or rate limits.

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

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

The description is verbose and includes information about multiple actions, making it unfocused. It should be front-loaded with the specific purpose of this tool. The '[Flattened action: get]' note is helpful but buried.

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 0% parameter description coverage, the description is insufficient. It doesn't specify what the tool returns for a 'get' action (e.g., customer details). The bulk support mention is vague and doesn't explain batch execution behavior.

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

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

Schema coverage is 0%, so the description must explain parameters. It mentions customer_id, address_id, page, size, customer_ids, address_ids, but only in context of other actions. The 'data' and 'account' parameters are not explained. The mapping of parameters to the 'get' action is unclear.

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

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

The description lists multiple actions (list, get, list_addresses, get_address) and states 'Flattened action: get', but it's unclear what this specific tool does. The name implies retrieving a single customer, but the description mixes other actions, creating 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?

No explicit guidance on when to use this tool versus sibling tools like pagarme_customers_list or pagarme_customers_get_address. The description implies that for 'get' you need customer_id, but it doesn't clearly differentiate usage scenarios.

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, destructiveHint. Description adds that the tool supports bulk execution with customer_ids and address_ids, and lists data fields for list action. However, it does not disclose response format, authentication needs, or any side effects beyond what annotations imply.

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 verbose, listing multiple actions in a bullet-like format, then adding a flattened action note and bulk support. It could be streamlined to a single sentence about getting an address with optional batch. The structure is cluttered and lacks prioritized 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 8 parameters, no output schema, and 0% schema descriptions, the description is incomplete. It does not specify required parameters (e.g., customer_id and address_id for get_address), explain the 'data' or 'account' fields, or describe the return structure for get_address. The list fields mentioned are not applicable to this tool's main action.

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

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

With 0% schema description coverage, the description partially compensates by mentioning customer_id, address_id, page, size, customer_ids, address_ids. However, it leaves 'data' and 'account' parameters unexplained. The requirements are implied but not explicitly linked to parameter combinations.

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 lists multiple actions (list, get, list_addresses, get_address) but states it is flattened to get_address. This creates ambiguity about the tool's primary purpose, as it mixes different operations. The name suggests a single get_address operation, but the description is not sharply focused.

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

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

No explicit guidance on when to use this tool versus sibling tools like pagarme_customers_get or pagarme_customers_list_addresses. The bulk support mention is not framed as a usage scenario, and there is no indication of when to use batch versus single calls.

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 readOnlyHint, idempotentHint, and destructiveHint, indicating a safe operation. The description adds useful behavioral context like bulk support via customer_ids and address_ids, and pagination with page/size. It does not contradict 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 somewhat verbose with multiple actions and a flattened action note, but it is structured with bullet points. It could be more concise by focusing solely on the list 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?

Given the tool's complexity (8 optional parameters, no output schema), the description lacks complete guidance. It does not describe the return format, the exact meaning of 'data' parameter, or how bulk execution works in detail. Annotations cover safety but not functional 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?

With 0% schema description coverage, the description must compensate. It explains parameters for the list action (page, size, data) and mentions customer_id, address_id, customer_ids, address_ids in context. However, the 'account' parameter is not explained, and the 'data' parameter's exact role is ambiguous (filter vs. output fields).

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 indicates the tool is for listing customers, with the action 'list' highlighted via 'Flattened action: list'. It includes specific fields (name, email, document, code) and differentiates from sibling tools like pagarme_customers_get and pagarme_customers_list_addresses. However, the inclusion of multiple actions (get, list_addresses, get_address) adds slight 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 usage for listing customers but does not explicitly state when to use this tool versus alternatives. It mentions the list action with parameters, but no explicit when-not or alternative tool 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, so description's main addition is the requirement for customer_id and batch execution. Describes no side effects beyond what annotations cover.

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 includes a list of unrelated actions (list, get, etc.) before focusing on list_addresses. This is verbose and not front-loaded for the specific tool.

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

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

With 8 parameters and no output schema, the description fails to explain most parameters (page, size, data, account, address_id). Only customer_id and bulk arrays are covered, leaving significant gaps.

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

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

Schema coverage is 0%. Description only explains customer_id, customer_ids, and address_ids in context. Leaves page, size, data, account, address_id 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 explicitly states 'list_addresses: endereços do cliente (requer customer_id)' and distinguishes from sibling tools like pagarme_customers_get_address (single address) and pagarme_customers_list (list customers). The flattened action clarifies the exact operation.

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

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

Clearly mentions that customer_id is required ('requer customer_id') and notes bulk support with customer_ids and address_ids. However, it does not explicitly state when not to use or compare directly to alternatives like get_address.

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 destructiveHint=false, but the description includes a delete action. This contradiction is confusing. No details on permissions, rate limits, or side effects.

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 somewhat organized but includes redundant action listings and unclear flattening. It could be more concise without losing 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 no output schema and missing parameter explanations, the description is insufficient for reliable use. No details on return values, error handling, or required ID relationships.

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% and the description does not explain any parameter semantics. For example, 'data' is a string but its format (JSON?) is unspecified; 'account', 'address_ids', 'customer_ids' have no 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 states it creates/updates customers and addresses, but the mention of multiple actions followed by '[Flattened action: create]' creates ambiguity. It does not clearly distinguish from sibling tools like 'pagarme_customers_write_create_address'.

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

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

No guidance on when to use this tool versus the many sibling tools for similar operations. No exclusions or prerequisites 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 set destructiveHint=false, yet the description includes a 'delete_address' action, which is destructive. This is a clear contradiction. Additionally, the description fails to disclose other behavioral traits like idempotency, side effects, or authorization beyond mentioning 'só sk_'. The annotation contradiction warrants the lowest score.

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 with a bullet list but includes redundant phrasing like 'Flattened action: create_address' and 'Bulk support'. While not overly verbose, some sentences could be streamlined.

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 complexity (6 parameters, multiple actions, no output schema), the description is severely incomplete. It does not explain how to select an action via parameters, lacks return value details, omits error handling, and only vaguely mentions bulk support. An agent would struggle to use this tool 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 description coverage, the description must compensate but only vaguely references 'data' and required IDs in action bullets. It does not map parameters to specific actions (e.g., when to use address_id vs address_ids) or explain the structure of 'data'. This adds little meaningful guidance 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 attempts to cover multiple actions (create/update/delete customers and addresses) but the tool's name focuses on 'create_address', and sibling tools exist for individual actions. The purpose is muddled: it's unclear whether this tool is for all actions or specifically for create_address.

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 lists actions but provides no guidance on when to use this combined tool versus the dedicated siblings (e.g., pagarme_customers_write_create, pagarme_customers_write_update). No exclusions or alternatives are mentioned.

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 includes a destructive action (delete_address: 'remove endereço'), but annotations declare destructiveHint=false. This is a direct contradiction. The description also fails to disclose other behavioral traits like authentication requirements or irreversible consequences beyond the annotation conflict.

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, listing actions in a clear bullet-like structure. The '[Flattened action: delete_address]' note helps. Some repetition of 'requer customer_id; data' could be streamlined, but overall it's 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?

Given the complexity of multiple actions and no output schema, the description provides necessary action breakdowns and parameter roles. However, it lacks explanation of the 'data' parameter format, return values, error handling, and does not fully compensate for missing schema docs. The bulk support note adds some value.

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 partially explains parameters: customer_id and address_id are linked to address actions, and data is mentioned for create/update. However, 'data' and 'account' remain unexplained, and the description does not specify the format or required fields within 'data'. The bulk parameters (customer_ids, address_ids) are mentioned but not detailed.

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 lists five actions (create, update, create_address, update_address, delete_address) and specifies required fields. The tool name includes 'delete_address', but the description clarifies it handles multiple customer and address write operations, distinguishing it from siblings like pagarme_customers_write_create which likely handles only 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 states required parameters for address actions (customer_id, address_id) and mentions bulk support, but it does not guide the agent on when to use this combined tool versus the more specific sibling tools (e.g., pagarme_customers_write_create, pagarme_customers_write_update, pagarme_customers_write_delete_address). No explicit when-to-use or when-not-to-use advice.

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 discloses destructive behavior (delete_address) and batch execution, but annotations set destructiveHint=false, which contradicts the description. No info on authentication requirements (though 'só sk_' hints at API keys), rate limits, or idempotency is given. The contradiction lowers the score significantly.

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 organized with action bullet points and mentions bulk support, but the line '[Flattened action: update]' is confusing and adds little value. It could be more concise by removing that line and clarifying the action combination. Overall, it has a reasonable structure but some 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 the tool's complexity (six actions, bulk support) and lack of output schema, the description omits crucial details: expected return values, error handling, permissions, and detailed bulk usage. The 'data' field format is left ambiguous. Missing output schema makes it harder for the agent to use the tool 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?

The description adds context to parameters, e.g., 'customer_id' is required for update and address actions, and 'data' includes fields like name, email. However, 'data' is typed as a string in the schema, but the description implies it should contain structured fields, which is vague. Schema description coverage is 0%, so the description provides some help but is incomplete.

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 creates/updates customers and addresses in Pagar.me V5, listing five specific actions (create, update, create_address, update_address, delete_address). It distinguishes from sibling tools like pagarme_customers_write_create by being a combined write/update tool, but does not explicitly call out when to prefer more specific 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?

No explicit when-to-use or when-not-to-use guidance is provided. The description mentions bulk support and a 'flattened action: update' but does not advise on choosing between this tool and more specific siblings like pagarme_customers_write_create or pagarme_customers_write_update_address.

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 readOnlyHint=false (mutation) and destructiveHint=false. The description says 'atualiza endereço' adding no further behavioral context such as side effects, permissions, or idempotency. It does not contradict the annotations, but adds minimal value beyond 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 a single paragraph listing multiple actions, which is somewhat verbose for a tool focused on one action. It front-loads the flattened action but includes extra details that could be streamlined. Not overly long but could be more 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?

Given 6 parameters with no schema descriptions and no output schema, the description covers basic usage (required IDs) but lacks details on parameter types, data format, return values, and error handling. Bulk support is mentioned but not explained. The tool is complex enough to warrant more complete guidance.

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 must compensate. It mentions customer_id, address_id, and bulk versions (customer_ids, address_ids) but does not explain what 'data' should contain (presumably JSON with address fields). The description provides some context but not enough to fully understand parameter formats and 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 the tool is for updating an address (flattened action: update_address), which is a specific verb+resource. However, it also lists other actions (create, update customer, create/delete address), causing some ambiguity. It distinguishes from siblings like create_address and delete_address by explicitly mentioning the flattened action.

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 tells when to use the tool for update_address (requires customer_id and address_id) and mentions bulk support. But it does not explicitly state when not to use this tool or point to alternative sibling tools like 'pagarme_customers_write_create_address' for creation. Usage is implied rather than explicitly contrasted.

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 set destructiveHint=true, and the description reinforces this by stating 'Irreversível' (irreversible). It additionally discloses bulk support behavior, which goes beyond the annotations. There is no 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 extremely concise: two sentences. The first sentence covers purpose, requirement, and irreversibility. The second adds bulk support. There is no redundant or unnecessary 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?

For a cancellation tool with three parameters and no output schema, the description covers purpose, required parameter, irreversibility, and bulk capability. It lacks explanation of the account parameter and potential error conditions, but is largely complete given the tool's simplicity.

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 has three parameters (account, invoice_id, invoice_ids) with 0% description coverage. The description adds meaning for invoice_id (required) and invoice_ids (bulk), but ignores the account parameter. This partial compensation results in a baseline of 3.

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

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

The description clearly states the verb 'Cancela' (cancel) and the resource 'fatura' (invoice), specifying the Pagar.me V5 platform and the required invoice_id. It distinguishes itself from siblings like pagarme_invoices_get or pagarme_invoices_write by being the cancel operation.

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 mentions that invoice_id is required and that bulk execution is supported via invoice_ids. However, it does not provide explicit guidance on when to use this tool versus alternatives or when not to use it (e.g., prerequisites, state of invoice). Usage is implied but not fully elaborated.

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 bulk support context but does not disclose additional behavioral traits such as authentication requirements, rate limits, or side effects.

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 reasonably concise but mixes Portuguese and English, and the structure (list of actions, then mention of bulk) could be cleaner. It is functional but not optimally front-loaded.

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

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

For a tool with 6 parameters and no output schema, the description covers the main actions and bulk support but lacks details on return format, error handling, and the account parameter. Annotations provide a safety profile, so completeness is moderate.

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 provides some meaning for parameters: it mentions 'data' can contain subscription_id, customer_id, status, due_since/until; page and size for pagination; invoice_id and invoice_ids. However, the 'account' parameter is not explained, and 'data' is ambiguously typed as a string.

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 the tool is for invoices (faturas) in Pagar.me V5 and enumerates two actions: list and get. It also mentions bulk support, which differentiates it from a simple get. However, it does not explicitly distinguish itself from the sibling pagarme_invoices_list, which might be confusing.

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

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

No guidance is provided on when to use this tool versus alternatives like pagarme_invoices_list or pagarme_invoices_cancel. The description does not specify contexts for list vs get vs bulk operations.

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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that it is a list operation with bulk support via invoice_ids, providing behavioral context beyond annotations. However, it lacks details on pagination behavior or rate limits.

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

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

The description is relatively concise and includes bullet points for clarity, but mixes Portuguese and English, which may cause minor confusion. The structure is acceptable but could be streamlined.

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

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

There is no output schema, and the description does not describe the return format or fields of the invoice list. For a list tool, this is a significant gap. Additionally, the bulk behavior is mentioned but not fully 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?

With 0% schema description coverage, the description adds value by explaining that 'data' contains filter fields (subscription_id, customer_id, status, due_since/until) and mentions invoice_id and invoice_ids. However, it does not explain the format of the 'data' string or the 'account' 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 states the tool is for listing invoices ('Faturas... list') and distinguishes between list and get actions, with an explicit indication that this tool is for listing ('[Flattened action: list]'). It also mentions bulk support, further clarifying its 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?

The description does not provide explicit guidance on when to use this tool versus alternatives like pagarme_invoices_get or pagarme_invoices_cancel. While it mentions a 'get' action for single invoice retrieval, it does not specify usage contexts 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 indicate a non-destructive write operation; description adds that it changes status but lacks detail on side effects, permissions, or rate limits. Behavioral insights are minimal.

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 with front-loaded purpose and requirements. Bulk support is noted separately, making it easy to scan.

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, no description of return values or error conditions. For a mutation tool, this leaves significant gaps in understanding the full behavior.

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

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

Schema coverage is 0%. Description explains invoice_id and status via examples, and invoice_ids for bulk support, but 'account' is not described. Valid status values are not enumerated.

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 alters invoice status with examples ('paid', 'canceled'). It identifies the API version and required parameters, but does not differentiate from the sibling tool 'pagarme_invoices_cancel', which may cause confusion.

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

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

No guidance on when to use this tool versus alternatives like pagarme_invoices_cancel. No prerequisites or context for appropriate use 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 (readOnlyHint=true, idempotentHint=true) align with the 'Leitura' mention, but the description then adds 'Bulk support' and a list of endpoints without explaining behavior beyond reading. The mixed messaging reduces transparency.

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 verbose and includes a bullet list of unrelated actions, making it unfocused. The structure is cluttered, and the 'Flattened action: balance' line is unclear. It is not 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?

Given the complexity (many sibling tools, no output schema, unannotated parameters), the description is insufficient. It fails to differentiate this tool from similar legacy tools and omits critical usage context.

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

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

The input schema has four parameters (data, account, transaction_id, transaction_ids) with zero schema description coverage. The description does not explain any parameter or how to use them, leaving the agent without 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 tool name is 'pagarme_legacy_balance', suggesting a balance-specific function. However, the description lists numerous other actions (list_transactions, get_transaction, etc.) that belong to separate sibling tools, creating confusion about the tool's actual 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?

No guidance is provided on when to use this tool versus the many sibling tools that cover the listed actions (e.g., pagarme_legacy_list_transactions). The description does not clarify the intended scope.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that the tool uses legacy ak_ keys, supports bulk via transaction_ids, and that field differences between V1-V4 appear raw in payload. 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 lists many actions and includes some redundancy (e.g., 'Flattened action'), making it longer than necessary. Key information is present but could be more streamlined.

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 lacks explicit details about the return value (e.g., single transaction object) beyond noting raw version differences. Given no output schema, more completeness would be helpful.

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 has 4 parameters with 0% description coverage. The description adds meaning for transaction_id (implied required) and transaction_ids (bulk support) and filters via data, but does not describe the account parameter. This provides moderate added value 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 clearly states the tool reads legacy transactions from Pagar.me API V1-V4, and specifies the get_transaction action requires a transaction_id. It distinguishes from sibling tools like pagarme_legacy_list_transactions by focusing on a single transaction retrieval.

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 usage context (when connection uses ak_ key, non-migrated to V5) and lists actions including get_transaction. However, it does not explicitly state when to use this tool versus other legacy tools like list_transactions, though the 'Flattened action' helps.

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 readOnlyHint=true and idempotentHint=true. The description adds that filtering is done via the 'data' parameter with typical list filters (count, page, status), and notes that field differences across versions come raw in the payload. However, the mention of 'bulk support: accepts transaction_ids' is questionable for a list_customers operation and may mislead. Overall, adds moderate behavioral context beyond annotations.

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

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

The description is overly verbose, containing a full list of actions that belong to multiple other tools. The flattened action notation helps, but the bulk of the text is not focused on the tool's specific function. This verbosity reduces clarity and makes it harder for an agent to quickly parse the 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?

There is no output schema, and the description does not explain the return value format or structure. While it mentions field differences in payload, it omits what fields to expect. For a legacy API with multiple versions, more detail on response shape would be valuable. The description also fails to clarify how the 'transaction_id' and 'transaction_ids' parameters relate to listing customers.

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 explain parameters. It only partially explains 'data' (filters as JSON) and implicitly 'account' (string for account identifier). The parameters 'transaction_id' and 'transaction_ids' are not explained and seem irrelevant to listing customers. This leaves significant ambiguity for an AI agent.

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 is for the legacy Pagar.me API (V1-V4) and the flattened action specifies 'list_customers'. However, it includes a list of other actions (list_transactions, get_transaction, etc.) that are not the focus of this tool, causing some confusion. The tool name and context signals indicate a specific listing purpose, and the distinction from modern API (V5) is implicit but present.

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 a condition: use when the connection uses an ak_ key (accounts not migrated to V5). This helps decide when to use this legacy tool instead of modern alternatives. However, it does not explicitly name sibling tools like pagarme_customers_list for comparison, though the context is sufficiently 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 and destructiveHint=false. The description adds bulk support via transaction_ids and version-specific field variations, providing useful behavioral context beyond annotations.

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

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

The description is overly verbose and contains general legacy API context and a list of actions not specific to this tool. The key action is buried, and the structure is messy.

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 4 parameters and no output schema, the description fails to fully cover parameter semantics or return format. The 'account' parameter is unexplained, and response details are 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 0%. The description explains the 'data' parameter as a JSON filter for list options and mentions 'transaction_ids' for bulk. But 'account' and 'transaction_id' are not explained, leaving gaps.

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 the tool lists payables from the legacy Pagar.me API, but it is cluttered with other actions and general legacy context, which dilutes focus. Sibling pagarme_payables_list exists, but no explicit differentiation.

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?

Describes when to use (legacy accounts with ak_ keys) and mentions differences between V1-V4. However, it does not explicitly contrast with sibling tools or specify when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint as safe. The description adds that this tool handles multiple actions (e.g., list_transactions, balance) but is flattened to list_plans, and that payload differences exist across versions. No 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?

Description is front-loaded with purpose and bullet-style for actions. Could be trimmed (e.g., 'Ações:' list) but remains clear 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?

Given no output schema and moderate complexity (legacy, multiple actions), the description covers core behavior, parameter usage for two key params, and context. Missing details on 'account' and 'transaction_id' prevent a 5.

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

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

Schema has 0% description coverage; description explains 'data' holds JSON filters (count, page, status) and 'transaction_ids' enables bulk execution. However, 'account' and 'transaction_id' are not described, so only partial compensation.

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 plans from the Pagar.me legacy API V1-V4, using verb 'list' and resource 'plans'. It distinguishes itself from the V5 counterpart (pagarme_plans_list) by specifying 'LEGADA' and the ak_ key condition.

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 context: use when connected with an ak_ key (legacy account). It implies the scope (V1-V4) but does not explicitly state when not to use or name alternatives like pagarme_plans_list, though siblings make it 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. The description adds behavioral context by stating this is a 'Leitura' (read) operation for the legacy API, mentioning filter support via JSON data, and highlighting bulk support with transaction_ids. 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 verbose, listing many actions not specific to this tool (e.g., list_transactions, list_subscriptions). The important information is present but buried. The '[Flattened action]' line helps, but the overall structure could be more concise and targeted.

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 provides context about the legacy API and filter capabilities, but lacks details on the output format or return values (no output schema). It covers the when-to-use aspect well, but given the complexity and number of sibling tools, more detail on the response structure 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?

Input schema has 0% description coverage. The description adds meaning by explaining that the 'data' parameter accepts JSON for filters (count, page, status), and that 'transaction_ids' is for batch execution. However, the 'account' parameter is not explained, and the description does not fully detail each parameter's format or constraints. Partial compensation for low 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 this tool is for reading the legacy Pagar.me API (V1-V4) and lists 'list_recipients' as one of the actions. The '[Flattened action: list_recipients]' line explicitly identifies the operation. It is distinguishable from sibling tools like 'pagarme_recipients_list' which likely target the newer V5 API.

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 that this tool is active when the connection uses an 'ak_…' key, indicating accounts not yet migrated to V5. This provides explicit context for when to use this legacy tool over its V5 counterparts. It also lists available actions, but does not explicitly state when not to use it, hence a 4.

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=true, consistent with the read nature. The description adds 'Bulk support: accepts transaction_ids for batched execution,' which is useful but lacks details on batch behavior (e.g., how results are aggregated). 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 verbose and unfocused, listing all legacy API actions instead of solely describing the subscription listing tool. The 'Ações:' list is irrelevant and the flattening note adds confusion without 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 output schema and the tool's complexity (multi-parameter, bulk support, legacy context), the description omits critical details: return format, how filters work in 'data', what batch execution entails, and error handling. The agent lacks enough information to use the tool 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 description coverage, the description must compensate. It mentions 'data' for filters but the schema defines 'data' as a string, not a JSON object, causing mismatch. 'account', 'transaction_id', and 'transaction_ids' are barely explained. The agent cannot infer parameter usage or 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?

The description conflates multiple legacy API actions (list_transactions, list_subscriptions, etc.), making it unclear that this tool is specifically for listing subscriptions. The 'Flattened action: list_subscriptions' note is confusing; the agent cannot determine if this tool performs only that action or is a catch-all.

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?

Mentions that this tool activates for legacy keys (ak_…) migrating from V5, which provides some context on when to use it. However, it does not explicitly contrast with sibling tools like 'pagarme_subscriptions_list' (non-legacy) or state when not to use it.

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

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

The description adds significant behavioral context beyond annotations: it reveals the tool supports multiple legacy API versions with raw field differences, accepts bulk transaction_ids, and uses a 'data' JSON parameter for filters. Annotations already declare readOnly, idempotent, and non-destructive, which the description reinforces without contradiction. The additional details (version sharing, bulk, filter mechanism) provide a comprehensive behavioral picture.

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 verbose and mixes Portuguese and English. It lists actions redundantly (e.g., actions list then flattened action note). The bulk support note is useful but could be integrated. The structure is not front-loaded with the core purpose, requiring multiple reads. Could be more concise and structured.

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

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

Given the complexity (4 parameters, no output schema, 0% parameter descriptions), the description is insufficient. It does not explain the return format, pagination behavior, or the exact role of each parameter. The agent lacks details to correctly invoke the tool, especially for 'account' and 'transaction_id'. Annotations help but do not cover parameter usage.

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 explain parameter meanings, but it only partially does so. It explains that 'data' holds list filters (count, page, status) and 'transaction_ids' enables bulk execution. However, 'account' and 'transaction_id' are not explained, and the relationship between parameters (e.g., when to use transaction_id vs transaction_ids) is unclear. This leaves significant ambiguity for the agent.

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 is for reading legacy Pagar.me transactions (V1-V4) and specifies the flattened action as 'list_transactions'. It distinguishes from sibling tools like pagarme_legacy_get_transaction by mentioning the separate get action and from other legacy list tools by naming them. The purpose is specific, actionable, and well-differentiated.

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

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

The description indicates this tool is active when using legacy ak_ keys (accounts not migrated to V5), providing a clear trigger condition. It lists related actions (list_subscriptions, etc.) implying alternatives, but does not explicitly state when to use this tool over siblings or provide when-not scenarios. Context is clear but lacks exclusions.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds important behavior: batch execution via transaction_ids, filtering via data JSON, and raw field differences between versions. 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 verbose and includes a list of multiple unrelated actions (e.g., list_customers, list_transactions) that are not specific to this tool. The flattened action helps, but the clutter reduces 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?

While the description covers legacy context, filtering, and batch support, it lacks details on output format (no output schema) and omits explanation of the 'account' parameter. This leaves some gaps for an agent using the tool.

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

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

The description explains the 'data' parameter for filters (count, page, status) and 'transaction_id'/'transaction_ids' for single/batch access. However, it does not explain the 'account' parameter. With 0% schema coverage, this partial coverage merits a score of 3.

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

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

The description clearly states it is for listing transfers from the legacy Pagar.me API (V1-V4), with the flattened action explicitly indicating 'list_transfers'. This distinguishes it from the modern pagarme_transfers_list 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?

The description specifies when to use this tool: 'Ativa quando a conexão usa uma chave ak_… (contas ainda não migradas pra V5).' This provides clear context, though it does not explicitly mention the modern alternative pagarme_transfers_list.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by detailing the return fields (id, label, version) but does not disclose further behavioral traits like pagination or filtering.

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 Portuguese sentence that is concise, front-loaded with the verb 'Lista', and contains no unnecessary words. Every part 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?

The description covers the basic purpose and return fields, but given the optional parameter and lack of output schema, it falls short on explaining parameter usage and return format (e.g., list structure, pagination). It is adequate but not comprehensive.

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 has one parameter 'account' with no description and 0% schema description coverage. The tool description does not mention this parameter at all, so the agent gains no insight into its purpose or usage.

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 specifies the tool's action: listing Pagar.me accounts (chaves) connected to the install. It states the returned fields (id, label, version) and distinguishes it from siblings that list other entities like cards or charges.

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 provide explicit guidance on when to use this tool versus alternatives. It only describes what the tool does, leaving the agent to infer from the context of sibling tool names.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false already indicate a safe read operation. The description adds that get_many returns { results, errors }, providing behavioral context. However, it does not fully disclose behavior for all parameters (e.g., what happens without order_id).

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

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

The description is somewhat verbose, listing all actions before flattening. It could be more direct about the get action. It is not poorly structured but contains extra information that may distract.

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 has 6 parameters with no descriptions and no output schema, the description provides insufficient context. It omits details on output format (except for get_many), account handling, and the role of data/account 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?

With 0% schema description coverage, the description must compensate. It explains order_id and order_ids, but ignores data, page, size, and account. Only 2 of 6 parameters are described, leaving significant gaps.

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 the tool is for retrieving order details (get and get_many) from Pagar.me V5, with specific mention of 'get: detalhe por order_id' and 'get_many: busca vários por order_ids'. However, it also includes list action, which may cause confusion since sibling tool pagarme_orders_list exists.

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 provide guidance on when to use this tool versus alternatives like pagarme_orders_list or pagarme_orders_get_many. It lists multiple actions but declares '[Flattened action: get]', lacking explicit when-to-use and when-not-to-use instructions.

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 readOnly and idempotent. The description adds key behavioral context: the tool returns a result with 'results' and 'errors' arrays (partial failure), and operates as a batch operation. This exceeds annotation coverage, though no details on authentication or rate limits.

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

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

The description is relatively short but includes irrelevant details about other actions (list, get) that belong to sibling tools. The core get_many description is concise but could be more focused. It mixes languages (Portuguese/English) which may reduce 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 the tool's complexity (6 parameters, no output schema), the description provides the essential purpose and return format but lacks parameter details and context on when to pass each field. It achieves a basic completeness score, but falls short for a production 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?

The description only explains the 'order_ids' parameter and its batch purpose, but the input schema lists 6 parameters (data, page, size, account, order_id, order_ids) with 0% schema description coverage. The description neglects the other five parameters, leaving their meaning unclear. This is insufficient for effective tool 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 clearly states the tool action: 'get_many: busca vários por order_ids (lote, retorna { results, errors })' and distinguishes it from 'list' and 'get' by specifying the method (batch by IDs) and return format.

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 use when needing multiple orders by specific IDs, and mentions the return includes both results and errors. However, it does not explicitly state when to avoid this tool or provide alternatives beyond the brief mention of other actions.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 'lista paginada' but does not explain pagination behavior (defaults, limits) nor clarify that the flattened action is 'list'. The mismatch between described parameters and schema undermines transparency.

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 includes irrelevant details about 'get' and 'get_many' actions, which could be omitted. The note '[Flattened action: list]' is helpful but the description is not front-loaded and contains excessive information for a list-only tool.

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

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

With no output schema and mismatched parameters, the description fails to convey how to use the tool effectively. It does not specify return format, pagination defaults, behavior when optional fields are omitted, or how the 'list' action differs from other order-related tools.

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

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

Schema description coverage is 0%, so the description must explain parameters. However, it does not define any of the input schema properties (data, page, size, account, order_id, order_ids). The listed parameters for list (code, status, etc.) are absent from the schema, providing no useful mapping.

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 conflates three actions (list, get, get_many) but the tool is for 'list' only. The listed parameters for list (code, status, etc.) do not match the input schema properties (data, account, order_id, order_ids), creating confusion about what the 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 mentions sibling actions (get, get_many) but does not provide any criteria for when to use this 'list' tool versus alternatives like pagarme_orders_get or pagarme_orders_get_many. No guidance on context 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 are present but minimal (readOnlyHint=false, destructiveHint=false). The description does not disclose side effects, idempotency, or error conditions beyond the account restriction and action summaries.

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 with bullet points and a note about flattened action. It conveys essential information without excessive verbosity.

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 complexity (multiple actions, bulk support) and lack of output schema, the description provides adequate information for the primary close operation but may not fully cover create/update usage or error handling.

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 description adds meaning to parameters: 'data' is JSON for create/update, 'closed' boolean for close, 'account' restricted to sk_, 'order_id' required for update/close, 'order_ids' for bulk. This compensates for the 0% 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 tool can create, update, or close orders in Pagar.me V5. The naming and 'Flattened action: close' indicate the primary purpose is closing/reopening, but the inclusion of create and update actions adds 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 mentions a restriction to 'sk_' accounts and lists actions with their requirements, but does not provide explicit guidance on when to use this tool versus specialized siblings like pagarme_orders_write_create or pagarme_orders_write_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?

The description discloses that the tool works only with accounts having 'sk_' prefix, supports bulk execution via order_ids, and explains the three actions. However, it does not mention authentication requirements, rate limits, or side effects like whether creations are reversible. Annotations provide no additional safety hints, so the description carries 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 concise, front-loaded with the main purpose, and uses bullet points for actions. However, it mixes Portuguese and English and includes 'Flattened action: create' which adds minor confusion. No wasted sentences.

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 multi-action nature and bulk support well, but lacks explanation of the 'account' parameter and does not describe the return value (no output schema). Given the complexity, it is adequate 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 coverage is 0%, so description must explain parameters. It explains data (JSON for create/update), closed (for close action), order_id (required for update/close), and order_ids (for bulk). However, the 'account' parameter is not explained, leaving a gap. Overall, adds value but 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 states the tool creates, updates, or closes orders (Criar/atualizar/fechar pedidos) and lists specific actions. However, the presence of sibling tools for update and close creates ambiguity about which tool to use, reducing clarity.

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

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

No explicit guidance on when to use this tool versus sibling tools like pagarme_orders_write_update or pagarme_orders_write_close. The description mentions that update and close require order_id but does not advise the agent to use more specific tools when only a single action is needed.

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

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

Annotations indicate non-destructive and non-read-only, but the description does not disclose additional behavioral traits like authentication requirements or error handling. The 'só contas sk_' note adds some context but is incomplete.

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?

Moderately concise, but includes clutter like '[Flattened action: update]' and lacks a clear structure that separates action-specific guidance.

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 complexity (5 parameters, no output schema), the description is incomplete: it does not explain return values, validation rules, or how bulk execution works in detail.

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 description adds meaning for data, order_id, closed, and order_ids, explaining their roles in different actions, but the account parameter is undefined, and with 0% schema description coverage, the explanation is insufficient.

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 creates/updates/closes orders in Pagar.me V5, but the '[Flattened action: update]' note is confusing and there is no differentiation from sibling tools pagarme_orders_write_create and pagarme_orders_write_close.

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

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

Provides some guidance on using create, update, or close based on the operation, but lacks information on when to use this combined tool versus the separate sibling tools for create and close.

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 traits. The description adds 'bulk support' via payable_ids, which is not in annotations, but lacks details on error handling, response format, or other behavioral nuances.

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 messy, mixing Portuguese and English, listing actions redundantly, and including a '[Flattened action: get]' note that adds confusion. Could be condensed and structured better.

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 0 required parameters, no output schema, and 6 parameters, the description lacks details on return values, pagination behavior, error handling, and the role of the 'data' and 'account' parameters. Incomplete for effective tool selection.

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

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

Schema description coverage is 0%. The description explains 'payable_id' and 'payable_ids', and implies 'page' and 'size' for list, but does not explain 'data' and 'account' parameters. Incomplete semantic coverage for a 6-parameter tool.

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 it gets a receivable by payable_id and supports batch via payable_ids, but it confusingly includes a 'list' action that overlaps with the sibling tool 'pagarme_payables_list'. This blurs the tool's specific purpose and does not clearly distinguish it.

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

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

No explicit guidance on when to use this tool versus alternatives like 'pagarme_payables_list'. The description mentions both list and get actions without indicating that list should go to the dedicated list 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and read-only. The description adds behavioral context: it supports bulk execution via payable_ids and lists expected return fields (status, payment_date, type) despite no output schema. 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 relatively concise but includes some redundancy (listing actions then flattening) and mixes Portuguese and English. It front-loads the resource name effectively, but could be structured more clearly.

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?

Provides an overview of actions and bulk support, mentions pagination (page, size) and some return fields. However, lacks details on the 'account' parameter, sorting, filtering, and does not clarify the relationship with the sibling get tool. Adequate but not fully complete for a 6-parameter tool.

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

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

With 0% schema description coverage, the description must compensate. It partially explains page, size, payable_id, and payable_ids, but the 'data' parameter is confusingly described as output fields rather than an input string. The 'account' parameter is not mentioned at all. This leaves significant gaps in understanding parameter usage.

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 is for listing payables (recebíveis) in Pagar.me V5, with explicit sub-actions for list and get. However, the presence of a sibling tool 'pagarme_payables_get' creates ambiguity about when to use this tool vs that one, and the description does not differentiate 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?

No explicit guidance on when to use this tool versus alternatives like pagarme_payables_get or legacy list tools. The mention of 'Bulk support: accepts payable_ids for batched execution' implies a use case for multiple IDs, but does not cover when to use list vs get or exclude other scenarios.

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 'Irreversível' (irreversible) beyond the destructiveHint=true annotation, and notes 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?

Two concise sentences with key info front-loaded: operation, requirement, irreversibility, bulk support. No extraneous 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?

Covers essential aspects for a simple destructive tool: purpose, required param, irreversibility, bulk. Missing details like return value or impact on subscriptions, but acceptable given simplicity and no output schema.

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

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

Description explains plan_id as required and plan_ids for bulk execution (2 of 3 params), but does not mention the 'account' parameter. With 0% schema coverage, the description partially compensates.

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 'Remove um plano' (delete a plan), specifies the API version (V5), and distinguishes from sibling tools like create, update, get, and list. The verb 'remove' and resource 'plano' are unambiguous.

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

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

Description mentions required plan_id and bulk support with plan_ids, but does not explicitly state when to use this tool versus alternatives (e.g., updating a plan instead). Usage is implied but no direct guidance.

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