Connect your Carrefour account to AI via Brazil's Open Finance: balances, statements, cards, investm
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.8/5.
Each tool has a clearly distinct purpose. Open Finance tools are segmented by resource (accounts, transactions, bills, loans, investments) and action (list, get, update, search), with no overlapping functionalities.
All tools follow a consistent verb_noun pattern. General tools use simple verbs (authenticate, connect), while Open Finance tools uniformly use the 'openfinance_' prefix followed by a verb_noun structure (e.g., openfinance_list_accounts, openfinance_get_account_balance).
25 tools is on the higher end but justified by the broad domain coverage (Open Finance operations for multiple financial products, plus a marketplace). Each tool addresses a specific need, and the count aligns with the server's scope.
The tool surface covers the core CRUD lifecycle for financial data: listing, reading, updating categories, and syncing. Missing are tools for deleting accounts or managing connections beyond disconnect/sync, but these are minor gaps given the read-heavy nature of the domain.
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?
Discloses that token establishes a session and config provides permanent auth. Annotations indicate idempotent and non-destructive, which aligns. 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?
Somewhat conversational and longer than needed; multiple sentences contain repeated info. Could be more concise, but front-loaded with key 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?
Covers both usage scenarios, parameter meaning, and desired outcome. No output schema needed. Complete for a simple auth tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, description compensates by explaining the 'token' parameter is a JWT from browser login. Could add format details, but sufficient.
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 defines the tool's purpose: authenticate by either providing a JWT token for session login or calling with no args to get a login link. It's specific and distinct 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?
Explains two usage modes (permanent config vs session token) and when to use each (no args for link). Could be clearer about when not to use, 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.
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 and idempotentHint true, confirming safe read operation. Description adds behavioral context about response in two states (all connected vs missing credentials), which is helpful but not extensive.
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 short sentences, front-loaded with core purpose, no redundancy. Every sentence adds value and the structure is 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 zero parameters, no output schema, and simple behavior, the description sufficiently covers the tool's behavior in the two main scenarios. No significant gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% (vacuously). Description provides no parameter info, but none is needed. Baseline score of 4 is appropriate.
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 tool returns connection status and URLs, with specific scenarios for when all providers are connected versus when credentials are missing. It differentiates from sibling authenticate tool by focusing on status rather than performing authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for checking connection status but does not explicitly state when to use versus siblings like authenticate or openfinance_list_connections. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?
It reveals critical behaviors beyond annotations: invoke works even when the MCP is not installed (one-off), returns a connect link if credentials are needed, returns a checkout/top-up link if paid and wallet is empty (and to retry), and that write operations require workspace owner/admin. The annotation readOnlyHint=false is consistent, and no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that is front-loaded with purpose and covers many critical details without filler. It is long but each sentence contributes unique information; however, breaking it into sections/bullets would improve readability and scanability.
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?
It covers the core marketplace flows, admin requirements, auth/payment link behavior, and the separate prompt library. Yet it omits explanation of some actions like 'resume' and parameters like 'immediate' or 'tier_slug', which leaves gaps for an agent trying to invoke all possible actions correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the central 'action' parameter and its values (search, describe, invoke, install, etc.), and mentions tool_id and arguments. However, many parameters like limit, immediate, tier_slug, cancel_reason, and prompt_targets are not explicitly defined, leaving some ambiguity for a 23-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is the 'official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them', and outlines the core flow (search → describe → invoke). It differentiates from sibling tools like openfinance_* and report_bug by being the central catalog/execution hub.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use each action: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', 'list_tools lists what is callable right now', and 'request_mcp asks us to build a NEW MCP when nothing fits'. This gives clear alternatives and contexts, far beyond a basic 'use this for X'.
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 already indicate destructiveness. The description adds that data is no longer available and returns a reconnection URL, providing useful context about the irreversible nature and recovery option. However, it does not mention prerequisites or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each adding value: revoke/delete, data unavailability, and reconnection URL. No redundant 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?
For a simple destructive tool with one parameter and no output schema, the description covers the action and return value. However, it lacks parameter clarification and usage guidance relative to siblings, leaving some gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'item' has no description in the schema (0% coverage), and the description does not clarify what 'item' represents (e.g., bank ID, connection ID). The agent must infer from context, making it ambiguous.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: revokes Open Finance consent and deletes connection data for a specific bank. The verb and resource are specific, and it distinguishes from siblings 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?
The description gives the purpose but does not explicitly state when to use this tool over alternatives like openfinance_list_connections or openfinance_force_sync. No 'when-not-to-use' guidance is provided.
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?
Goes far beyond annotations (which only indicate not read-only, not destructive). Describes polling behavior (waits up to ~60s), return fields (status, executionStatus, lastUpdatedAt, synced, needs_action with reconnect_url), error states (MFA_REINTERACTION, LOGIN_ERROR, timed_out). 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 longer than average but every sentence adds value. It is front-loaded with the main action and then provides detailed guidance. Could be slightly more concise but remains clear and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description thoroughly explains the return format (results/errors) with field meanings and error handling (reconnect_url, timed_out). It covers all essential behavioral aspects for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description fully explains both parameters: 'items' as an array of selectors (item_id, connector_id, etc.) and that omitting it syncs all; 'wait' as a boolean for synchronous vs fire-and-forget. This fully compensates for the missing 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 uses specific verbs ('forces', 're-sync') and resource ('connections') and clearly states it waits for completion. It distinguishes itself from sibling tools like openfinance_get_item_status (re-check if timed out) and read-only tools by emphasizing its write/sync nature.
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 (stale balance/transactions) and when not to (without disconnecting). Mentions alternatives (openfinance_get_item_status for timed out results) and provides guidance on wait parameter behavior (fire-and-forget vs wait).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_account_balanceAReturns real-time balance payload per account id (GET /accounts/:id/balance). Pass account_ids as an array (1–50). CREDIT accounts may return Pluggy BALANCE_FETCH_ERROR — those rows include a structured warning instead of throwing. When the financial institution is temporarily unavailable upstream (5xx) or the connector is not Open Finance, the row DEGRADES to the last-synced balance with realtime: false, updatedAt and a warning instead of an error. Response shape: { results: [...], errors: [{ id, status, message }] }.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and idempotent. The description adds valuable behavior: it may return warnings instead of throwing errors, and degrades to last-synced balance when upstream is unavailable. This complements the annotations well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: it starts with the core purpose, then parameter guidance, then error handling and response shape. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema) and annotations present, the description covers all essentials: purpose, parameter usage, error scenarios, degradation behavior, and response shape. It is fully adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by explaining the parameter (account_ids as array, 1–50 constraint). It provides necessary usage context without being overly verbose.
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 'Returns real-time balance payload per account id' with a specific verb and resource. It distinguishes from siblings like openfinance_get_accounts_detail which likely return account details, not balance. It also covers error handling details.
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 such as array size limit (1–50) and scenarios with warnings, but does not explicitly guide when to use this tool vs alternatives or when not to use it. The use case is implied but lacking exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_accounts_detailAReturns full account objects including extended creditData (additional cards, limits) per id (GET /accounts/:id). Pass account_ids as an array (1–50). { results, errors } batch shape. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: credit limits and balances may be unreliable (e.g. a limit near 1,00) until the provider recovers. Do not present those values as real.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral context: it may include a `provider_incident` block indicating that credit limits and balances could be unreliable. This alerts the agent to potential data quality issues, which is highly valuable for correct tool usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise at four sentences, with key information front-loaded. The first sentence states the core purpose, the second explains the output shape, the third addresses the special `provider_incident` case, and the fourth provides a specific usage warning. No extraneous content.
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 that there is no output schema, the description adequately explains the return structure (full account objects with creditData, batch `results/errors`, and potential `provider_incident`). It covers the most important behavioral nuance. However, it does not detail the fields within an account object, which might be assumed from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, but the description compensates by explaining `account_ids` as an array (1–50 elements). This adds meaning beyond the raw schema, specifying both the data type (array of strings) and the length constraint. However, it does not describe individual string format beyond being IDs.
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 full account objects including extended creditData per ID. It specifies the endpoint pattern and the required parameter `account_ids`, making the purpose unambiguous. While it doesn't explicitly distinguish from `openfinance_list_accounts`, the focus on extended data and batch retrieval by IDs implies a distinct use case.
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 important usage context: it notes the batch shape `{ results, errors }` and warns about the `provider_incident` block causing unreliable data when the provider has an OPEN incident. This helps the agent decide when to trust the data. However, it does not explicitly state when to use this tool over siblings like `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_credit_card_billAReturns bill-level detail for one or more credit card bills by id (GET /bills/:id): financeCharges and payments[] (id, paymentDate, amount, valueType, paymentMode). Does NOT return individual transactions — to get itemized credit card transactions (purchases, subscriptions, etc.), use openfinance_list_transactions with the credit card account_id and a from/to date range matching the bill's billing cycle (approximately dueDate − 30d to dueDate); each transaction MAY carry a creditCardMetadata.billId hint toward its bill, but it's sparse/inconsistent on some connectors (e.g. Nubank), so do NOT reconstruct a bill total by summing transactions by billId — the bill's own totalAmount is authoritative. Pass bill_ids as an array — use openfinance_list_credit_card_bills first to discover ids. { results, errors } batch shape. NOTE: Pluggy does NOT return a paid/status field. In Brazilian Open Finance, payments[] reflects payments registered during THIS bill's billing cycle — typically the payment of the PREVIOUS bill (do NOT assume this bill was paid just because payments[] is non-empty). To check paid status, prefer openfinance_list_credit_card_bills which derives payment_status via cross-bill match.
| Name | Required | Description | Default |
|---|---|---|---|
| bill_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. The description adds critical behavioral context: Pluggy missing paid/status field, explanation that payments[] in the bill typically pertain to the previous bill, and batch response shape. 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 lengthy but well-structured, with each paragraph adding distinct value (core, non-returns, usage, parameter hints, behavioral notes). A slightly more condensed version could improve, but the current form is still clear 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 no output schema, the description covers the returned fields, what is excluded, interactions with sibling tools, and important caveats about payment interpretation. It is complete for a read-only retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully explains the single parameter bill_ids: its type (array), its purpose, and how to obtain valid values (via list bills). This compensates for the absent 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 starts with a clear verb ('Returns'), specific resource ('bill-level detail'), and explicit fields (financeCharges, payments). It immediately distinguishes from sibling openfinance_list_transactions by stating what it does NOT return.
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_transactions for itemized transactions, use openfinance_list_credit_card_bills to discover bill IDs, and warns against reconstructing totals from transactions. Includes a note about paid status and an alternative tool for that purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_item_statusAReturns the current status of a bank connection (UPDATED, UPDATING, LOGIN_ERROR, etc.), its executionStatus, connector metadata, and a reconnect_url that reopens the widget in UPDATE mode for that connection (re-authenticate / enter MFA token in place, without disconnecting and without consuming a connection slot). Omit item to get the status of ALL linked banks at once (returns { count, items }); pass item for a single bank.
Bulk support: accepts item_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| item_id | No | ||
| item_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that the reconnect_url allows re-authentication without disconnecting and without consuming a connection slot, which is useful behavioral context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (4 sentences) and well-structured, front-loading the core purpose and then providing parameter guidance. Every sentence adds value 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 moderate complexity and lack of an output schema, the description explains the key return fields and behavior. It could be more complete by detailing the full return structure, but it sufficiently covers the essential information for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain parameters. It clarifies that omitting 'item' returns all banks and passing 'item' targets a single bank, and mentions 'item_ids' for bulk. However, it does not differentiate between 'item' and 'item_id' (both strings in the schema), leaving ambiguity about their distinct use. This gap lowers the score.
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 the current status of a bank connection, including specific fields like status, executionStatus, connector metadata, and reconnect_url. It distinguishes between retrieving status for all linked banks vs a single bank, and mentions bulk support. This is specific and differentiates it from siblings that list connections or perform other actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to omit or pass the 'item' parameter to get all vs single bank status, and mentions batch execution via 'item_ids'. It lacks explicit exclusions or when-not-to-use scenarios, but the context is sufficient for an agent to decide when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_loan_detailAReturns full loan contract detail by id (GET /loans/:loanId): interestRates[] (taxType, ratePercentage, indexer), contractedFinanceCharges[], balloonPayments[], warranties[], installments schedule (installmentsCount, paidInstallments, numberOfInstallmentsRemaining, installmentFrequency), amortizationScheduled, CET, ipocCode and dates. Use after openfinance_list_loans to deep-dive on a specific contract. Pass loan_ids as an array (1-50). { results, errors } batch shape.
| Name | Required | Description | Default |
|---|---|---|---|
| loan_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds batch shape '{ results, errors }' and the array size limit, but does not cover error behavior or authentication needs. This adds moderate 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?
Three sentences: first lists fields, second gives usage guidance, third specifies parameter and return shape. No wasted words, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists many fields and mentions batch response shape, covering core functionality. Missing explicit structure of the response object (nested fields, types) but sufficient for a simple retrieval tool with good 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 coverage is 0%, so description must compensate. It explains loan_ids as an array of 1-50 items and notes the batch return shape, but does not clarify that items are loan ID strings or the format of each item. Provides some meaning beyond schema 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 the tool returns full loan contract detail by ID (GET /loans/:loanId) and lists specific fields returned, which distinguishes it from sibling tools like openfinance_list_loans (which likely provides summaries).
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 'Use after openfinance_list_loans to deep-dive on a specific contract,' providing clear context for when to use this tool. Also specifies the parameter format (array of 1-50 loan_ids) but does not mention when to avoid using it.
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?
Beyond annotations (readOnlyHint, idempotentHint), the description discloses that credit card balance meaning is connector-dependent, and that provider_incident and identity_notice blocks may appear with special handling instructions. 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 detailed and front-loaded with the primary function. While long, each section adds necessary context (e.g., credit balance nuance, provider incidents). Some redundancy could be trimmed, but structure is logical.
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, but the description fully explains the return fields and special cases (provider_incident, identity_notice). Covers usage scenarios and integrations with Open Finance environment. Complete for the tool's 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?
With 0% schema coverage, the description adds significant meaning: explains `item` (optional, single bank), `type` (enum filtering), `item_ids` (bulk execution). However, `item_id` is not explicitly explained, though its role can be inferred.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns accounts for bank connections with specific types (BANK, CREDIT) and fields. It distinguishes from sibling tools like openfinance_list_credit_card_bills by mentioning that for standardized bill amounts, that tool should be used instead.
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: omit `item` to list all bank connections, pass `item` for a single bank. Also directs users to openfinance_list_credit_card_bills for standardized bill amounts. Mentions bulk support via item_ids.
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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that the response is cached and is a single aggregated response with no batch ids, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words. All information is front-loaded and essential. Efficient and clear.
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 lacking an output schema, the description fully explains the return structure (fields like id, description, parentId) and mentions caching and single response. Complete for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters (0 params, schema coverage 100%). The description adds value by explaining the meaning and structure of the output fields, which is not covered by the schema, making it highly helpful.
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 Pluggy's transaction category taxonomy, cached for the session, and explains the fields in each entry. It is distinct from sibling tools as no other tool lists categories.
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 obtaining category IDs to use with openfinance_update_transaction_category, but does not explicitly state when to avoid using it or alternatives. However, given it is the only category listing tool, the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_connectionsAReturns the saved bank connections for this install: connector_id, item_id, bank name, a per-connection reconnect_url, and an add_connection_url to link additional banks via the Open Finance widget. The reconnect_url reopens the widget in UPDATE mode for that EXISTING connection (user re-enters credentials / MFA token and the data refreshes in place) — use it when a connection needs re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data). It does NOT consume a connection slot and does NOT require disconnecting first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: explains that reconnect_url opens in UPDATE mode, does not consume a connection slot, and does not require disconnecting. This goes beyond annotations with 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 two sentences, conveying all necessary information without fluff. The second sentence is somewhat lengthy but remains focused. Could be slightly restructured but is reasonably 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 no output schema, the description adequately explains the returned fields (connector_id, item_id, bank name, URLs) and their semantics. It covers the purpose and behavior of the URLs sufficiently for a simple list tool with full annotation coverage.
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 (baseline 4 per rules). Schema coverage is 100% and description adds no parameter info since there are none. Score reflects baseline.
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 saved bank connections and lists specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes from sibling list tools like openfinance_list_accounts and openfinance_list_transactions which focus on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance for the reconnect_url (for re-authentication, MFA, LOGIN_ERROR, stale data) which indirectly helps when to use the list tool to obtain those URLs. However, it lacks explicit context on when to call the list tool itself versus other connection-related tools like 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_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?
Discloses critical behavioral traits beyond annotations: payment timing rules (cycle vs. due date), connector asymmetry (open bill availability), bill grouping reliability warnings, and derived payment_status logic. Annotations indicate readOnlyHint and destructiveHint false, which are consistent; description adds value without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-organized: front-loaded with primary fields, then payment semantics, open bill, connector asymmetry. Every section serves a purpose, but minor redundancy could be trimmed. Structure with clear sectioning aids 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?
Given the tool's complexity (5 params, no output schema), the description covers all necessary aspects: precise field definitions, payment derivation algorithm, open bill availability, error handling, cross-bank identification, and warnings about transaction-level consistency.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description fully explains each parameter: account_id required, include_open_bill opt-in with trade-off (extra scan), account_ids for batched execution, page and page_size for pagination. Adds meaning beyond the schema's mere type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns CLOSED credit card bills for a CREDIT-type account, listing key fields (dueDate, totalAmount, payments[], etc.) and distinguishes from sibling tools like openfinance_list_transactions by noting this tool provides bill-level summaries, not individual 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 extensive when-to-use guidance: explains when not to rely on payments[] for payment status, specifies when to use openfinance_list_transactions for itemized purchases, and advises against using the CREDIT account's balance variable due to connector differences.
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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds critical behavioral details: error handling returns empty structure instead of throwing, data integrity checks for zeroing, and flagging suspect rows. 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 detailed but front-loaded with the main purpose. It includes multiple paragraphs, but each sentence provides value (error handling, data integrity, bulk support). Could be slightly more concise, but structure is clear.
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 output fields, error handling, and data integrity well. However, it does not explain pagination parameters (page, page_size) or all input parameters, leaving some gaps for 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?
Input schema has 6 parameters with 0% description coverage. The description only mentions 'Bulk support: accepts item_ids' and does not describe item, page, page_size, type, or item_id. With low schema coverage, more parameter descriptions are needed.
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 the investment portfolio for a connection, listing specific investment types (FIIs, stocks, etc.), and distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on portfolio 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?
The description mentions bulk support with item_ids but does not explicitly state when to use this tool versus alternatives (e.g., openfinance_list_investment_transactions) or when not to use it. It implies usage for portfolio listings but lacks direct guidance.
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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds batched execution support and itemized field details (e.g., expenses breakdown). 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?
Two sentences plus a short paragraph; no unnecessary words. Front-loaded with key info. Could be more structured, but efficient overall.
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 4 parameters and no output schema, the description covers main functionality and prerequisites but lacks details on pagination parameters, reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains investment_id and investment_ids (bulk), but does not describe page or page_size parameters, leaving a 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?
Clearly states it returns movement history for investment positions, lists movement types (BUY/SELL/TAX/etc.) and fields. Distinguishes from siblings like openfinance_list_transactions by specifying it's for investment positions and should be used after 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?
Provides explicit prerequisite: 'Use after openfinance_list_investments to get the investment_id.' Also mentions bulk support. Does not explicitly state when not to use, but 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_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 already indicate safe read operation; description adds GET endpoint, sequential execution with rate limiting, and response structure `{results, errors}`.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences front-load purpose, then parameter usage, then behavior; no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema but description states return format. Covers parameter, behavior, and result structure. Siblings differentiate single vs list. Adequate for a simple 1-param 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 has 0% description coverage; description fully explains `items` as array of connection selectors (uuid, connector_id, connector_name) and the semantic difference between providing and omitting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists loan contracts per bank connection, referencing the endpoint and distinguishing from sibling `openfinance_get_loan_detail` by scope and behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance on using `items` parameter for specific connections or omitting for all, with sequential querying and rate-limit spacing. Alternative not mentioned but 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_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?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds rich behavioral context: pending/posted variation by connector, sparse billId population, auto-pagination up to 5000 ceiling with truncation warning, manual pagination behavior, error returns instead of throwing, provider incident block, and bulk support. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is lengthy but well-structured with clear paragraphs for pagination, detail levels, and credit card specifics. Every sentence adds value, and key information is front-loaded. A slightly more concise version could achieve a 5, but the current organization makes it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema), the description covers all aspects: pagination modes, detail choices, error handling, credit card nuances, bulk support, provider incidents, and cross-references to sibling tools (openfinance_list_credit_card_bills, openfinance_get_item_status, openfinance_list_accounts). It is fully self-contained and prepares the agent for real-world 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?
Input schema has 0% description coverage, so the description carries the full burden. It explains all 8 parameters: from/to (ISO dates), page, page_size, detail (enum compact/rich/raw with usage guidance), account_id, account_ids (bulk), and search_queries (case-insensitive substring, OR semantics). The description adds significant meaning beyond the schema's bare structure.
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 transactions for a bank account, with specific distinction for CREDIT accounts. It distinguishes from sibling tools like openfinance_list_credit_card_bills (for bills) and openfinance_list_transactions_by_item (different scope). The description explains that for CREDIT accounts, this is the ONLY way to get itemized transactions, making its purpose unique and 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?
Extensive guidance on when to use this tool vs alternatives: only way for credit card itemized transactions, not for reconstructing bills (use openfinance_list_credit_card_bills for standard totals), and when to check connection health via openfinance_get_item_status. Also provides explicit instructions on pagination modes, date filters, search queries, and detail levels.
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?
Adds significant behavioral context beyond annotations: internal account resolution, 5k-per-account cap with truncation flag, provider incident warnings, and granularity/detail behavior. 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?
Dense but well-structured with front-loaded purpose. Some redundancy (e.g., repeating 'entradas/saídas' definitions) could be trimmed, but overall 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?
Comprehensive for a complex tool with 9 params and no output schema: covers return format, edge cases (truncation, incident), and bulk mode.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description explains all major parameters (item, from/to, granularity, detail, type, top_n) with concrete examples and semantics, fully compensating.
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 provides consolidated cash-flow analysis for a whole bank connection in one call, distinguishing it from sibling tools that require separate account listing calls.
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 describes when to use (for cash-flow analysis, specific Portuguese queries) and when to use different granularity/detail options; contrasts with alternatives like openfinance_list_transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_provider_statusAChecks the LIVE operational status of the Open Finance provider (its public status page) — this is the PROVIDER's health, separate from your own connection's openfinance_get_item_status. Use it whenever data looks incomplete or stale even though a connection shows UPDATED (accounts/transactions/balances missing, a bank not returning everything): it reveals an upstream outage or a known incident on a specific bank/connector, so you can tell a provider-side problem apart from a connection that just needs reconnecting. Returns the global indicator (none/minor/major/critical), degraded components, open incidents, and — when you have banks connected — flags the incidents that affect YOUR connected banks in your_banks_affected.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral context: it is LIVE (real-time), checks an external status page, and returns incident details filtered to connected banks. 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 efficiently structured: first sentence states core purpose, second explains use case, third lists return values. No redundant sentences, all information is valuable.
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 sufficiently explains return values (global indicator, degraded components, open incidents, your_banks_affected). The use case is fully covered, and the tool's role among siblings is well-defined.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and the description concisely explains what the tool does without needing any input. Schema coverage is 100%, and the description adds no unnecessary param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the LIVE operational status of the Open Finance provider's public status page, distinct from the own connection status via openfinance_get_item_status. It specifies what is returned: global indicator, degraded components, open incidents, and affected banks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use it (when data looks incomplete/stale despite UPDATED connection) and contrasts with the sibling openfinance_get_item_status, providing clear diagnostic guidance.
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 readOnly, non-destructive, and idempotent behavior. The description adds valuable context beyond annotations: it explains the caveat about non-Open-Finance connectors needing periodic reconnection, how the user's plan affects visibility of PF/PJ banks, and that the tool never dumps the whole catalog. 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 paragraph that covers all necessary aspects without being verbose. It front-loads the main purpose and then adds details. While it could be more structured (e.g., bullet points), it remains efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description thoroughly explains what the tool returns: connector id, access, audience, linked connections, optional accounts, connect_url, and caveats. It also covers plan behavior and edge cases, making it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so the description must explain parameters. It does: keywords[] is described as required and illustrated with examples, and include_accounts is explained to return accounts when true. This adds meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool searches bank connectors by name and returns specific fields like connector id, access type, audience, linked connections, and a ready connect_url. It distinguishes itself from sibling tools like 'openfinance_list_connections' by focusing on search with keywords and providing a one-click link.
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 call this tool before connecting to hand the user a one-click link. It mentions that keywords[] is required and that without it a hint is returned. While it doesn't explicitly name alternatives, the context makes it clear when this tool should be used relative to other connection-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_update_transaction_categoryAInspectCorrects the category of one or more transactions (PATCH /transactions/:id). Pass items as an array of { transaction_id, category_id } — transaction_id comes from openfinance_list_transactions, category_id from openfinance_list_categories. This overrides Pluggy's automatic categorization AND teaches Pluggy: recategorizing a transaction automatically creates a Category Rule for this client (case-insensitive exact match on the transaction's data), so FUTURE similar transactions are categorized the same way — use this to fix miscategorized transactions and improve categorization accuracy going forward. Batch shape: returns { updated, results: [{ transaction_id, category, categoryId }], errors: [{ id, status, message }] } — per-item errors do not fail the whole batch.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral traits beyond annotations: it overrides automatic categorization and teaches Pluggy by creating a Category Rule for future similar transactions. It also notes that per-item errors do not fail the whole batch. Annotations (readOnlyHint=false, destructiveHint=false) are consistent and the description adds significant context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise, front-loading the core purpose and then detailing side effects and return shape. Each sentence contributes value, though it could be slightly shorter without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (batch update with side effects) and no output schema, the description thoroughly covers the return shape, error handling, and learning behavior. It provides sufficient context for an AI agent to understand the tool's complete behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It explains that items is an array of { transaction_id, category_id }, with transaction_id from openfinance_list_transactions and category_id from openfinance_list_categories. This adds meaning beyond the raw schema, though it doesn't elaborate on parameter formats.
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: 'Corrects the category of one or more transactions (PATCH /transactions/:id).' It specifies the verb 'corrects' and resource 'transactions', and distinguishes from sibling list/get tools by indicating it is an update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that transaction_id comes from openfinance_list_transactions and category_id from openfinance_list_categories, and recommends using this tool to 'fix miscategorized transactions and improve categorization accuracy going forward.' While it doesn't explicitly state when not to use, it provides clear context for appropriate usage.
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?
Description adds behavioral context beyond annotations: conversation array needed for reproduction. Annotations note idempotentHint=true (no contradiction). No destructive behavior mentioned, which aligns with destructiveHint=false.
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 fluff. Could be more structured but efficient for the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple reporting tool with no output schema. Description covers main usage but lacks parameter details. Adequate for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. It only describes the 'conversation' parameter, leaving 'context' and 'message' unexplained. Message is required but no semantics provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reports bugs, missing features, or feedback, using specific verb and resource. It distinguishes from siblings which are all finance-related.
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 to include the conversation array for reproduction, guiding when to use. Does not mention exclusions or alternatives, but context signals indicate this is the only bug-reporting tool.
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, idempotentHint, and destructiveHint. The description adds that it shows 'MCP platform and adapter versions', which provides context beyond the annotations but does not disclose additional behavioral traits.
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, clear sentence with no redundant words. It is front-loaded 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 the tool's simplicity (0 parameters, read-only), the description fully explains the purpose and result. No output schema exists, but the version information is clearly stated.
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 (schema coverage 100%), so baseline is 4. The description adds no parameter info, but none is needed.
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 shows current MCP platform and adapter versions, which is specific and distinct from sibling tools that handle authentication, finance operations, or connection management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are given. The unique purpose implies usage when version information is needed, but there is no guidance on when not to use it or how it compares to other tools.
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 readOnlyHint, idempotentHint, and destructiveHint=false, covering safety profile. The description adds valuable context about the exact data returned (installed MCPs, connection status, accounts, catalog tool counts), going beyond the basic read-only guarantee. There are 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 a single, front-loaded sentence that directly states the purpose and the full scope of the return value. Every word earns its place with no filler or 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?
For a simple, zero-parameter, read-only tool, the description is fully sufficient. It enumerates all key aspects of the returned state, and no output schema exists to clarify further. There are no notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is trivially complete. Per the rubric, a baseline of 4 is appropriate; no parameter explanation is needed in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Returns the current toolkit state' and enumerates the exact contents (installed MCPs, connection status, accounts, catalog tool counts). It uses a specific verb 'Returns' tied to a clear resource, and it is distinct from siblings like show_version or 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?
The description clearly implies when to use this tool: whenever you need a snapshot of the toolkit state. It does not explicitly name alternatives or exclusions, but the context is unambiguous given the tool's role and zero-parameter signature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Sign in to create a connector for this server.