Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.7/5 across 19 of 19 tools scored. Lowest: 4/5.
Most tools target distinct resources/actions, but a few pairs (list_accounts vs get_accounts_detail, list_transactions vs list_transactions_by_item) have overlapping purposes that rely on descriptions to disambiguate. The descriptions are thorough, preventing major confusion.
All tools share the openfinance_ prefix and follow a consistent verb_noun snake_case pattern (list_accounts, get_account_balance, force_sync). Minor qualifiers like _by_item are used consistently and do not break the pattern.
The 19 tools are slightly above the ideal 3-15 range, but the domain is broad (connections, accounts, transactions, bills, loans, investments, categories, provider status). Each tool has a distinct role, making the count justified.
The surface covers the full read cycle plus relevant actions: connection lifecycle, account/transaction retrieval, credit card bills with derived status, loans, investments, categories, and provider health. No obvious dead ends for common banking queries.
openfinance_disconnect_bankARevokes the Open Finance consent for a specific bank and deletes the connection data. The bank's data will no longer be available. Returns an add_connection_url to re-connect if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes |
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.
openfinance_force_syncAInspectForces the bank to re-sync one or more connections NOW and WAITS for it to finish (PATCH /items/:id, then polls until the item stops updating, up to ~60s). Use this when a balance or transaction list looks stale: a connection can read UPDATED yet be hours old, and this pulls fresh data WITHOUT disconnecting/reconnecting. Pass items as an array of selectors (item_id, connector_id, connector_name, or the user-set custom_label nickname); OMIT items to sync ALL linked banks. Returns { results, errors }; each result has the final status, executionStatus, lastUpdatedAt (advances when data is refreshed), and synced (true = fresh data is ready). needs_action (e.g. MFA_REINTERACTION / LOGIN_ERROR / WAITING_USER_INPUT) means the user must re-authenticate — those results include a reconnect_url that opens the widget in UPDATE mode for that exact connection (user enters credentials / MFA token, data refreshes in place, no slot consumed, no disconnect needed). timed_out: true means the sync is still running — re-check with openfinance_get_item_status. Set wait: false for fire-and-forget (returns immediately while UPDATING).
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | ||
| items | No |
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.
openfinance_get_account_balanceAReturns real-time balance payload per account id (GET /accounts/:id/balance). Pass account_ids as an array (1–50). CREDIT accounts may return Pluggy BALANCE_FETCH_ERROR — those rows include a structured warning instead of throwing. When the financial institution is temporarily unavailable upstream (5xx) or the connector is not Open Finance, the row DEGRADES to the last-synced balance with realtime: false, updatedAt and a warning instead of an error. Response shape: { results: [...], errors: [{ id, status, message }] }.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral detail beyond that: handling of CREDIT accounts with BALANCE_FETCH_ERROR warnings, degradation to last-synced balance with realtime:false on 5xx or non-Open Finance connectors, and the structured response envelope. This far exceeds annotation coverage.
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 well-structured sentences: the first states the core purpose and endpoint, the second covers the parameter constraint, and the third discloses edge cases and response shape. Every sentence adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one simple parameter, no output schema, and read-only annotations, the description thoroughly covers usage, error/degradation modes, and return envelope. It is more than complete 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?
The schema has only `account_ids` with no description (0% coverage). The description compensates by specifying it must be an array and explicitly stating the 1–50 item limit. It also clarifies that they are account IDs, adding 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 opens with 'Returns real-time balance payload per account id (GET /accounts/:id/balance)', specifying a clear verb, resource, and scope. It distinguishes itself from sibling tools like openfinance_get_accounts_detail and openfinance_list_accounts by focusing on balance retrieval for specific account IDs.
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 context: when real-time balances for specific account IDs are needed, and even mentions constraints like array size and CREDIT account behavior. However, it does not explicitly name alternatives or state when to prefer other tools, so it falls just short of full usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_accounts_detailAReturns full account objects including extended creditData (additional cards, limits) per id (GET /accounts/:id). Pass account_ids as an array (1–50). { results, errors } batch shape. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: credit limits and balances may be unreliable (e.g. a limit near 1,00) until the provider recovers. Do not present those values as real.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes |
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.
openfinance_get_credit_card_billAReturns bill-level detail for one or more credit card bills by id (GET /bills/:id): financeCharges and payments[] (id, paymentDate, amount, valueType, paymentMode). Does NOT return individual transactions — to get itemized credit card transactions (purchases, subscriptions, etc.), use openfinance_list_transactions with the credit card account_id and a from/to date range matching the bill's billing cycle (approximately dueDate − 30d to dueDate); each transaction MAY carry a creditCardMetadata.billId hint toward its bill, but it's sparse/inconsistent on some connectors (e.g. Nubank), so do NOT reconstruct a bill total by summing transactions by billId — the bill's own totalAmount is authoritative. Pass bill_ids as an array — use openfinance_list_credit_card_bills first to discover ids. { results, errors } batch shape. NOTE: Pluggy does NOT return a paid/status field. In Brazilian Open Finance, payments[] reflects payments registered during THIS bill's billing cycle — typically the payment of the PREVIOUS bill (do NOT assume this bill was paid just because payments[] is non-empty). To check paid status, prefer openfinance_list_credit_card_bills which derives payment_status via cross-bill match.
| Name | Required | Description | Default |
|---|---|---|---|
| bill_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds significant context: the payments[] semantics (previous bill), the sparse creditCardMetadata.billId on Nubank, the absence of paid/status field in Pluggy, and the authoritative totalAmount. Also discloses the { results, errors } batch response shape.
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 each sentence adds essential information. It is front-loaded with the core purpose, then covers exclusions, alternatives, parameter discovery, and critical payment semantics caveats.
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 explains the return structure (financeCharges, payments[] with fields, { results, errors }) and addresses edge cases (sparse billId, payment interpretation, paid status). It is contextually complete for a complex financial data 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 schema has 0% description coverage, so the description carries the burden. It instructs to pass bill_ids as an array and to use openfinance_list_credit_card_bills first to discover ids, which adds practical semantics beyond the raw schema type.
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 returns bill-level detail for credit card bills by id, listing financeCharges and payments[] fields, and immediately distinguishes itself by noting it does NOT return individual transactions, directing to openfinance_list_transactions. This provides a specific verb+resource+scope and differentiates from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: use openfinance_list_credit_card_bills first to discover ids, use openfinance_list_transactions for itemized transactions, and prefer openfinance_list_credit_card_bills for paid status. It also explains the batch shape and the caution about payments[] representing previous bill payments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_item_statusAReturns the current status of a bank connection (UPDATED, UPDATING, LOGIN_ERROR, etc.), its executionStatus, connector metadata, and a reconnect_url that reopens the widget in UPDATE mode for that connection (re-authenticate / enter MFA token in place, without disconnecting and without consuming a connection slot). Omit item to get the status of ALL linked banks at once (returns { count, items }); pass item for a single bank.
Bulk support: accepts item_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| item_id | No | ||
| item_ids | No |
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.
openfinance_get_loan_detailAReturns full loan contract detail by id (GET /loans/:loanId): interestRates[] (taxType, ratePercentage, indexer), contractedFinanceCharges[], balloonPayments[], warranties[], installments schedule (installmentsCount, paidInstallments, numberOfInstallmentsRemaining, installmentFrequency), amortizationScheduled, CET, ipocCode and dates. Use after openfinance_list_loans to deep-dive on a specific contract. Pass loan_ids as an array (1-50). { results, errors } batch shape.
| Name | Required | Description | Default |
|---|---|---|---|
| loan_ids | Yes |
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.
openfinance_list_accountsAReturns accounts for a bank connection: BANK (checking/savings) and CREDIT (credit card) with balance, number, type, subtype, bankData, and creditData. Also returns bank (the brand/connector name like 'Nubank Empresas' — same shown in the dashboard UI) and connector_id. Note: each account's name is the legal entity that issues the account (e.g. 'Nu Pagamentos S.A. - Instituição de Pagamento'), which is not the same as the brand — when referring to the bank in user-facing text, use bank. OMIT item to list accounts across ALL linked banks at once — the response aggregates every connection's accounts into results, each row tagged with its own bank/connector_id/item_id (use this when the user asks for 'my accounts/cards' without naming a bank). Pass item to target a single bank (response carries bank/connector_id/item_id at the root). CREDIT (credit card) balance: its meaning is CONNECTOR-DEPENDENT — some banks report the current open-bill partial, others the full revolving/installment debt — so do NOT treat balance as 'this month's bill'. The open billing cycle is defined by creditData.balanceCloseDate (when it closes) / balanceDueDate (when it's due). For a standardized open-bill amount and total debt that mean the same across connectors, use openfinance_list_credit_card_bills (open_bill + total_pending_debt, derived from PENDING transactions); closed bills come from that same tool's results. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a bank in this response: balances and credit limits may be unreliable (incomplete or wrong, e.g. a credit limit near 1,00) even with the connection UPDATED, until the provider recovers. Do not present those values as real. May include an identity_notice when the SAME account (same number) arrives via two connections stamped with DIFFERENT owner/taxNumber: in Open Finance those fields reflect each connection's CONSENT HOLDER (e.g. a joint account consented by both holders), so dedupe by account number before summing balances and do not attribute ownership by owner/taxNumber for those accounts.
Bulk support: accepts item_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| type | No | ||
| item_id | No | ||
| item_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint/idempotentHint annotations, disclosing connector-dependent balance semantics, the distinction between `name` and `bank`, provider incident warnings, identity notice deduplication rules, and bulk execution support. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with the core purpose and then structured into distinct behavioral notes. Each paragraph adds meaningful operational context, though a few clauses could be tightened 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?
With no output schema, the description compensates fully by detailing return fields, response structure for aggregated vs. single-item calls, credit card balance nuances, incident/notice handling, and fallback tool guidance. It is comprehensive enough for an agent to invoke and interpret results 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?
Despite 0% schema description coverage, the description thoroughly explains `item` (omit for all, pass for one) and `item_ids` (bulk). It does not explicitly describe the singular `item_id` parameter or the `type` filter, though both are partially inferable from context and enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Returns accounts for a bank connection') with concrete resources (BANK and CREDIT accounts) and enumerates returned fields. It clearly distinguishes itself from sibling tools by noting when to use openfinance_list_credit_card_bills for standardized bill amounts.
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: omit `item` to aggregate all linked banks, pass `item` to target a single bank, and use openfinance_list_credit_card_bills for standardized open-bill amounts. This includes when-not-to-use guidance and an explicit alternative tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_categoriesAReturns Pluggy's transaction category taxonomy (GET /categories), cached for the adapter session. Each entry has id (the categoryId used by openfinance_update_transaction_category), description (English), descriptionTranslated (Portuguese — prefer this for pt-BR users), parentId and parentDescription (the tree parent). Single aggregated response — no batch ids.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
openfinance_list_connectionsAReturns the saved bank connections for this install: connector_id, item_id, bank name, a per-connection reconnect_url, and an add_connection_url to link additional banks via the Open Finance widget. The reconnect_url reopens the widget in UPDATE mode for that EXISTING connection (user re-enters credentials / MFA token and the data refreshes in place) — use it when a connection needs re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data). It does NOT consume a connection slot and does NOT require disconnecting first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
openfinance_list_credit_card_billsAReturns CLOSED credit card bills for a CREDIT-type account: dueDate, totalAmount, minimumPaymentAmount, allowsInstallments, plus payments[] (id, paymentDate, amount, valueType, paymentMode), payments_count, payments_total, finance charges aggregates, and a derived payment_status per bill. IMPORTANT — Brazilian Open Finance semantics: Pluggy does NOT return a paid/status field. The payment goes into the payments[] of the bill whose CYCLE contains the paymentDate (closing ≈ dueDate − 7d): pre-payment before close stays on the bill being paid; payment between close and due, or after due, lands on the NEXT bill. So payments[] on a bill commonly carries the previous bill's payment, NOT the current one's — do NOT assume this bill was paid just because payments[] is non-empty. Use the derived payment_status (PAID | OPEN | PAST_DUE_UNCONFIRMED | PAST_DUE_UNPAID): a bill is PAID when its OWN payments[] (early pre-payment) or ANY newer bill in the payload contains a payment with amount ≈ this bill's totalAmount (±R$0.50). The MOST RECENT bill that's past-due, with no own pre-payment match, cannot be confirmed via cross-bill (the next cycle hasn't closed yet) — it returns PAST_DUE_UNCONFIRMED. NEVER call such a bill 'vencida' categorically; flag that the payment may have been made between close and due and not yet reflected upstream. The full payment_status_legend is returned alongside the results. OPEN BILL & TOTAL DEBT (standardized, derived — OPT-IN): pass include_open_bill:true to ALSO get open_bill (the current not-yet-closed bill, próxima a vencer) and total_pending_debt (saldo devedor total = all pending installments), BOTH derived from PENDING transactions so they mean the same thing across connectors — use these instead of the CREDIT account's balance, whose meaning VARIES by connector (some report the open-bill partial, others the full installment debt). open_bill = { available, method (cycle_dates = real close/due dates | calendar_month_fallback = estimated, confidence:'low'), close_date, due_date, total_amount (net charges − credits), transaction_count }; plus a future_bills[] breakdown per month — LOW-confidence forward projections of PENDING installments (confidence:'low', basis), NOT authoritative bills (for closed months trust the results totalAmount). CONNECTOR ASYMMETRY: where the bank does NOT expose the open bill before closing (only closed bills, no reliable cycle dates), open_bill.available is false with a reason (connector_exposes_no_pending or open_bill_not_published) — that bill isn't retrievable by any endpoint until it closes (upstream limit of the institution's Open Finance feed, not our filter); check the bank app for the current open bill. When per-transaction billId grouping does not reconcile with the bills' totals, a bill_grouping_reliability warning is attached (trust totalAmount, do not sum by billId). Default false (the projection runs an extra accounts+transactions scan, so it's opt-in). The response opens with an account echo block ({ account_id, bank, name, number, type, item_id }) identifying WHICH card/bank these bills belong to. When more than one bank is connected, ALWAYS cross-check the echo against the card you intended to query and name the bank when presenting results — never attribute one bank's bills to another. This tool's results are bill-level summaries — NOT individual transactions, and each bill's totalAmount (from the bank) is the AUTHORITATIVE amount. To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id — but note creditCardMetadata.billId is a per-connector hint that can be sparse/inconsistent (e.g. Nubank), so do NOT reconstruct a bill total by summing transactions by billId. Returns a warning instead of failing if the CREDIT_CARDS product is not enabled.
Bulk support: accepts account_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| account_id | Yes | ||
| account_ids | No | ||
| include_open_bill | No |
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.
openfinance_list_investmentsAReturns the investment portfolio for a connection (broker or bank with INVESTMENTS product enabled): FIIs, stocks, ETFs, fixed income (CDB/LCI/LCA/Tesouro), mutual funds, retirement (previdência) and COE. Each row carries balance, amount, amountOriginal, amountProfit, lastMonthRate / annualRate / lastTwelveMonthsRate (when available), dueDate, issuer, ISIN, etc. Returns { total:0, results:[], warning } instead of throwing when INVESTMENTS isn't enabled (403) or other upstream errors. DATA INTEGRITY: when MULTIPLE positions come back as TOTAL_WITHDRAWAL with balance/quantity 0 at once (mass zeroing), the tool cross-checks each position's own transaction history upstream; if the zeroing is contradicted (BUY with no sale/redemption/transfer) the response carries data_integrity_warning and the affected rows are flagged integrity:'suspect_zeroed' — treat those balances as UNAVAILABLE (likely a temporary connector failure publishing zeros), never as real R$0, and do NOT sum them into the portfolio.
Bulk support: accepts item_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| page | No | ||
| type | No | ||
| item_id | No | ||
| item_ids | No | ||
| page_size | No |
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.
openfinance_list_investment_transactionsAReturns the movement history for a specific investment position: BUY / SELL / TAX / INTEREST / AMORTIZATION / TRANSFER. Each row carries quantity, value, amount, netAmount, agreedRate (treasury), brokerageNumber, and itemized expenses (brokerageFee, incomeTax, settlementFee, custodyFee, stockExchangeFee, etc.). Use after openfinance_list_investments to get the investment_id.
Bulk support: accepts investment_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| investment_id | Yes | ||
| investment_ids | No |
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.
openfinance_list_loansALists loan contracts per bank connection (GET /loans). Pass items as an array of connection selectors (item_id uuid, connector_id, or connector_name) — one entry per connection to fetch; multiple connections are queried sequentially with rate-limit spacing. OMIT items to list loans across ALL linked banks. Returns { results, errors } per connection.
| Name | Required | Description | Default |
|---|---|---|---|
| items | No |
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.
openfinance_list_transactionsAReturns transactions for a bank account (BANK or CREDIT type). For CREDIT (credit card) accounts, this is the ONLY way to get itemized transactions (purchases, subscriptions, etc.). Each credit card transaction MAY carry creditCardMetadata.billId pointing at a bill from openfinance_list_credit_card_bills, but this is a per-connector HINT, not authoritative: some connectors (e.g. Nubank) populate it sparsely (many transactions and installments arrive with no billId) or inconsistently (the same payment tagged to more than one bill). Do NOT reconstruct a bill's total by summing transactions by billId — the bill's own totalAmount from openfinance_list_credit_card_bills is the source of truth. CREDIT PENDING vs POSTED varies by connector: where the bank exposes future-dated status:'PENDING' installments, those represent the OPEN bill plus future bills (future months); where it does NOT, only the last closed bill's POSTED items appear until ~closing. Same query, different coverage per bank (upstream). To get a standardized open-bill total / total debt regardless, use openfinance_list_credit_card_bills (open_bill / total_pending_debt). Supports from/to date filters (ISO YYYY-MM-DD) and an optional keyword filter via search_queries (case- and accent-insensitive substring match against description and merchant name, OR semantics across multiple terms). When search_queries is set the tool aggregates up to 5000 transactions within from/to before filtering — narrow from/to if truncated:true is returned. PAGINATION: OMIT both page and page_size (the default) to get ALL transactions in the from/to range in one call — the tool auto-paginates the upstream and returns them under a single logical page (page:1, totalPages:1), up to a 5000 ceiling (truncated:true + warning if exceeded, then narrow from/to). Passing page and/or page_size switches to MANUAL pagination: you get one page (page_size items, default 50, max 500; page defaults to 1) with the REAL total/totalPages, so page_size:5 alone returns the first 5 with totalPages telling you how many pages remain. On upstream errors, returns { total:0, results:[], warning, error } instead of throwing. detail controls how much per-row data you get (default 'compact' = slim, cheap). Use detail:'rich' to enrich each row (when the bank connector provides it) with merchantInfo (estabelecimento: businessName/razão social, cnpj, cnae, category — useful for auto-classifying spending) and extra creditCardMetadata fields: billId (a per-connector HINT toward the transaction's bill — sparse/inconsistent on some connectors like Nubank, so do NOT sum by it to get a bill total; use the bill's totalAmount instead), purchaseDate, payeeMCC, feeType/feeTypeAdditionalInfo, otherCreditsType/otherCreditsAdditionalInfo. Use detail:'raw' to get the FULL untouched Pluggy transaction object (everything Pluggy returns, un-normalized — heaviest, for when you need a field we don't project). 'rich'/'raw' add tokens per row and coverage varies by bank/Open Finance, so keep the default for normal listings. For the card's statement closing/due dates use openfinance_list_accounts (creditData.balanceCloseDate / balanceDueDate). The response opens with an account echo block ({ account_id, bank, name, number, type, item_id }) identifying WHICH account/bank these transactions belong to. When more than one bank is connected, ALWAYS cross-check the echo against the account you intended to query and name the bank when presenting results — never attribute one bank's transactions to another. If total is 0 for a CREDIT account, check the connection health via openfinance_get_item_status — statusDetail.creditCards.isUpdated: false means the credit card sync failed and a force sync (openfinance_force_sync) or reconnection may be needed. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: transactions may come back incomplete or wrong until the provider recovers, and reconnecting does not fix it.
Bulk support: accepts account_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| page | No | ||
| detail | No | ||
| page_size | No | ||
| account_id | Yes | ||
| account_ids | No | ||
| search_queries | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnly/idempotent annotations, detailing pagination behavior (auto vs manual, 5000 ceiling, truncated flag), per-connector variation in PENDING/POSTED items, error handling ('returns { total:0, results:[], warning, error } instead of throwing'), provider_incident blocks, and the impact of detail levels on payload size. This provides the agent with comprehensive expectations for runtime behavior and edge cases.
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, front-loading the core purpose and then methodically covering credit-card specifics, search, pagination, detail levels, and error handling. It loses a point for minor redundancy—the 'do not sum by billId' warning appears twice (in the credit card metadata section and again in the rich detail explanation). Otherwise, every sentence serves a purpose and the organization makes the length acceptable.
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 explaining the response structure: account echo block, results, total, totalPages, truncated flag, warning/error on upstream errors, and provider_incident block. It also clarifies how to interpret pagination metadata (e.g., page_size:5 alone returns first 5 with totalPages telling remaining pages). It covers edge cases like sparse billId population and CREDIT PENDING vs POSTED variations, making it self-sufficient for the agent to use correctly in varied bank connector scenarios.
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 zero parameter descriptions, so the description must carry full weight. It does so comprehensively: explains from/to as ISO YYYY-MM-DD filters, search_queries as case/accent-insensitive OR substring matching, detail enum (compact/rich/raw with distinct behaviors), page/page_size pagination modes including defaults and max, and account_ids for bulk execution. Each parameter's semantics and constraints are clarified beyond the schema's bare 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 opens with 'Returns transactions for a bank account (BANK or CREDIT type)'—a specific verb+resource+scope statement. It further distinguishes itself from siblings by noting that for CREDIT accounts this is the ONLY way to get itemized transactions, and explicitly points users to openfinance_list_credit_card_bills for standardized open-bill totals. This makes the tool's purpose unambiguous and differentiates it from related 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 explicit when-to-use guidance: for CREDIT account itemized transactions, this is the ONLY approach. It also provides clear when-not-to-use advice, e.g., 'Do NOT reconstruct a bill's total by summing transactions by billId' and directs to openfinance_list_credit_card_bills as the source of truth. It further suggests using openfinance_list_accounts for statement dates and openfinance_get_item_status for sync health, offering concrete alternatives for specific needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_transactions_by_itemAConsolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call. Resolves the connection's accounts internally and fans out their transactions, so you do NOT need to call openfinance_list_accounts first nor carry account_id uuids between calls. Pass item (connector_id, connector_name or item_id) to target one bank, or OMIT it to analyze ALL linked banks at once. from/to are ISO dates (YYYY-MM-DD). Default granularity:'monthly' returns a COMPACT summary (no raw rows): total entradas, saídas, saldo_liquido, monthly evolution (por_mes), and top_despesas/top_recebimentos (largest N each), plus a per-account breakdown (by_account). Use this for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'. Set granularity:'raw' to ALSO get every consolidated transaction (heavier — only when itemized rows are needed); combine with detail:'rich' to enrich those rows with merchantInfo (cnpj/cnae/businessName/category) + extra creditCardMetadata (billId, purchaseDate, fees), or detail:'raw' for the full untouched Pluggy object per row, when the connector provides them. type filters BANK or CREDIT accounts. On a connection with many transactions the scan caps at 5000/account and flags truncated:true. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: the totals/rows may be incomplete or wrong until the provider recovers, and reconnecting does not fix it.
Bulk support: accepts item_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| item | No | ||
| type | No | ||
| top_n | No | ||
| detail | No | ||
| item_id | No | ||
| item_ids | No | ||
| granularity | No |
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.
openfinance_provider_statusAChecks the LIVE operational status of the Open Finance provider (its public status page) — this is the PROVIDER's health, separate from your own connection's openfinance_get_item_status. Use it whenever data looks incomplete or stale even though a connection shows UPDATED (accounts/transactions/balances missing, a bank not returning everything): it reveals an upstream outage or a known incident on a specific bank/connector, so you can tell a provider-side problem apart from a connection that just needs reconnecting. Returns the global indicator (none/minor/major/critical), degraded components, open incidents, and — when you have banks connected — flags the incidents that affect YOUR connected banks in your_banks_affected.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
openfinance_search_bank_connectorsASearches the available bank connectors by name (pass keywords[], e.g. ['nubank','btg']) and returns, per match: the connector id, whether it's Open Finance or API (access), PF/PJ (audience), the user's already-linked connections (and accounts when include_accounts=true), and a ready connect_url with the bank pre-selected. Some non-Open-Finance credential connectors carry a caveat warning that they don't auto-update (needs periodic manual reconnection) — surface it so the user can prefer the institution's Open Finance connector for automation. Honors the user's plan (a PF plan hides PJ banks; a PJ plan covers BOTH — PF and PJ banks connect and count under the same plan). Call this BEFORE connecting to hand the user a one-click link to the right bank. keywords[] is REQUIRED — without it returns a hint (never dumps the whole catalog).
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | No | ||
| include_accounts | No |
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.
openfinance_update_transaction_categoryAInspectCorrects the category of one or more transactions (PATCH /transactions/:id). Pass items as an array of { transaction_id, category_id } — transaction_id comes from openfinance_list_transactions, category_id from openfinance_list_categories. This overrides Pluggy's automatic categorization AND teaches Pluggy: recategorizing a transaction automatically creates a Category Rule for this client (case-insensitive exact match on the transaction's data), so FUTURE similar transactions are categorized the same way — use this to fix miscategorized transactions and improve categorization accuracy going forward. Batch shape: returns { updated, results: [{ transaction_id, category, categoryId }], errors: [{ id, status, message }] } — per-item errors do not fail the whole batch.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
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.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Sign in to create a connector for this server.