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