Banco MCP

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

Annotations already mark the tool as destructive (destructiveHint=true, readOnlyHint=false). The description adds valuable behavioral details: 'The bank's data will no longer be available' and 'Returns an add_connection_url to re-connect if needed'. This goes beyond the annotations by explaining consequences and recovery, giving the agent a clearer picture of the operation's impact.

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

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

The description is only two sentences, front-loaded with the primary action. It explains both what the tool does and a key recovery mechanism (the returned add_connection_url). Every sentence earns its place, with no redundant or vague phrasing.

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

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

The tool is simple (1 parameter, no output schema), but the description covers the effect and return value. However, the critical parameter 'item' is unexplained, and there is no mention of prerequisites (e.g., existing connection) or edge cases (e.g., already disconnected). While the behavioral context is good, the missing parameter details prevent this from being fully complete.

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

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

The input schema has one required parameter 'item' (string) with no description coverage. The description mentions 'a specific bank' but never explains what 'item' should be (e.g., bank ID, connection ID, item ID). With 0% schema coverage and no parameter explanation in the description, the agent cannot confidently determine the correct value to pass. This is a significant 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 uses the specific verb 'Revokes' and clearly states the resource: 'Open Finance consent for a specific bank' and 'deletes the connection data'. This distinguishes it from all sibling tools, which are focused on reading or updating data. There is no ambiguity about what this tool 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 provides clear context: this tool is used when you need to revoke consent and delete a bank connection. However, it does not explicitly mention alternatives or when not to use it. The context is sufficient for most cases, but lacks explicit exclusions or cross-references to sibling tools.

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

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

The description goes far beyond the sparse annotations by disclosing the polling mechanism, 60s timeout, return structure, `timed_out` flag, `needs_action` with reconnect_url, and the effect of `wait: false`. This provides complete behavioral transparency without contradicting any annotations.

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

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

Although the description is longer than average, every sentence carries essential operational detail—from the immediate action to return handling, error scenarios, and sync modes. It is front-loaded with the core purpose and structured in a logical flow that avoids redundancy.

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

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

Given no output schema, the description thoroughly documents the response shape (`{ results, errors }`, status fields, `lastUpdatedAt`, `synced`, `reconnect_url`, `timed_out`) and error recovery. Combined with parameter semantics and usage guidance, it provides everything an agent needs to invoke and interpret 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 description coverage is 0%, but the description fully compensates: it explains `items` as an array of selectors (item_id, connector_id, connector_name, custom_label) and that omitting it syncs all. It also defines `wait: false` behavior, enriching the minimal boolean schema with actionable semantics.

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

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

The description opens with a specific verb and resource: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish' with an explicit HTTP method and polling behavior. It clearly distinguishes from sibling tools like openfinance_get_item_status by explaining it triggers a sync rather than just reading 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?

Explicit guidance is given: 'Use this when a balance or transaction list looks stale' and it contrasts with disconnecting/reconnecting. It also instructs to check openfinance_get_item_status on timeout and explains the `wait: false` fire-and-forget alternative, covering both when and when-not 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?

Despite annotations already declaring readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral nuance: the snapshot freshness semantics, credit-account error variants, degradation behavior with warnings instead of throwing, and the response shape. This goes well beyond what annotations provide and contains 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 long but dense and front-loaded with the core behavior and endpoint. Every sentence adds operational value, especially around error handling and freshness. It loses a point for being a wall of text that could benefit from light formatting or shorter sentences, but it is not padded.

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

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

With no output schema, the description compensates by stating the response shape explicitly: '{ results: [...], errors: [{ id, status, message }] }'. It also covers error cases, degradation, consent failures, and the relationship to force_sync, making the tool safe and actionable 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?

The input schema provides only param name and type with no description coverage, so the description carries the burden. It adds the key constraint that account_ids must be an array of 1–50 and clarifies it relates to per-account balances. It could be slightly stronger by pointing to openfinance_list_accounts as the source for IDs, but the parameter meaning is sufficiently conveyed.

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

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

The description opens with a specific verb and resource: 'Returns the latest available balance per account id' and identifies the exact endpoint GET /accounts/:id/balance. It clearly separates this from transaction listing and other Open Finance tools by focusing on balance snapshots per account.

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

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

The description gives explicit when-to-use guidance: it explains that this is a snapshot tied to the last sync, and tells the agent to run openfinance_force_sync and re-read if the balance is stale or disagrees with openfinance_list_transactions. It also constrains account_ids to an array of 1–50, which is concrete invocation guidance.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses critical context: the `{ results, errors }` batch shape, the potential `provider_incident` block, and a clear warning that values may be unreliable during provider incidents and should not be presented as real. This adds significant value beyond structured annotations.

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

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

The description is compact and front-loaded with the main return value, followed by usage and a caveat. Every sentence contributes; the provider incident explanation is somewhat detailed but necessary for safe use.

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

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

For a one-parameter read tool with no output schema, the description is remarkably complete: it specifies the endpoint, batch shape, response envelope, and a critical edge case (provider incidents). It leaves little ambiguity about what to expect.

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

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

Schema coverage is 0%, so the description carries the burden. It explicitly states to pass `account_ids` as an array with a 1–50 limit, adding meaning beyond the bare schema. It does not detail each element's type beyond implicit ID, but that's sufficient for the single 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 explicitly states 'Returns full account objects including extended creditData (additional cards, limits) per id', a specific verb+resource that clearly distinguishes from siblings like list_accounts or get_account_balance. The batch shape and per-id behavior further define 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 gives clear context: use when you need full account details for specific IDs, with the instruction to pass account_ids as an array (1–50). It does not explicitly name alternatives or exclusions, but the sibling set and the phrase 'full account objects... per id' imply when this is appropriate.

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

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

Annotations already signal read-only, idempotent, non-destructive. The description goes far beyond that, disclosing that transactions are not in the bill payload and require an extra scan, that transactions_basis may be an estimate, that bill totalAmount is authoritative, that payments[] refers to the previous bill's payment, and that Pluggy returns no paid/status field. This gives the agent strong behavioral grounding.

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, yet every sentence carries material decision-making weight: return shape, opt-in consequences, authoritative fields, known limitations, alternative routes, and required calls. It is front-loaded with core output and progressively adds caveats, so it remains to learn.

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 no-output-schema tool, this description provides a surprisingly complete contract: request semantics, response fields, batch shape with results and errors, edge-case behavior for open bills, estimate sources, paid-status guidance, cost considerations, and aliases. Nothing essential is missing for an agent to select and invoke 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?

Schema description coverage is 0%, and the description compensates for most parameters: bill_ids as an array, account_id required for include_transactions, include_transactions as opt-in, plus caveats about their meanings. The only missing semantic coverage is transactions_detail and its enum (compact/rich/raw); the values are self-describing, but the description does not connect them to the include_transactions flow.

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

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

The description opens with a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)' and lists the returned fields. It clearly identifies itself as a detail-fetching tool for a known bill id and is easily distinguishable from siblings like openfinance_list_credit_card_bills.

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

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

The description gives explicit guidance: use openfinance_list_credit_card_bills first to discover ids, prefer openfinance_list_credit_card_bills for paid status, and use openfinance_list_transactions for fetching transactions separately. It also explains when the include_transactions opt-in is useful and not necessary, making the tool's place among siblings unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: the meaning of the returned reconnect_url (reopens widget in UPDATE mode for re-auth/MFA without disconnecting or consuming a slot), the response shape for bulk queries (`{ count, items }`), and the status value examples. This goes beyond what annotations convey.

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

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

The description is front-loaded with the primary purpose and packs return-field details, single/all behavior, and bulk support into three sentences. There is no redundant or filler content; every sentence adds necessary information.

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

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

With no output schema, the description sufficiently covers return values and special behaviors (reconnect_url, count/items). However, the unexplained `item_id` parameter and lack of explicit guidance on when to prefer this over sibling read tools (e.g., list_connections) leave minor completeness 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?

The description explains `item` (single vs. all) and `item_ids` (bulk), but the input schema has 0% coverage and the description completely omits `item_id`, leaving its relationship to `item`/`item_ids` unclear. This is a meaningful gap for an agent deciding which parameter to populate.

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

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

The description uses a specific verb ('Returns the current status') and clearly identifies the resource ('a bank connection'). It also distinguishes the tool's scope: status with executionStatus, connector metadata, and reconnect_url, plus single/ALL/bulk modes, separating it from sibling list tools.

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

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

The description gives clear context for when to use the tool: omit `item` for all linked banks, pass `item` for a single bank, and use `item_ids` for batched execution. It does not explicitly name alternatives or exclusions relative to sibling tools, but the usage contexts are unambiguous.

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, so the safety profile is known. The description adds valuable behavioral context beyond annotations, including the batch response shape '{ results, errors }' and the array size limit of 1-50, which helps the agent anticipate error handling and payload constraints.

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

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

The description is dense but efficient, starting with the core action and then listing return fields. The field enumeration is somewhat long, but each item conveys needed output structure with no fluff, earning a strong score.

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 fully specifies the return values, including interestRates, charges, payments, warranties, installments, and batch shape. It also covers usage context and constraints, making it complete for a single-parameter read-only 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 the description must compensate. It does by explaining that `loan_ids` are the identifiers and specifying the array limit '1-50.' This adds practical meaning beyond the bare schema type of array of strings.

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

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

The description clearly states the tool's purpose: 'Returns full loan contract detail by id' with the specific endpoint GET /loans/:loanId. It distinguishes the tool from siblings like openfinance_list_loans by focusing on detailed contract data rather than a list of loans.

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

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

The description explicitly instructs to 'Use after openfinance_list_loans to deep-dive on a specific contract,' naming the sibling tool and the intended workflow. This provides clear when-to-use guidance and implies an alternative usage pattern.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behavioral nuances: `balance` semantics for CREDIT are connector-dependent, `balance_notice` means the balance was reported as zero despite an outstanding amount, `bankData` fields can lag after connection creation, and `provider_incident`/`identity_notice` can make values unreliable or require deduplication. This is far beyond what the annotations alone convey.

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

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

The description is long but carefully organized: purpose first, then usage modes, then important behavior caveats, then bulk support. Every section addresses a behavior or decision the agent needs, and the most critical scoping guidance ('OMIT item...', 'Pass item...') is front-loaded rather than buried at the end.

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 must compensate by explaining the shape and meaning of the response. It does so thoroughly, covering aggregated results, per-row tagging, credit-card balance issues, provider incidents, identity notices, and stale bankData. For a tool with this many edge cases, the description is complete enough for an agent to call it correctly and interpret results safely.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains `item` (omit for all banks, pass to target a single bank), implies `type` semantics by describing BANK and CREDIT, and explains `item_ids` bulk support. However, the `item_id` parameter is not explicitly described as an input, even though it appears in the schema, so the coverage is not fully 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 returns accounts for a bank connection, specifying BANK and CREDIT account types and the fields returned (balance, number, type, subtype, bankData, creditData). It also distinguishes itself from related tools by directing users to openfinance_list_credit_card_bills for standardized bill amounts, and the resource being acted on is explicit and specific.

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

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

The description gives explicit usage guidance: omit `item` to list accounts across all linked banks when the user says 'my accounts/cards' without naming a bank, and pass `item` to target a single bank. It also recommends openfinance_list_credit_card_bills for standardized open-bill amounts and when `balance_notice` is present, which clearly routes the agent to the correct alternative.

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

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

Annotations already provide read-only, idempotent, non-destructive hints. The description adds valuable context: the data is cached per adapter session, the response is a single aggregated result with no batch ids, and each entry contains specific fields (id, description, descriptionTranslated, parentId, parentDescription). This goes beyond the annotations without contradicting them.

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

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

The description is concise—two sentences—and front-loaded with the main purpose. It packs essential details (endpoint, fields, caching, Portuguese translation preference, no batch ids) without verbose or redundant wording. 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?

For a zero-parameter, read-only list with no output schema, the description fully compensates by describing the response shape and fields. It also mentions caching and the relationship to update_transaction_category, making it self-contained. No critical contextual gaps remain.

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

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

The tool has zero parameters, so the input schema covers everything (100% coverage vacuously). The baseline for 0 params is 4, and the description appropriately focuses on the response fields rather than parameters. It adds meaning to the output, not the input, which is acceptable here.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy, with a specific verb ('Returns') and resource. It also distinguishes itself by noting the `id` field is used by openfinance_update_transaction_category, linking it to a sibling tool and clarifying its specific role among the list tools.

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

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

It conveys usage context by mentioning the cache for the adapter session, suggesting repeated use without refetch, and advises preferring `descriptionTranslated` for pt-BR users. While it doesn't explicitly say 'when not to use' alternatives, the sibling list makes it clear this is the only category taxonomy tool, so guidance is adequate.

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, non-destructive, idempotent behavior. The description goes beyond by explaining the widget's UPDATE mode, that reconnection refreshes in place, and that no connection slot is consumed. This adds meaningful context about side effects and safe usage.

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, but the first sentence lists the returned data and the second explains the reconnect behavior. Every phrase carries useful information, and the structure is efficient despite its length.

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 no parameters and no output schema, the description fully explains what the tool returns and the purpose of each URL. It also covers edge cases like re-authentication and stale data, making it complete for an agent to use correctly.

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

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

The tool has zero parameters, so the description doesn't need to explain parameter semantics. According to the rubric, 0 params warrants a baseline of 4. The description adds no parameter info because none exists, but the empty schema is fully covered.

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 exactly what the tool does: 'Returns the saved bank connections for this install' and enumerates the returned fields. It clearly distinguishes this from sibling tools that list accounts or transactions, as it's focused on bank connections and the associated URLs.

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 returned reconnect_url (for re-authentication issues like MFA, LOGIN_ERROR, stale data) and clarifies that it doesn't consume a connection slot or require disconnecting. However, it doesn't explicitly name alternative tools for when not to use this tool, so it stops short of a 5.

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

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

Beyond the readOnlyHint annotation, the description discloses critical behavioral semantics: Pluggy does not return a paid/status field, payment placement depends on cycle dates, payment_status derivation rules, connector asymmetry for open bills, and a warning instead of failure when CREDIT_CARDS is not enabled. These details are not available in annotations or schema.

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

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

The description is long but well-structured with bolded sections (e.g., IMPORTANT, OPEN BILL & TOTAL DEBT, CONNECTOR ASYMMETRY) and front-loaded with the core purpose. Every sentence adds substantive caveats or clarifications, though some redundancy exists (e.g., repeated emphasis on not summing by billId). It is dense but appropriate for the tool's complexity.

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

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

Given there is no output schema, the description must explain return values, and it does comprehensively: lists all fields, explains payment_status legend, open_bill structure, future_bills, account echo, and warning behavior. It also covers edge cases like unreliable billId grouping and connector asymmetries, making it complete for effective invocation and interpretation.

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 thoroughly explains include_open_bill (opt-in, derived fields, fallback behavior) and account_ids (bulk support), which are non-obvious. However, page/page_size are not mentioned, though they are standard pagination parameters. With 0% schema description coverage, this partial compensation is good 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 opens with 'Returns CLOSED credit card bills for a CREDIT-type account', clearly stating the specific verb, resource, and account type. It also distinguishes from sibling tools by explicitly noting it provides bill-level summaries and pointing to openfinance_list_transactions for itemized 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 gives explicit when-to-use guidance: 'To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id' and warns about billId inconsistencies. It also provides cross-bank caution ('ALWAYS cross-check the echo against the card you intended to query') and explains when open_bill is unavailable, with reasons.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description richly discloses behavior: returns a structured warning object instead of throwing, and details the data-integrity zeroing detection with integrity:'suspect_zeroed' flags. This is substantial added context that annotations do not provide, and no contradictions exist.

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

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

The description is dense but every sentence adds value: purpose, fields, error fallback, data integrity rule, and bulk support. It is well-structured with clear sections and front-loads the core function. Given the complexity, length is justified.

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 explains the return shape ({ total, results, warning }), row fields, error handling, and integrity flags. However, pagination behavior (page/page_size) and parameter mapping are not covered, leaving some gaps for a complex tool. Still, most operational context is present.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only mentions item_ids for bulk execution and never explains item, page, type, item_id, or page_size. The enum values for type are undocumented. This is a significant gap for a 6-parameter tool, though the bulk note earns a little credit.

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 an investment portfolio for a connection, enumerating specific asset types (FIIs, stocks, ETFs, fixed income, etc.). This distinguishes it from sibling tools like list_investment_transactions and list_accounts. The verb 'returns' and resource 'investment portfolio' are specific and unambiguous.

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

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

The description provides clear context: use for a connection with INVESTMENTS product enabled, and explains fallback behavior when not enabled. It does not explicitly name alternatives or exclusions, but the context is sufficient to guide selection among sibling list tools. Missing an explicit 'use this instead of...' keeps it from a 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds valuable behavioral context by enumerating return fields (quantity, value, netAmount, itemized expenses) and movement types, plus bulk execution support. No contradictions with annotations.

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

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

The description is concise and well-structured: purpose stated first, then return details, then usage prerequisite and bulk support. Every sentence adds value, with no redundant or vague wording.

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 no output schema, the description provides sufficient context: purpose, movement types, field list, prerequisite for investment_id, and bulk option. It could mention pagination behavior or error handling, but the core information needed for invocation is present.

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

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

Schema description coverage is 0%, so the description must compensate. It explains investment_id (used to specify position) and investment_ids (bulk support), but does not mention page/page_size parameters. Since pagination params are common but still undocumented, this is adequate but 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 the tool's function: 'Returns the movement history for a specific investment position' with specific movement types (BUY/SELL/TAX/etc.), which is a specific verb+resource. It distinguishes from siblings like list_investments and list_transactions by focusing on investment position history and referencing investment_id.

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

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

Explicitly provides usage context: 'Use after openfinance_list_investments to get the investment_id' and mentions bulk support for batched execution. This gives clear when-to-use guidance and a prerequisite, though it doesn't explicitly state when not to use or compare with list_transactions.

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

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

Beyond the readOnly/idempotent hints, the description adds meaningful behavior: sequential queries with rate-limit spacing, and the return format `{ results, errors }` per connection. This is valuable context not present in annotations.

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

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

Three sentences pack purpose, parameter usage, and return format with zero filler. The description is efficiently front-loaded with 'Lists loan contracts per bank connection' and each subsequent sentence adds necessary detail.

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

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

Given the single optional parameter and no output schema, the description is complete: it explains the parameter, the two invocation modes, and the response shape. Sibling tools for details and other lists are easily differentiated by the clear 'Lists loan contracts' scope.

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

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

The schema only shows `items` as an array of strings, but the description explains that each string is a connection selector (item_id uuid, connector_id, or connector_name) and how multiple entries affect behavior. This fully compensates for the 0% schema description 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 lists loan contracts, scoped per bank connection, with the option to list across all linked banks. The verb 'Lists' is specific, and the resource 'loan contracts' is unambiguous, distinguishing it from detail-oriented siblings like get_loan_detail.

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 is given for both usage modes: pass `items` for specific connections, and omit it to list all banks. The description also clarifies that multiple connections are queried sequentially with rate-limit spacing, which is practical usage context.

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

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

This description discloses a great deal beyond the annotations: automatic pagination behavior, the 5000-transaction ceiling, descending date ordering, scheduled future rows, truncated responses, per-connector variability, upstream error response shape, and provider incidents. The annotations declare readOnlyHint=true and idempotentHint=true, and the description does not contradict them.

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

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

The description is long but front-loaded with purpose and organized by recurring caveats, warnings, and alternatives. There is some redundancy around billId and credit-card bill reconstruction, and the same Nubank example appears more than once. For this tool's complexity, the length is mostly justified, but tighter edits would make it even easier 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?

There is no output schema, so the description must explain both inputs and expected returns. It covers the account echo block, list fields, scheduled_count/notice, truncated:true, totalPages, error fallback shape, provider_incident, and upstream variability. After reading this description, an agent has enough context to select the correct account, mode, and pagination strategy.

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 8 parameters and 0% schema description coverage, so the description carries most of the burden. It does well by explaining from/to, search_queries, page, page_size, and the detail enum with concrete semantics. However, it does not explicitly explain the account_ids parameter, and account_id is mostly implied through the response echo block rather than directly documented as an input.

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

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

The description opens with a precise statement: 'Returns transactions for a bank account (BANK or CREDIT type)' and clarifies that for CREDIT accounts it is the ONLY way to get itemized transactions. This gives a clear resource, a specific verb, and enough scope to distinguish it from related bill-level and account-level tools.

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

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

The description is explicit about when to use this tool versus alternatives: use openfinance_list_credit_card_bills for standardized bill totals/due dates, openfinance_list_accounts for closing/due dates, and openfinance_get_item_status or openfinance_force_sync for credit sync health. It also gives concrete guidance about pagination modes and detail levels, so an agent knows exactly when each path is appropriate.

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

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

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds significant behavioral context: the 5000/account scan cap with truncated:true flag, the provider_incident block indicating potentially incomplete/wrong data, and the note that reconnecting will not resolve incidents. This goes well beyond the structured 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?

Though lengthy, every sentence adds value. The description is front-loaded with the core purpose, then progressively details parameters, use cases, output shape, edge cases, and bulk support. No filler or redundancy; the structure makes a complex tool comprehensible.

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

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

Given 9 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains the return structure (total entradas/saídas/saldo_liquido, por_mes, top_despesas, top_recebimentos, by_account), the truncation behavior, provider incidents, and bulk execution. This is fully sufficient for an agent to select and 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?

With 0% schema description coverage, the description carries full responsibility for explaining parameters. It explicitly covers item (connector_id, connector_name, or item_id; omit for all banks), from/to as ISO dates, granularity (monthly vs raw), detail (compact/rich/raw), type filtering, and item_ids for bulk. top_n is implied via 'largest N each' for top_despesas/top_recebimentos. This is thorough and adds meaning beyond the raw 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 opens with a clear, specific verb+resource: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It further explains that it resolves accounts internally and fans out transactions, distinguishing itself from openfinance_list_accounts and openfinance_list_transactions by noting that no prior account listing or account_id carry-over is needed.

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 usage guidance is provided: 'Use this for análise anual/mensal, fluxo de caixa, entradas e saídas, maiores gastos/recebimentos.' It also clarifies when to choose compact vs raw granularity and when to enrich with detail='rich'. The statement that you do NOT need to call openfinance_list_accounts first clearly positions this tool relative to siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by detailing what the tool returns (global indicator, degraded components, open incidents, and `your_banks_affected`) and explaining how to interpret the results, going 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 a single, dense paragraph that includes all necessary information without fluff. Although somewhat long, every sentence serves a purpose, covering purpose, usage context, and return values. It is well-structured and front-loaded with the core purpose.

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

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

Despite having no output schema, the description explicitly lists the return fields and explains how to use them. It also addresses the tool's role relative to sibling tools and provides a clear decision framework for when to use it. The description is comprehensive for 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 tool has zero parameters, so the input schema is empty. The description does not need to explain parameters. It compensates by clearly explaining the tool's output and its relevance, meeting the baseline for parameterless tools.

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 checks the LIVE operational status of the Open Finance provider's public status page, distinguishing it from the connection-specific `openfinance_get_item_status`. It uses a specific verb and resource, leaving no ambiguity about 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 explicitly explains when to use this tool (when data appears incomplete/stale despite an updated connection) and contrasts it with `openfinance_get_item_status`, effectively guiding the user to choose the correct tool. It also states the practical benefit of distinguishing provider-side problems from connection issues.

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 valuable behavioral context beyond the readOnly/idempotent annotations: it discloses that missing keywords returns a hint rather than dumping catalog, that results vary by user plan, and that some connectors carry a caveat warning. This goes beyond the annotations' safety profile and informs the agent of dynamic result shaping.

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 dense paragraph but every sentence contributes essential information (purpose, return fields, caveats, plan logic, usage timing, required parameter). It is efficiently written though could benefit from a bulleted breakdown for even easier scanning; still, it is appropriately sized for the tool's complexity.

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 absence of an output schema and the tool's nuanced behavior (plan-based filtering, caveats, required keywords), the description covers all necessary aspects: return values, error handling for missing keywords, plan logic, and a clear call-to-action. The context makes it fully actionable for an agent to select and invoke 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 zero schema description coverage, the description compensates fully: it explains `keywords` with an example array and clarifies it is required despite the schema not marking it so; it also explains `include_accounts` controls whether linked accounts are returned. Both parameters are given practical meaning beyond type definitions.

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 'Searches the available bank connectors by name', specifying the verb, resource, and purpose. It details the return fields (connector id, access, audience, connect_url) and distinguishes this tool from siblings by focusing on connector search and connect_url generation, unlike other tools that handle connections, accounts, or transactions.

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

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

The description explicitly instructs to 'Call this BEFORE connecting', providing clear context for when to use it. It also explains plan-based behavior (PF/PJ) and how to handle caveats. However, it doesn't explicitly name alternative tools for other situations, though the 'before connecting' directive implies a separation from post-connection tools.

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

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

Annotations only indicate readOnlyHint=false and destructiveHint=false; the description adds critical behavioral context: it overrides Pluggy's automatic categorization, teaches Pluggy by creating a rule, and defines batch error semantics (per-item errors don't fail the whole batch). This goes well beyond the structured fields.

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

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

The description is dense and front-loaded with the core action, then covers usage and output. It's longer than typical but every sentence provides necessary information for correct invocation, though it could be tightened slightly without losing 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?

For a batch mutation tool with side effects, the description covers input format, ID sources, side-effect behavior, and batch response structure. With no output schema, this level of detail is essential and fully sufficient for an agent to select and 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?

The schema has no descriptions for the nested fields, but the description fully explains the items array structure, required fields, and their provenance. It even describes the exact batch response shape, compensating entirely for the lack of schema descriptions and output schema.

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

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

The description states a specific verb ('corrects') and resource ('category of one or more transactions') and references the PATCH endpoint, clearly distinguishing it from sibling list-only tools like openfinance_list_transactions. It also notes the override and learning behavior, leaving no ambiguity about what the tool 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 explicitly tells when to use it (fix miscategorized transactions, improve future categorization) and identifies where to get required IDs from sibling tools (openfinance_list_transactions and openfinance_list_categories). It also explains the side effect of creating a Category Rule, so the agent understands long-term implications.

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