Connect your Conta Bemol account to AI via Brazil's Open Finance: balances, statements, cards, inves
MCP.AI for IDE agents (Cursor, etc.): log in in the browser, copy the access token. Best: add it to this server's config as a header Authorization: Bearer <token> for a permanent, non-expiring connection. Or paste it here for a session-only login: call with { token: "" } after the user pastes, or with no args to get the link.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false (write), destructiveHint=false, idempotentHint=true. Description adds context: explains login flow, token expiration (session-only), permanent vs temporary. It also reveals that calling with no args returns a link. No contradictions.
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 slightly verbose (three sentences) but front-loads the purpose. Every sentence adds value, though it could be condensed slightly. Still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional param, no output schema), the description is fully complete. Covers both authentication methods, explains token behavior, and mentions config alternative. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description fully explains the single parameter 'token': optional JWT string. It describes both use cases: with token for authentication, without for getting login link. Adds meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: authenticating via browser login and token. It specifies the verb 'authenticate' and the resource 'access token', and distinguishes between two methods (permanent config vs session-only paste). This differentiates it from sibling tools like 'connect' or 'marketplace'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: best practice is to add token to config for permanent connection; alternative is to paste token for session-only login. It explains calling with token (paste) or without (get link), covering both scenarios. No exclusions needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns connection status and URLs. When all providers are connected, returns authenticated:true and empty pending[]. When credentials are missing, returns connect_url for the toolkit and per-install URLs.
| 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, indicating a safe, read-only operation. The description adds behavioral context such as returning URLs and the distinction between connected and missing credentials states, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The description is front-loaded with the core purpose and then provides conditional behavior. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description covers the main behaviors (all connected vs missing credentials). It does not mention error conditions or rate limits, but given the read-only nature and annotations, it is mostly complete. The lack of output schema is mitigated by describing return values.
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 and schema coverage is 100% (empty schema), so the description does not need to explain parameters. It compensates by describing the return values in different scenarios, which aids the agent in understanding the output even without an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns connection status and URLs. It specifies behavior for two scenarios (all providers connected vs missing credentials). However, it does not explicitly differentiate from sibling tools like 'authenticate' or 'openfinance_list_connections', missing some clarity on when to use this specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on what to expect under different conditions (all providers connected vs missing credentials), implying when to check status. However, it lacks explicit guidance on when to use this tool versus alternatives, such as when to use 'authenticate' or 'openfinance_list_connections' instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. Covers capability requests like "find an MCP that does X", "consulta um CPF", "is there a tool for Y". Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile (every tool with its id + params, pricing, auth) so you pick the right tool_id → invoke RUNS that tool. KEY: invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list. If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link (the user opens it, then you retry). Use install only to make an MCP PERMANENT in the active toolkit (its tools then show up natively in future sessions); prefer invoke for a single/occasional use. list_tools lists what is callable right now. subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits. Search/describe flag installed_in_toolkit vs installed_in_workspace. Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also carries the mcp.ai PROMPT LIBRARY, which is about ready-made prompt TEXT rather than MCPs: search_prompts finds one, get_prompt returns its full text with {{variables}} filled, and publish_prompt saves a prompt and returns a shareable mcp.ai/p/ link that opens without login.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| action | No | search | |
| mcp_id | No | ||
| message | No | ||
| tool_id | No | ||
| arguments | No | {} | |
| immediate | No | ||
| tier_slug | No | ||
| prompt_body | No | ||
| prompt_slug | No | ||
| prompt_tool | No | ||
| prompt_vars | No | {} | |
| conversation | No | [] | |
| prompt_title | No | ||
| request_name | No | ||
| cancel_reason | No | ||
| cancel_comment | No | ||
| prompt_targets | No | ||
| report_context | No | ||
| prompt_category | No | ||
| request_details | No | ||
| prompt_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: invoke runs tools even if not installed, returns connect/checkout links for auth/payment, and install adds permanent tools. It also notes permission requirements for writes, providing rich behavioral context that annotations alone (readOnlyHint=false, destructiveHint=false) do not capture.
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 a clear overview but is a single dense paragraph without bullet points or action-grouped sections, making it hard to scan. While the length is justified by the tool's complexity, better structure would improve readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 actions, 23 params, and no output schema, the description covers the core flows, permissions, auth/payment handling, and prompt library adequately. It omits details on some parameters and return formats for specific actions like list_tools, but overall provides substantial context for such a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 23 parameters and zero schema descriptions, the description must compensate. It explains the action enum values and core parameters like tool_id and mcp_id, but leaves many parameters (immediate, tier_slug, cancel_reason, prompt_targets, etc.) ambiguous, so coverage is only partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is the official mcp.ai marketplace, serving as the catalog for MCPs/tools and the way to run them. It outlines a concrete flow (search → describe → invoke) and explicitly distinguishes its scope from sibling openfinance_* and utility tools, making its purpose unmistakable.
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: prefer invoke for one-off tasks, use install only for permanent addition, and use list_tools to see what's callable now. It also states that writes require owner/admin and that request_mcp is for when nothing fits, providing clear when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revokes 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 set destructiveHint=true, and description confirms the destructive nature ('deletes the connection data'). It adds the behavioral details of consent revocation and return of reconnection URL, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the primary action and outcome, with no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good purpose and transparency, the description lacks parameter guidance for the 'item' field and does not describe the output (the reconnection URL format). For a destructive tool with no output schema, this is incomplete.
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 fails to explain the single required 'item' parameter (e.g., what it represents or how to specify the bank). It 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 clearly states the tool revokes consent and deletes connection data for a specific bank, distinguishing it from sibling tools like openfinance_force_sync. The verb 'revokes' and resource 'bank connection' are 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 implies use when disconnecting a bank and mentions reconnection via returned URL, providing clear context. However, it does not explicitly state when not to use it or compare with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forces 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?
Describes wait time (~60s), polling mechanism, returned fields (status, executionStatus, etc.), and special cases like needs_action with reconnect_url and timeout. No contradiction with annotations; the description adds depth 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 detailed and well-structured, front-loading the core action. While slightly lengthy, every sentence adds value (e.g., explaining return formats and edge cases). Minor redundancy in listing selector types could be trimmed.
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 covers return values (results/errors), error states (needs_action, timeout), and fallback behavior. It addresses all likely agent queries about syncing, making the tool fully understandable without external references.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage, so the description fully explains both parameters: 'items' as selectors array with examples, 'wait' as fire-and-forget flag. This compensates completely for the schema's lack of descriptions.
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 forces a bank re-sync and waits for completion. It distinguishes from siblings by emphasizing 'without disconnecting/reconnecting' and includes specific use cases like stale balances. The verb 'forces' and resource 'connections' are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (stale balance/transactions) and alternatives (openfinance_get_item_status for re-check, wait: false for fire-and-forget). Provides clear guidance on omitting items to sync all vs. passing selectors.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the latest available balance per account id (GET /accounts/:id/balance). This is the freshest balance the provider can serve, but it is a SNAPSHOT anchored to the connection's last upstream sync: the updateDateTime/updatedAt in each row is that sync instant, NOT a to-the-second live read. If a movement that just happened is not reflected yet, or the balance disagrees with the sum of openfinance_list_transactions, run openfinance_force_sync to pull fresh data and then re-read. Pass account_ids as an array (1–50). CREDIT accounts may return Pluggy BALANCE_FETCH_ERROR (provider could not fetch it) or BALANCE_CONSENT_ERROR (the institution refused it because the consent lacks the balance permission — reconnecting the bank restores it) — 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?
Despite readOnlyHint and idempotentHint annotations, the description adds substantial behavioral detail: balances are snapshot values tied to the last upstream sync, not live reads; certain conditions produce structured warnings instead of throwing; and upstream 5xx or non-Open Finance connectors cause degraded rows. This goes well 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 dense but well-organized: core purpose first, then freshness caveat, then remediation, then parameter usage, then error behavior. Every sentence contributes necessary context, though the length is on the higher side and 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?
For a single-parameter read tool with no output schema, the description covers invocation, parameter constraints, freshness semantics, error handling, and a remediation path. It does not describe the full response shape in detail, but it mentions key fields like updateDateTime/updatedAt and warning, which is sufficient for correct use.
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 does so by specifying that account_ids should be passed as an array and constrained to 1–50 items. While the schema already defines the array type and string items, the size constraint and usage hint add practical meaning.
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 a specific action and resource: 'Returns the latest available balance per account id' and gives the exact GET endpoint. It also distinguishes this tool by emphasizing the snapshot nature and explicitly referencing sibling actions like openfinance_force_sync and openfinance_list_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 provides practical usage guidance: if the balance seems stale or inconsistent with transactions, run openfinance_force_sync and re-read. It does not explicitly compare with openfinance_get_accounts_detail or openfinance_list_accounts, but it gives enough context for the primary balance-fetching scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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?
Annotations declare readOnlyHint, destructiveHint, idempotentHint, confirming safe read. Description adds context about provider_incident block and potential unreliable values, going beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise single paragraph with four sentences, each adding value. Front-loaded with purpose, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers batch shape, error case via provider_incident, and orientation for agent. Could add more detail on typical response fields but sufficient for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 0%, the description specifies that account_ids should be an array with 1-50 elements, adding practical constraints beyond the JSON schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns full account objects with extended creditData for given IDs, specifies the HTTP endpoint, and the batch response shape. It distinguishes from sibling tools like openfinance_list_accounts by focusing on per-ID detail retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage instructions: pass account_ids as array of 1-50, and warns about provider_incident affecting reliability of credit data. Does not explicitly compare to alternatives but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns bill-level detail for one or more credit card bills by id (GET /bills/:id): dueDate, billClosingDate (when the cycle closed — the boundary that defines which purchases belong to this bill), totalAmount, financeCharges and payments[] (id, paymentDate, amount, valueType, paymentMode). ITEMIZED PURCHASES (OPT-IN): the bank's bill payload has no transactions in it — they live on the card ACCOUNT. Pass include_transactions:true (plus account_id of the credit card, since the bill itself carries no account reference) and each row also gets transactions[], transactions_count, transactions_sum and reconciles_with_total, already matched to that bill. Always check transactions_basis: bill_id = exact (the bank tagged each transaction with this bill — the normal case for CLOSED bills), date_window = ESTIMATE (confidence:'low', window echoed in transactions_window) used when the connector tags no billId or the bill is still open (PENDING lines get no billId until the cycle closes), unavailable = no link possible. Opt-in because it costs an extra full transaction scan of the account. Whatever the basis, the bill's own totalAmount is authoritative — do NOT rebuild it by summing transactions. Without the opt-in the response carries a transactions_hint; you can also fetch them yourself via openfinance_list_transactions with the credit card account_id and a from/to range ending at billClosingDate. 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 | ||
| account_id | No | ||
| transactions_detail | No | ||
| include_transactions | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are rich behavioral disclosures beyond the annotations' readOnlyHint/idempotentHint/destructiveHint: transactions_basis distinctions with confidence levels, authoritative totalAmount warning against summing, the meaning of payments[] relative to the current bill, the absence of a paid/status field, and the cost/performance implication of include_transactions. This goes far beyond the metadata.
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 every sentence carries essential operational knowledge: what is returned, what the opt-in does, basis precision, payment semantics, and recommended alternatives. It is tightly organized and front-loads the core purpose before diving into complications, with no filler or repetition.
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 complex tool with no output schema, the description is exceptionally complete. It covers the batch shape, field semantics, edge cases like open vs closed bills, estimate windows, the transactions_hint, manual retrieval workflow, and limitations of payments[] data. An agent can confidently invoke it correctly with this description alone.
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 shoulders the burden. It explains bill_ids (array, discover via list), include_transactions, account_id (required when opt-in), and role of billClosingDate. However, transactions_detail (compact/rich/raw) is entirely unmentioned, and the description does not clarify what each enum value changes in output shape.
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 starts with a precise verb and resource: "Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)" and enumerates the exact fields returned. It clearly distinguishes itself from sibling tools by explaining that bill ids come from openfinance_list_credit_card_bills and that transactions may instead be fetched with openfinance_list_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 provides explicit when-to-use guidance: discover ids via openfinance_list_credit_card_bills first, pass bill_ids as an array, and choose the opt-in include_transactions path only when full transaction scan is justified. It also explicitly directs users to openfinance_list_credit_card_bills for paid status and to openfinance_list_transactions for manual transaction retrieval, with the range ending at billClosingDate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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?
Adds significant value beyond annotations: describes returned fields (status, executionStatus, connector metadata, reconnect_url), explains behavior difference when `item` is omitted vs. provided, and mentions bulk support. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Information is front-loaded with core purpose and usage. Could be slightly more concise by combining sentences, but structure is logical and no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the input schema (3 params, no enums, no output schema) and annotations, the description fully covers tool behavior: return fields, bulk support, single vs. all distinction, and reconnect URL usage. No gaps for expected usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining that omitting `item` returns all banks, and passing `item` returns a single bank. Also clarifies `item_ids` for batch. Does not differentiate `item` vs `item_id`, but overall adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states the tool returns the current status of a bank connection with specific status values. It distinguishes between retrieving status for all linked banks (omit `item`) and a single bank (pass `item`), clearly differentiating from sibling tools like `openfinance_list_connections`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context on when to use: to get status, to obtain a reconnect URL without disconnecting. It implies batch usage via `item_ids`. However, it lacks explicit exclusions or alternative tool recommendations, so slightly below top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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?
Discloses behavioral traits beyond annotations: specifies GET request, batch operation with array of 1-50 loan_ids, response shape { results, errors }, and detailed fields returned. No contradiction with readOnlyHint annotation.
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 each sentence adds value: purpose, use context, parameter details, response shape. Slightly long but effective. Could be more structured with bullet points.
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 provides extensive field listing and batch shape. It covers prerequisites and usage context. Minor lack of error handling details, but overall quite complete for a detail endpoint.
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 only defines loan_ids as an array of strings with 0% coverage. The description adds critical semantics: array size limit (1-50), batch behavior, and that it accepts multiple IDs for detail lookup.
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: returning full loan contract detail by ID. It lists specific return fields and distinguishes from sibling tool openfinance_list_loans by indicating its use for deep-diving after listing.
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 tells when to use this tool: 'Use after openfinance_list_loans to deep-dive on a specific contract.' This provides clear guidance compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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. A CREDIT row may carry creditData.usedAmount (how much of THIS card's limit the bank reports as consumed) and a balance_notice. balance_notice means balance came back 0,00 while the bank's own payload indicates an outstanding amount — some issuers never fill the card's consolidated balance field. When it is present, do NOT tell the user the card has nothing to pay: read the amount from openfinance_list_credit_card_bills instead. bankData.closingBalance and automaticallyInvestedBalance are provider-reported extras that can LAG right after a connection is first created: the bank may publish the connection as UPDATED before those derived fields converge, so they can briefly carry a stale/phantom value that a force sync (openfinance_force_sync) reconciles. The account's own balance is authoritative — treat those two as hints until they agree with it. 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?
Goes far beyond the readOnly/idempotent/destructive annotations by disclosing connector-dependent balance semantics, balance_notice, provider_incident, identity_notice, and lagging bankData fields. No statement conflicts with 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 long but well organized, opening with the core return value and then layering caveats. It is dense and occasionally wordy, though most sentences earn their place given the complexity of Open Finance edge cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, it describes the main fields and the notice blocks, explains authoritative vs auxiliary data, and gives dedupe instructions. An agent has enough context to call the tool correctly and to avoid misinterpreting returned values.
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 parameter-documentation burden. It explains item omission vs presence and item_ids bulk execution, but it does not explicitly define item_id or describe how type filters results, leaving those two parameters to be inferred from the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first line names a specific verb-resource pair ('Returns accounts') and enumerates the exact account types and fields returned (balance, number, type, subtype, bankData, creditData). It also distinguishes the tool's role from related tools by noting that standardized bill data belongs to 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?
Explicitly explains when to omit item for cross-bank aggregation versus pass item for one bank, and when to use openfinance_list_credit_card_bills instead for standardized open-bill amounts. It even gives handling guidance for stale fields (force sync) and for notices, covering both selection and interpretation of results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds details about caching behavior, the single aggregated response (no batch ids), and language preferences for Portuguese users, providing valuable behavioral context beyond what annotations offer.
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 with three sentences, each serving a purpose: stating the main function, detailing output fields, and noting caching and language preference. It is front-loaded and has no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and simple read-only nature, the description sufficiently explains return values with field meanings, language note, and caching. It does not cover pagination or errors, but those are minor for a category list that is typically small and cached.
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 baseline is 4. The description does not need to add parameter information; instead, it focuses on the output structure, which is appropriate and adds meaning beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns Pluggy's transaction category taxonomy via a GET /categories endpoint, cached per session. It further explains the structure of each entry and how the id is used by openfinance_update_transaction_category, making the purpose 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 implicitly suggests using this tool to obtain category IDs for updating transactions, but it does not explicitly state when to use this tool versus other tools like openfinance_list_transactions or alternative methods. No exclusion criteria or context about alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: that the reconnect_url does not consume a connection slot and does not require disconnecting first, which is not evident from annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently conveys the main purpose, key fields, and important usage notes. It is front-loaded with the return value and includes necessary details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero parameters, the description provides sufficient context about the return values and their semantics. It explains both URLs adequately, making the tool's behavior complete for an API listing 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 input schema has no parameters (coverage 100%). The description adds meaning by detailing the return fields and their significance (e.g., reconnect_url for UPDATE mode, add_connection_url for linking additional banks).
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 saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes itself from sibling tools by explaining the reconnect_url's purpose in updating existing connections.
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 the reconnect_url (e.g., for re-authentication, LOGIN_ERROR, stale data). It implies the tool is for listing connections, but does not explicitly state when not to use it, though the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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?
Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant context: derived payment_status logic, connector asymmetry, bill grouping reliability, open_bill projection methodology and confidence levels. 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 very long and dense, covering many details in a single paragraph. While every sentence adds value, it lacks formatting (bullet points, sections) that would improve scanability. Could be more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (derived fields, connector asymmetry, cross-bill logic) and no output schema, the description covers all necessary aspects: output structure, edge cases, and warnings. It is thorough and leaves little ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It thoroughly explains include_open_bill and mentions account_ids for bulk. However, it does not describe page and page_size parameters (defaults, limits), leaving gaps. Adequate but not comprehensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns closed credit card bills for CREDIT-type accounts, listing specific fields. It distinguishes itself from sibling tools like openfinance_list_transactions (individual transactions) and openfinance_get_credit_card_bill (singular bill).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive guidance: when to use include_open_bill, how to interpret payment_status, warnings against assuming payment from payments[], when to use openfinance_list_transactions for itemized purchases, and connector asymmetry. Also specifies when to not use this tool for open bills.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds significant behavioral context: error handling (returns warning instead of throwing), and a detailed data integrity mechanism with cross-checking and 'suspect_zeroed' flags. 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 around 150 words and front-loaded with the main purpose. It includes essential details without excessive redundancy. Minor redundancy exists in the data integrity section, but overall it is well-structured and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and many siblings, the description covers error handling, data integrity, and return values (balance, amount, etc.). Missing parameter explanations partially reduce completeness, but the rest is adequate for a 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 description coverage is 0%. The description only hints at 'item_ids for batched execution' but does not explain other parameters like 'item', 'page', 'type', or 'page_size'. This minimal compensation is insufficient for the agent to understand parameter usage correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'Returns the investment portfolio for a connection' and lists specific asset types (FIIs, stocks, ETFs, etc.), making the resource and verb distinct. The tool name includes 'list_investments' and the description differentiates it from siblings that list 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 provides some context (error handling, bulk support) but does not explicitly state when to use this tool versus alternatives like openfinance_list_investment_transactions. The usage is implied by the resource type, but no when-not or exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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 and idempotent behavior. Description adds detail about returned fields and bulk execution, providing value beyond structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused paragraphs with no wasted words, front-loading core functionality and following with usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return fields and movement types well, but lacks information on pagination behavior and does not fully cover all parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Only investment_id and investment_ids are explained; page and page_size are undocumented, leaving semantic gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns movement history for investment positions, listing specific transaction types. Distinguishes from sibling tools like openfinance_list_investments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use after openfinance_list_investments to obtain investment_id. Mentions bulk execution support, but does not state when to avoid this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists 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?
Annotations indicate readOnly, idempotent, and non-destructive. The description adds important behavioral details: items accept connection selectors, multiple connections are queried sequentially with rate-limit spacing, and the return format is { results, errors } per connection.
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 with two sentences. It front-loads the purpose, then provides parameter and usage details, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers different usage patterns, return format, and rate-limit behavior. It lacks pagination details, but for a list tool with no output schema, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description fully compensates by explaining the items parameter: array of connection selectors (item_id uuid, connector_id, or connector_name), with option to omit for all connections.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists loan contracts per bank connection, specifies the HTTP endpoint, and explains different behaviors for providing vs. omitting the items parameter. It distinguishes this tool from siblings like openfinance_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?
The description explains when to use the items parameter (to fetch specific connections) and when to omit it (list all), including sequential querying with rate-limit spacing. However, it does not explicitly state when not to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns 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). SCHEDULED (future-dated) ROWS: results are ordered by date DESCENDING, and on a card with long installment plans the TOP of the list is the FUTURE — rows dated months ahead are scheduled installments of purchases already made, not new purchases. Every such row is flagged scheduled:true, the response carries scheduled_count and a notice naming the most recent row that actually happened. NEVER read the first row as 'the latest purchase' without checking scheduled. To list only what already happened, pass to = today. 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), billForecastDate, cardNumber, purchaseDate, payeeMCC, feeType/feeTypeAdditionalInfo, otherCreditsType/otherCreditsAdditionalInfo. billForecastDate ("YYYY-MM") is the counterpart of billId for the OPEN cycle: PENDING transactions have NO billId (the bank only mints it once the bill closes), so this is the only field telling you which bill a pending purchase will land in — its month OFFSET is per-connector (some banks month+1, others month+0), so surface it as-is and do not derive a due date from it. cardNumber (last 4 digits) separates the primary cardholder's charges from an additional card's when several cards share one account_id. 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 reveals a great deal of behavior not captured by the annotations: auto-pagination behavior, sorted by date descending with scheduled rows, truncation at 5000 transactions, error return shape, provider_incident blocks, and per-connector inconsistencies like sparse billId. The annotations already signal read-only/idempotent, and the description adds extensive side-effect-free operational context 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 first sentence delivers the core purpose, and the description is organized into semantic chunks: credit-card caveats, filtering, pagination, detail modes, response echoes, and sibling-tool referrals. It is quite long and repeats the billId warning and 'do not sum by billId' guidance in more than one place, so it is not maximally concise—but the complexity and per-bank caveats justify most of the 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?
Given no output schema, the description is remarkably complete about return contents, including the account echo, scheduled_count, notice, truncated flag, provider_incident block, and graceful-error structure. It also covers connector variability and how to recover when a credit card sync breaks. An agent has everything needed to select, invoke, and interpret this tool 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?
With 0% schema coverage, the description does substantial work to explain parameters: from/to use ISO YYYY-MM-DD, search_queries uses case-insensitive OR matching, page/page_size switch between auto and manual pagination, detail level semantics are fully documented. The required account_id, however, is only implied by context rather than explicitly defined as 'the ID of the target account', and account_ids is explained only as a terse 'bulk support' line.
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-object: 'Returns transactions for a bank account (BANK or CREDIT type)', clearly identifying the resource and its scope. It also distinguishes the tool from openfinance_list_credit_card_bills and openfinance_list_accounts by explaining which sibling to use for bill totals and statement dates. This goes beyond the generic title and disambiguates the tool effectively.
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: 'this is the ONLY way to get itemized transactions' for credit cards, and directs agents to openfinance_list_credit_card_bills when they need a standardized open-bill total or total debt. It also explicitly warns against reconstructing bill totals from transactions and points to openfinance_get_item_status when a credit total is zero, giving precise routing and remediation paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Consolidated 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?
The description discloses important behavioral traits beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It warns about a 5000/account cap with truncation flag, a provider_incident block that can cause incomplete data, and explains the fan-out internal logic. This fully informs the agent about side effects and limitations, adding significant value over the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence. It is lengthy but every sentence adds value, covering parameters, behavior, and edge cases. Some rephrasing could improve readability (e.g., using bullets), but overall it is well-structured and informative without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 unannotated parameters, no output schema), the description is exceptionally complete. It explains all parameters, return structure (summary fields like total entradas, por_mes, top_despesas, by_account), edge cases (truncation, provider incidents), and bulk support via item_ids. No critical information 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?
The input schema has 9 parameters with no descriptions (0% coverage), but the description provides thorough explanations for each parameter: item (connector_id/connector_name/item_id), from/to (ISO dates), granularity (monthly/raw), detail (compact/rich/raw), type (BANK/CREDIT), top_n, item_id, item_ids. It gives exact usage examples and behavioral details, fully compensating for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool provides consolidated cash-flow analysis for a bank connection over a period in one call, resolving accounts internally and avoiding the need for separate list_accounts calls. It distinguishes itself from siblings like openfinance_list_accounts and openfinance_list_transactions by emphasizing the consolidated, one-call nature. The verb 'analyze' and resource 'connection transactions' 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 explicitly states when to use this tool (e.g., for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos') and provides guidance on parameters like granularity and detail for different needs. It mentions that you do NOT need to call openfinance_list_accounts first. However, it does not explicitly mention alternative sibling tools for simpler queries, which would strengthen usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral details beyond annotations: it states the tool checks a public status page, returns global indicator, degraded components, open incidents, and flags incidents affecting connected banks via `your_banks_affected`. No contradictions.
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 three sentences long, each packing useful information. It is front-loaded with the main purpose. However, it could be slightly more concise; for example, the explanation of 'your_banks_affected' could be integrated more succinctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description completely covers what the tool does, when to use it, and what it returns (global indicator, degraded components, incidents, affected banks). It provides sufficient context for an agent to select and invoke it 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?
There are zero parameters, so the input schema offers no semantics. The description fully explains what the tool does without needing to describe parameters, meeting the baseline for no-parameter tools. It adds rich context about the tool's output and use cases.
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 'Checks' and identifies the resource as 'LIVE operational status of the Open Finance provider'. It clearly distinguishes this tool from the sibling `openfinance_get_item_status`, which checks the connection's own status, not the provider's health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'whenever data looks incomplete or stale even though a connection shows UPDATED'. It explains the tool reveals upstream outages or known incidents, helping differentiate provider-side problems from connection issues. It also contrasts with the sibling tool `openfinance_get_item_status`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches 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?
Annotations already indicate safe, read-only, idempotent. Description adds crucial behaviors: plan-based filtering (PF/PJ), caveat warnings for credential connectors, and returning a ready connect_url. 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?
Single dense paragraph with front-loaded purpose. Every sentence adds value: search action, return fields, plan behavior, caveat, usage directive. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description thoroughly explains return values, plan behavior, edge cases (caveat), and required parameters. Complete for a search tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage; description adds meaning by explaining keywords as an array of strings (with example) and include_accounts triggers accounts retrieval. Useful but could mention default value for include_accounts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it searches bank connectors by name, specifies returned fields (connector id, access, audience, linked connections, connect_url), and distinguishes from sibling list tools by emphasizing it's for pre-connection one-click linking.
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 says 'Call this BEFORE connecting' and notes that keywords[] is required (without it returns a hint). Does not explicitly exclude alternatives but context implies its unique role.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Corrects 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?
Beyond the annotations that merely indicate non-read-only, non-idempotent, and non-destructive, the description reveals a critical side effect: recategorizing automatically creates a Category Rule that affects future similar transactions. It also details batch error handling, describing the response structure and emphasizing that per-item errors do not fail the whole batch. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single paragraph that efficiently conveys the purpose, parameter structure, side effect, and batch behavior. It front-loads the action and uses clear language. While it packs a lot of information, it is not overly verbose and every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description covers input semantics, behavioral implications, and response format. It includes error handling details absent from the schema. No gaps remain for an agent to operate effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the structure of the `items` array and the meaning of each field, including the sources of transaction_id and category_id. This adds essential meaning that the raw schema lacks.
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 corrects transaction categories, names the HTTP method and endpoint, and distinguishes itself from sibling tools by referencing openfinance_list_transactions and openfinance_list_categories for input IDs. It also explains the side effect of creating a Category Rule, which is unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises when to use: 'to fix miscategorized transactions and improve categorization accuracy going forward.' It also provides guidance on obtaining the required IDs from other tools. However, it does not explicitly state when not to use or list alternatives, though the sibling context implies no other tool modifies categories.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report a bug, missing feature, or send feedback. Include the conversation array with recent messages for reproduction.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| message | Yes | ||
| conversation | No | [] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the description's 'report' action is consistent and non-contradictory. However, it does not disclose additional behavioral traits like ticket creation or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences, front-loading the purpose and a key usage tip. It is minimally sufficient but could be slightly improved with structural cues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one required parameter and no output schema, the description covers the basic purpose and a usage hint. It lacks details on what happens after reporting (e.g., confirmation, error handling).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains the 'conversation' parameter for reproduction. The 'message' and 'context' parameters lack any additional meaning beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Report' and clearly defines the resources: bug, missing feature, or feedback. It distinguishes from all sibling tools, none of which are for reporting issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for providing feedback with reproduction context but does not explicitly state when to use or not use this tool, nor mention alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show the current MCP platform and adapter versions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context by specifying it shows 'MCP platform and adapter versions', which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that conveys the full purpose without any extraneous words. Perfectly front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with zero parameters and no output schema, the description is complete. It tells the agent exactly what to expect from invoking this 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?
No parameters exist, and schema description coverage is 100%. The description adds no parameter-specific meaning, but with zero parameters, baseline is 4.
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 'Show the current MCP platform and adapter versions' clearly states the tool's purpose with a specific verb ('Show') and resource ('versions'). It uniquely identifies what the tool does among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative guidance, but for a simple version retrieval tool, the context is self-evident. The description implies this is for checking version information, sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the current toolkit state: installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context by detailing exactly what the returned state includes, giving the agent a clear picture of the tool's output without over-explaining. 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 a single sentence that is well-organized and packs all necessary information without filler. It lists the key components (installed MCPs, connection status, accounts, catalog tool count) in a logical order, making it highly scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no params, no output schema) and strong annotation coverage, the description provides sufficient detail about what the agent will receive. It covers the main aspects of the toolkit state but could optionally mention whether it requires network access or is purely local.
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 is not required to explain parameter behavior. The baseline for no parameters is 4, and the description adds no irrelevant parameter details, correctly focusing on what is returned.
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 is specific and informative: 'Returns the current toolkit state' with a clear enumeration of what's included (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like 'show_version' or 'openfinance_list_accounts'.
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 clearly implies when to use this tool—whenever you need an overview of the toolkit's state, such as checking which MCPs are installed and their connectivity. It does not explicitly mention alternatives or exclusions, but the purpose is distinct enough from siblings to provide clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
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
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
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!
Connect your Banco Bmg account to AI via Brazil's Open Finance: balances, statements, cards, investm
Connect your Banrisul account to AI via Brazil's Open Finance: balances, statements, cards, investme
Connect your Atacadão account to AI via Brazil's Open Finance: balances, statements, cards, investme
Connect your Bradesco account to AI via Brazil's Open Finance: balances, statements, cards, investme
Add one secure layer between your agents and this server.
Every tool has a clearly distinct purpose: accounts, transactions, credit card bills, loans, investments, connections, sync, categories, provider status, and platform meta-tools are all separable. Even the two transaction tools differ (per-account list vs consolidated analysis) and the two status tools differ (connection vs provider health).
The openfinance_* prefix is consistently applied across the financial domain, and most follow a verb_noun pattern (list_accounts, get_balance, update_category). However, there are non-prefixed tools (authenticate, connect, marketplace, toolkit_info) and one outlier like openfinance_provider_status (noun instead of verb) that slightly break the pattern.
25 tools is at the upper boundary of what feels heavy for a single server, even for a comprehensive financial aggregation toolkit. The number is justified by the breadth of domains covered (accounts, credit, loans, investments, connections, platform features), but it requires careful agent selection and might be better split into separate servers.
The surface covers the full financial data lifecycle: listing and fetching details for all asset types, updating transaction categories, managing connections (list, sync, disconnect, reauth), checking provider health, and searching connectors. There are no obvious dead ends—every domain has read and appropriate write/update operations.