Connect your BV account to AI via Brazil's Open Finance: balances, statements, cards, investments. R
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.4/5 across 25 of 25 tools scored. Lowest: 3.8/5.
Most tools have clearly distinct purposes, such as listing vs. getting details vs. syncing. Some functional overlap exists (e.g., list_accounts vs. list_credit_card_bills both deal with accounts), but descriptions clarify the differences. General tools like authenticate and connect are separate from the openfinance_* family.
The naming follows a consistent verb_noun pattern (e.g., openfinance_list_accounts, openfinance_get_account_balance). General tools like authenticate, connect, and report_bug are also consistently styled with underscore separators and lowercase. There is no mixing of conventions.
With 25 tools, the set is slightly on the heavier side but remains well-scoped for the domain of Open Finance integration and marketplace features. Each tool serves a specific purpose, and the count is justified by the breadth of functionality covered.
The tool surface covers core operations: authentication, connection management, listing accounts, balances, transactions, credit cards, loans, investments, category management, syncing, and provider status. Minor gaps exist (e.g., no generic transaction update tool), but the set is largely complete for financial data access and management.
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?
Describes session vs permanent behavior and idempotency (idempotentHint=true supported). No contradictions with annotations, though could clarify if repeated calls overwrite session.
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?
Informative but slightly verbose; front-loaded with purpose, but could be more concise while retaining key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so description should detail return values. It mentions 'get the link' for no-arg call but not what happens with token arg (e.g., success message). Incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description fully explains the token parameter as a JWT string and its purpose, adding essential meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: authentication via browser login or token paste. It distinguishes itself from siblings by being the only auth tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on two modes of use (with and without token) and an alternative (config header for permanent connection), helping the agent choose correctly.
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 indicate read-only, idempotent, non-destructive behavior. The description adds behavioral detail about response states (authenticated:true with empty pending vs. returning connect_urls), which is valuable 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 efficiently convey the tool's purpose and key behavioral details. No wasted words; the most important information is front-loaded.
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 parameters and no output schema, the description adequately covers the main scenarios. However, it does not describe other possible states (e.g., partial connections), which might be needed for full 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?
There are no parameters, so schema coverage is 100%. The description does not need to add parameter info, and it already provides response semantics. Baseline for 0 params is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns connection status and URLs, and provides specific scenario examples (all connected vs. missing credentials). This distinguishes it from sibling tools like 'authenticate' 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 implies use cases (checking connection status, obtaining connect URLs) but does not explicitly state when to use this tool versus alternatives. It provides context for expected responses but lacks direct comparisons to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
marketplaceAInspectThe official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. Covers capability requests like "find an MCP that does X", "consulta um CPF", "is there a tool for Y". Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile (every tool with its id + params, pricing, auth) so you pick the right tool_id → invoke RUNS that tool. KEY: invoke works even when the MCP is NOT installed — it runs the tool pontualmente (one-off), without adding the MCP to the toolkit and without bloating the tool list. If the MCP needs a credential/login, invoke returns a connect link; if it is paid and the wallet is empty, invoke returns a checkout/top-up link (the user opens it, then you retry). Use install only to make an MCP PERMANENT in the active toolkit (its tools then show up natively in future sessions); prefer invoke for a single/occasional use. list_tools lists what is callable right now. subscribe/cancel handle per-MCP billing; report_bug sends feedback; request_mcp asks us to build a NEW MCP when nothing fits. Search/describe flag installed_in_toolkit vs installed_in_workspace. Writes (install/uninstall/subscribe/cancel and the one-off install behind invoke) require workspace owner/admin. It also carries the mcp.ai PROMPT LIBRARY, which is about ready-made prompt TEXT rather than MCPs: search_prompts finds one, get_prompt returns its full text with {{variables}} filled, and publish_prompt saves a prompt and returns a shareable mcp.ai/p/ link that opens without login.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | No | ||
| action | No | search | |
| mcp_id | No | ||
| message | No | ||
| tool_id | No | ||
| arguments | No | {} | |
| immediate | No | ||
| tier_slug | No | ||
| prompt_body | No | ||
| prompt_slug | No | ||
| prompt_tool | No | ||
| prompt_vars | No | {} | |
| conversation | No | [] | |
| prompt_title | No | ||
| request_name | No | ||
| cancel_reason | No | ||
| cancel_comment | No | ||
| prompt_targets | No | ||
| report_context | No | ||
| prompt_category | No | ||
| request_details | No | ||
| prompt_description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the generic annotations by explaining key side effects: invoke works without installation and runs one-off, install makes the MCP permanent, auth/checkout return links for user action, and writes require admin privileges. It also discloses return behaviors (connect link, checkout/top-up link, shareable prompt link) and the installed_in_toolkit vs installed_in_workspace flags.
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 without visual structure, mixing Portuguese ('pontualmente') with English and covering a huge amount of detail. While much information is valuable, it lacks front-loaded clarity and would benefit from bullet points or section breaks; it reads as a wall of text rather than a concise, scannable guide.
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 (23 parameters, no output schema, many sub-actions), the description is fairly complete: it explains the main workflow, installation vs. one-off invocation, auth/checkout behavior, prompt library, and permission requirements. It omits details on some peripheral parameters (immediate, tier_slug, conversation), but these are less central and the description covers the primary usage scenarios well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the action parameter by enumerating valid values (search, describe, install, invoke, etc.) and explains the role of tool_id in invoke. However, with 23 parameters and 0% schema description coverage, many parameters (limit, query, immediate, tier_slug, cancel_reason, prompt_* fields) are left unexplained, and the description does not explicitly map parameters to their purpose beyond the core flow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as the official mcp.ai marketplace — a catalog of MCPs and the mechanism to run them, covering both capability discovery and prompt library functions. It explicitly describes the core flow (search → describe → invoke) and distinguishes it from sibling tools by positioning it as the central hub versus the specific openfinance/authenticate tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: prefer invoke for one-off use, install only for permanent toolkit inclusion, list_tools for currently callable tools, request_mcp when nothing fits, and subscribe/cancel for billing. It also contrasts the prompt library use cases (search_prompts, get_prompt, publish_prompt) and notes that writes require workspace owner/admin, giving clear usage boundaries.
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 destructiveHint=true. The description adds that the data is deleted and a re-connection URL is returned, but does not detail other behavioral aspects like authorization needs or rate limits.
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, no extraneous text. Each sentence contributes: action, effect, and return value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a vague parameter, the description should clarify the parameter meaning and full return payload. The mention of add_connection_url helps but is insufficient.
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' is not explained. Schema coverage is 0% and the description does not clarify what 'item' represents (e.g., bank ID, connection ID). This hinders correct invocation.
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 action: revokes consent and deletes connection data for a specific bank. It distinguishes from sibling tools like openfinance_list_connections (read-only) by emphasizing destructive 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?
It explains the consequence (data no longer available) and provides a re-connection path via returned URL. However, it does not explicitly state when to use this vs. other tools or prerequisites.
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?
Discloses polling behavior (up to ~60s), return structure (results/errors, status, executionStatus, lastUpdatedAt, synced, needs_action), and handling of MFA with reconnect_url. Also explains wait flag behavior. Adds value 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 packed with valuable information but is slightly lengthy. Every sentence adds value; however, it could be more structured (e.g., separate paragraphs for usage and return details) to improve readability. Still 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?
Extremely comprehensive given the tool's complexity and lack of output schema. Covers all states (success, needs_action, timed_out), return fields, and next steps. No gaps identified.
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 both parameters: wait (boolean, default implied true) and items (array of selectors with examples and special value 'omit'). Compensates completely for 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 clearly states it forces a bank to re-sync connections and waits for completion. It uses specific verbs ('forces', 're-sync') and distinguishes from siblings like openfinance_get_item_status and 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?
Explicitly says when to use: 'when a balance or transaction list looks stale'. Provides alternatives: fire-and-forget with wait: false, and re-check with openfinance_get_item_status if timed out. Distinguishes from disconnecting/reconnecting.
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 indicate readOnly, idempotent, non-destructive. The description adds critical behavioral details: CREDIT accounts return structured warning instead of error, and upstream unavailability degrades to last-synced balance with realtime: false and warning. This goes well beyond annotations and fully discloses behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat lengthy (4 sentences) but each sentence adds distinct value: purpose, input format, error handling, degradation behavior, response shape. It is front-loaded with the primary action. Could be slightly tighter, but no redundancies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides the response shape ({ results, errors }) and explains error/degradation behaviors. For a simple balance endpoint, this covers all necessary context: how to use, what to expect, and edge cases. Complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only defines account_ids as an array of strings with no description. The description compensates fully by specifying it is an array of account IDs, valid range 1-50, and the purpose ('per account id'). This adds essential meaning that the schema lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Returns real-time balance payload per account id' and specifies the resource (account id). It distinguishes from siblings like openfinance_list_accounts (which lists accounts) and openfinance_get_accounts_detail (which gets details) by focusing on balance retrieval. No ambiguity.
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 specifies input format (array of 1-50 account IDs) and handles edge cases like CREDIT accounts and unavailable institutions. It implicitly guides when to use (for balance) but does not explicitly state when not to use or mention alternatives. The usage context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_accounts_detailAReturns full account objects including extended creditData (additional cards, limits) per id (GET /accounts/:id). Pass account_ids as an array (1–50). { results, errors } batch shape. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: credit limits and balances may be unreliable (e.g. a limit near 1,00) until the provider recovers. Do not present those values as real.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark read-only and idempotent. The description adds critical behavioral context: the batch shape ({ results, errors }), the provider_incident block, and a warning not to treat certain values as real. This goes beyond annotations 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 four sentences, front-loaded with the core purpose, and each sentence adds unique information without redundancy or fluff.
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 explains the batch response structure and a key edge case (provider incident). While it does not enumerate all fields, it is sufficient for a detail retrieval tool in a domain where account objects are understood from sibling tools.
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 adds value by specifying the array size constraint (1–50) and the batch shape. This compensates for the schema's lack of parameter documentation, though it does not explain the format of individual account 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 the tool returns 'full account objects including extended creditData' per ID, distinguishing it from listing tools like openfinance_list_accounts and balance tools like openfinance_get_account_balance. The verb 'returns' and resource specification are precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage context (batch of 1-50 IDs, results/errors shape) but does not explicitly guide when to use this tool over siblings. It lacks alternative recommendations or exclusions, leaving the agent to infer applicability.
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?
Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds critical behavioral details: batch shape { results, errors }, absence of paid/status field from Pluggy, and nuance that payments[] might reflect previous bill's payment. These disclosures are not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is somewhat long but well-structured with front-loaded purpose. It contains some redundancy (e.g., repeated emphasis on not summing transactions) and could be slightly more concise 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 no output schema and a single simple parameter, the description thoroughly covers return shape, field details, important caveats about payment status, and typical usage flow. It is complete enough 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 coverage is 0%, so description must compensate. It explains that bill_ids should be passed as an array and suggests using openfinance_list_credit_card_bills to discover ids, but does not elaborate on format expectations (e.g., string lengths, patterns). Adequate for a simple parameter with common sense usage.
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 verb ('Returns'), resource ('bill-level detail for one or more credit card bills'), and specific fields returned. It explicitly distinguishes from sibling tools by stating it does NOT return individual transactions and directs to openfinance_list_transactions for itemized data.
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 on when to use this tool (to get bill-level detail) and when not to (for transactions, use openfinance_list_transactions). Advises to first use openfinance_list_credit_card_bills to discover ids, and warns against reconstructing totals from transactions.
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 indicate read-only, idempotent, non-destructive. The description adds rich behavioral details: the output structure, the reconnect_url behavior (reopens widget in UPDATE mode without disconnecting or consuming a slot), 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 concise and well-structured: first sentence covers core output, second covers usage variants, third mentions bulk support. A bit dense but 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 adequately describes return values (count, items, fields) and usage patterns. Covers all necessary aspects for a simple read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains 'item' and 'item_ids' well, but 'item_id' is not mentioned, creating ambiguity. Partial coverage of parameters reduces 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 it returns the status of a bank connection, lists specific fields (status enum, executionStatus, connector metadata, reconnect_url), and distinguishes between single and bulk operations. This differentiates it from sibling tools like list_connections or get_account_balance.
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?
Usage guidance is explicit: omit 'item' for all, pass 'item' for single bank, use 'item_ids' for bulk. It provides clear context for when to use each parameter, though it does not explicitly mention when not to use it or compare to alternatives.
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, destructiveHint=false, and idempotentHint=true, so the description's addition of batch shape and array limit adds moderate context. However, it does not significantly expand beyond the annotations' safety profile.
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, front-loaded with the core action, and efficient in covering purpose, usage, and return shape without extra fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists many return fields (interestRates, charges, balloonPayments, etc.) and notes the batch shape. It is fairly complete for a detail endpoint, though error handling or response status could be added.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description adds the limit '1-50' and clarifies the input type ('array'), but does not explain the meaning of each item or provide examples. This adds some value but not full compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and resource ('full loan contract detail by id'), clearly distinguishing its purpose from the sibling tool openfinance_list_loans by stating it is for deep-diving on a specific contract. The listed fields further specify the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to use after openfinance_list_loans and mentions the batch limit (1-50 loan_ids) and output shape (`{ results, errors }`). While it does not explicitly state when not to use, the context is clear and sufficient.
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?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: credit balance meaning is connector-dependent, `name` is legal issuer not brand, deduplication for joint accounts, provider_incident block indicating unreliable data, and identity_notice for consent holder differences. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with core functionality and then detailed edge cases. It is efficiently written with no wasted sentences, but its length could be reduced by merging some repetitive explanations. Overall 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?
Given no output schema, the description details all returned fields (balance, number, type, subtype, bankData, creditData, bank, connector_id) and covers complex scenarios (provider incidents, identity notices, credit balance interpretation). It also references related tools for further actions. Comprehensive for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description fully compensates. It explains `item` for targeting a single bank, `type` enum for filtering, `item_ids` for batched execution, and the effect of omitting `item`. However, `item_id` is not explicitly distinguished from `item`, and the explanation is somewhat unstructured, reducing clarity slightly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns accounts for a bank connection, listing specific fields like balance, number, type, subtype, bankData, creditData, bank, and connector_id. It distinguishes between BANK and CREDIT accounts and explicitly differentiates from sibling tools like openfinance_list_credit_card_bills by directing users to that tool for standardized bill amounts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance: omitting `item` for all banks, passing `item` for a single bank, using openfinance_list_credit_card_bills for standardized bill amounts, and handling provider incidents and identity notices. It clearly states alternatives and conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_categoriesAReturns Pluggy's transaction category taxonomy (GET /categories), cached for the adapter session. Each entry has id (the categoryId used by openfinance_update_transaction_category), description (English), descriptionTranslated (Portuguese — prefer this for pt-BR users), parentId and parentDescription (the tree parent). Single aggregated response — no batch ids.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that results are cached for the adapter session and returns a single aggregated response, which is useful 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 that are front-loaded with the core purpose and efficiently detail the fields and usage. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description fully explains the returned fields and their meaning, plus caching and aggregation behavior. It is 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?
No parameters exist, so the schema covers 100%. The description adds value by explaining the returned fields and their relationships (e.g., id used by sibling 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 returns the transaction category taxonomy, specifies the data fields, and distinguishes from sibling tools that consume these categories (e.g., openfinance_update_transaction_category).
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 indicates the categories are used for updating transactions, providing clear context. However, it does not explicitly state when not to use this tool or mention alternatives, though the sibling context makes it less critical.
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, idempotentHint=true, destructiveHint=false. The description adds value by detailing the reconnect_url's behavior (UPDATE mode, no slot consumption) without contradicting 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, but the first is slightly long. However, it is front-loaded with the main purpose and all information is relevant and non-redundant with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only list tool with annotation coverage, the description fully specifies the return fields and key behaviors (reconnect_url semantics). No output schema exists, but the description compensates well.
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 parameters, so the description carries no parameter burden. It adds meaning by listing the output fields (connector_id, item_id, bank name, etc.), which is helpful since no output schema is 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?
The description uses a specific verb ('Returns') and clearly identifies the resource ('saved bank connections') with a list of returned fields. It distinguishes from sibling tools like openfinance_list_accounts by focusing on 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?
Explicitly explains when to use the reconnect_url (re-authentication, MFA, LOGIN_ERROR, stale data) and states the tool does not consume a connection slot or require disconnecting. This helps the agent choose correctly among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_credit_card_billsAReturns CLOSED credit card bills for a CREDIT-type account: dueDate, totalAmount, minimumPaymentAmount, allowsInstallments, plus payments[] (id, paymentDate, amount, valueType, paymentMode), payments_count, payments_total, finance charges aggregates, and a derived payment_status per bill. IMPORTANT — Brazilian Open Finance semantics: Pluggy does NOT return a paid/status field. The payment goes into the payments[] of the bill whose CYCLE contains the paymentDate (closing ≈ dueDate − 7d): pre-payment before close stays on the bill being paid; payment between close and due, or after due, lands on the NEXT bill. So payments[] on a bill commonly carries the previous bill's payment, NOT the current one's — do NOT assume this bill was paid just because payments[] is non-empty. Use the derived payment_status (PAID | OPEN | PAST_DUE_UNCONFIRMED | PAST_DUE_UNPAID): a bill is PAID when its OWN payments[] (early pre-payment) or ANY newer bill in the payload contains a payment with amount ≈ this bill's totalAmount (±R$0.50). The MOST RECENT bill that's past-due, with no own pre-payment match, cannot be confirmed via cross-bill (the next cycle hasn't closed yet) — it returns PAST_DUE_UNCONFIRMED. NEVER call such a bill 'vencida' categorically; flag that the payment may have been made between close and due and not yet reflected upstream. The full payment_status_legend is returned alongside the results. OPEN BILL & TOTAL DEBT (standardized, derived — OPT-IN): pass include_open_bill:true to ALSO get open_bill (the current not-yet-closed bill, próxima a vencer) and total_pending_debt (saldo devedor total = all pending installments), BOTH derived from PENDING transactions so they mean the same thing across connectors — use these instead of the CREDIT account's balance, whose meaning VARIES by connector (some report the open-bill partial, others the full installment debt). open_bill = { available, method (cycle_dates = real close/due dates | calendar_month_fallback = estimated, confidence:'low'), close_date, due_date, total_amount (net charges − credits), transaction_count }; plus a future_bills[] breakdown per month — LOW-confidence forward projections of PENDING installments (confidence:'low', basis), NOT authoritative bills (for closed months trust the results totalAmount). CONNECTOR ASYMMETRY: where the bank does NOT expose the open bill before closing (only closed bills, no reliable cycle dates), open_bill.available is false with a reason (connector_exposes_no_pending or open_bill_not_published) — that bill isn't retrievable by any endpoint until it closes (upstream limit of the institution's Open Finance feed, not our filter); check the bank app for the current open bill. When per-transaction billId grouping does not reconcile with the bills' totals, a bill_grouping_reliability warning is attached (trust totalAmount, do not sum by billId). Default false (the projection runs an extra accounts+transactions scan, so it's opt-in). The response opens with an account echo block ({ account_id, bank, name, number, type, item_id }) identifying WHICH card/bank these bills belong to. When more than one bank is connected, ALWAYS cross-check the echo against the card you intended to query and name the bank when presenting results — never attribute one bank's bills to another. This tool's results are bill-level summaries — NOT individual transactions, and each bill's totalAmount (from the bank) is the AUTHORITATIVE amount. To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id — but note creditCardMetadata.billId is a per-connector hint that can be sparse/inconsistent (e.g. Nubank), so do NOT reconstruct a bill total by summing transactions by billId. Returns a warning instead of failing if the CREDIT_CARDS product is not enabled.
Bulk support: accepts account_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| account_id | Yes | ||
| account_ids | No | ||
| include_open_bill | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds critical context: it returns a warning instead of failing if CREDIT_CARDS product is disabled, explains how payments are attributed to bills (including counterintuitive cross-bill effects), and details connector-specific limitations like open_bill unavailability. 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 very long but well-structured with bold key terms and bullet points. It front-loads the core function and uses whitespace effectively. Could be more concise, but the density of information justifies the length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of Brazilian Open Finance and the lack of output schema, the description covers all essential aspects: return fields, derived payment_status logic, connector asymmetry, open_bill projection confidence, reliability warnings, and cross-referencing with sibling tools. Leaves no critical ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description explains include_open_bill in depth, mentions account_ids for bulk support, and implies account_id usage. However, page and page_size parameters are not described, leaving a gap for pagination 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 it returns closed credit card bills for CREDIT-type accounts, with a specific list of fields. It distinguishes from sibling tools like openfinance_list_transactions (individual transactions) and openfinance_get_credit_card_bill (singular bill), making the tool's specific purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides extensive guidance: when to use include_open_bill, how payment_status is derived, connector asymmetry, and explicit advice to use openfinance_list_transactions for itemized purchases. Also warns about cross-bank attribution and when not to use this tool for open bills.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_investmentsAReturns the investment portfolio for a connection (broker or bank with INVESTMENTS product enabled): FIIs, stocks, ETFs, fixed income (CDB/LCI/LCA/Tesouro), mutual funds, retirement (previdência) and COE. Each row carries balance, amount, amountOriginal, amountProfit, lastMonthRate / annualRate / lastTwelveMonthsRate (when available), dueDate, issuer, ISIN, etc. Returns { total:0, results:[], warning } instead of throwing when INVESTMENTS isn't enabled (403) or other upstream errors. DATA INTEGRITY: when MULTIPLE positions come back as TOTAL_WITHDRAWAL with balance/quantity 0 at once (mass zeroing), the tool cross-checks each position's own transaction history upstream; if the zeroing is contradicted (BUY with no sale/redemption/transfer) the response carries data_integrity_warning and the affected rows are flagged integrity:'suspect_zeroed' — treat those balances as UNAVAILABLE (likely a temporary connector failure publishing zeros), never as real R$0, and do NOT sum them into the portfolio.
Bulk support: accepts item_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| page | No | ||
| type | No | ||
| item_id | No | ||
| item_ids | No | ||
| page_size | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, destructiveHint), the description discloses critical behaviors: returns a safe response on errors instead of throwing, and details the data integrity warning for mass zeroing of positions. This extra context is highly valuable for correct invocation and interpretation.
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 but packs significant detail. It front-loads the main purpose and then logically covers error handling, data integrity, and bulk support. Could be slightly more structured (e.g., bullet points) but is not overly verbose.
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 (portfolio listing with integrity checks), the description covers core behaviors well. However, parameter descriptions are missing, and the return structure is only partially described. No output schema exists, so the description bears the burden, which is mostly but not fully met.
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 only explains 'item_ids' for bulk support. The other five parameters (item, page, type, item_id, page_size) are not clarified at all. The type enum values are listed in the schema but not explained. This is insufficient for an agent to use these parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.) and key fields. This clearly distinguishes it from sibling tools like openfinance_list_investment_transactions, which deals with transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool is for connections with INVESTMENTS enabled and describes error handling when not enabled. It provides implicit context but does not explicitly contrast with alternatives or state when not to use it. The bulk support note adds practical 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, confirming safe read-only behavior. The description adds detail on returned fields but does not contradict annotations. No additional behavioral traits beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with two sentences covering main behavior and fields, plus a usage note. Slightly dense field enumeration, but overall efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Describes return fields in detail despite lacking output schema, and states prerequisite. However, omits pagination behavior with page/page_size and does not fully clarify bulk usage (e.g., how to supply multiple IDs).
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 for bulk support, but does not mention page or page_size parameters, leaving pagination behavior undocumented.
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 movement history for a specific investment position, listing types (BUY/SELL/TAX, etc.) and distinguishing from sibling tools like openfinance_list_investments and openfinance_list_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to use after openfinance_list_investments to get the investment_id, and mentions bulk support. However, does not specify when not to use or provide alternatives beyond the prerequisite.
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?
The description adds behavioral context beyond annotations: sequential querying with rate-limit spacing and the return format per connection ({ results, errors }). Annotations already mark it as read-only and idempotent. No contradiction is present.
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, immediately stating the core function and then detailing parameter usage. Every sentence adds value with no redundancy or fluff. 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 no output schema, the description partially describes the return structure. It could mention potential pagination or error handling details, but for a tool with one optional parameter and a simple list operation, the description is adequately complete. The sequential behavior compensates for missing details.
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 0% description coverage, but the description fully explains the 'items' parameter: what values it accepts (item_id uuid, connector_id, or connector_name), its behavior (one per connection), and the effect of omitting it (list all banks). This exceeds the minimum required compensation for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists loan contracts per bank connection, specifying the HTTP endpoint and differentiating it from sibling tools like openfinance_get_loan_detail. The verb 'list' combined with the resource 'loan contracts' and scope 'per bank connection' makes the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to pass the 'items' parameter and when to omit it, including behavior for multiple connections (sequential with rate-limit spacing). It does not explicitly mention when not to use this tool (e.g., preferring a detail tool for a single loan), but the context is clear enough for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_transactionsAReturns transactions for a bank account (BANK or CREDIT type). For CREDIT (credit card) accounts, this is the ONLY way to get itemized transactions (purchases, subscriptions, etc.). Each credit card transaction MAY carry creditCardMetadata.billId pointing at a bill from openfinance_list_credit_card_bills, but this is a per-connector HINT, not authoritative: some connectors (e.g. Nubank) populate it sparsely (many transactions and installments arrive with no billId) or inconsistently (the same payment tagged to more than one bill). Do NOT reconstruct a bill's total by summing transactions by billId — the bill's own totalAmount from openfinance_list_credit_card_bills is the source of truth. CREDIT PENDING vs POSTED varies by connector: where the bank exposes future-dated status:'PENDING' installments, those represent the OPEN bill plus future bills (future months); where it does NOT, only the last closed bill's POSTED items appear until ~closing. Same query, different coverage per bank (upstream). To get a standardized open-bill total / total debt regardless, use openfinance_list_credit_card_bills (open_bill / total_pending_debt). Supports from/to date filters (ISO YYYY-MM-DD) and an optional keyword filter via search_queries (case- and accent-insensitive substring match against description and merchant name, OR semantics across multiple terms). When search_queries is set the tool aggregates up to 5000 transactions within from/to before filtering — narrow from/to if truncated:true is returned. PAGINATION: OMIT both page and page_size (the default) to get ALL transactions in the from/to range in one call — the tool auto-paginates the upstream and returns them under a single logical page (page:1, totalPages:1), up to a 5000 ceiling (truncated:true + warning if exceeded, then narrow from/to). Passing page and/or page_size switches to MANUAL pagination: you get one page (page_size items, default 50, max 500; page defaults to 1) with the REAL total/totalPages, so page_size:5 alone returns the first 5 with totalPages telling you how many pages remain. On upstream errors, returns { total:0, results:[], warning, error } instead of throwing. detail controls how much per-row data you get (default 'compact' = slim, cheap). Use detail:'rich' to enrich each row (when the bank connector provides it) with merchantInfo (estabelecimento: businessName/razão social, cnpj, cnae, category — useful for auto-classifying spending) and extra creditCardMetadata fields: billId (a per-connector HINT toward the transaction's bill — sparse/inconsistent on some connectors like Nubank, so do NOT sum by it to get a bill total; use the bill's totalAmount instead), purchaseDate, payeeMCC, feeType/feeTypeAdditionalInfo, otherCreditsType/otherCreditsAdditionalInfo. Use detail:'raw' to get the FULL untouched Pluggy transaction object (everything Pluggy returns, un-normalized — heaviest, for when you need a field we don't project). 'rich'/'raw' add tokens per row and coverage varies by bank/Open Finance, so keep the default for normal listings. For the card's statement closing/due dates use openfinance_list_accounts (creditData.balanceCloseDate / balanceDueDate). The response opens with an account echo block ({ account_id, bank, name, number, type, item_id }) identifying WHICH account/bank these transactions belong to. When more than one bank is connected, ALWAYS cross-check the echo against the account you intended to query and name the bank when presenting results — never attribute one bank's transactions to another. If total is 0 for a CREDIT account, check the connection health via openfinance_get_item_status — statusDetail.creditCards.isUpdated: false means the credit card sync failed and a force sync (openfinance_force_sync) or reconnection may be needed. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: transactions may come back incomplete or wrong until the provider recovers, and reconnecting does not fix it.
Bulk support: accepts account_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| page | No | ||
| detail | No | ||
| page_size | No | ||
| account_id | Yes | ||
| account_ids | No | ||
| search_queries | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing credit card pending/posted behavior, auto vs manual pagination, error handling, detail level effects, provider incidents, and connector-specific variability. There is 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 front-loaded with the core purpose. While it contains some repetition (e.g., billId warnings), the depth of information justifies the length. Minor improvements could be made with bullet points or section headings, but overall it is well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (8 parameters, no output schema), the description covers all essential aspects: distinct use cases, parameter behavior, edge cases, error handling, cross-tool references, and provider incidents. It leaves no critical gap 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 thoroughly explains every parameter: date formats, search_queries semantics, pagination parameters with both manual and auto modes, detail enum values and their impact, and account_ids for bulk. It adds critical meaning not present in the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns transactions for bank accounts (BANK or CREDIT type), and distinguishes it as the only way to get itemized credit card transactions. It differentiates from sibling tools like openfinance_list_credit_card_bills and openfinance_list_transactions_by_item, establishing its unique role.
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 this tool versus alternatives, including warnings about not summing by billId for totals and directing to openfinance_list_credit_card_bills for standardized totals. It explains pagination modes, when to narrow date ranges, and how to handle zero results in credit accounts via health checks.
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: caps at 5000 transactions per account with truncated flag, provider_incident block causing data incompleteness, and that raw granularity is heavier. Annotations already indicate read-only, idempotent, non-destructive, but description enriches with real-world constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded, but slightly long. However, each sentence adds value, covering purpose, usage, parameters, and caveats. Could be slightly more concise but is effective.
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 (9 params, no output schema), the description is remarkably complete. It explains the consolidated output, the raw option, truncation, provider incidents, and bulk execution. No significant 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?
With 0% schema description coverage, the description thoroughly explains all parameters: item, from/to dates, granularity, detail, type, top_n (implied), item_id/item_ids. It clarifies default behaviors and combined usage of granularity and detail.
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 performs consolidated cash-flow analysis for a whole bank connection in one call, using specific verbs like 'list transactions' and 'analyze'. It distinguishes itself from sibling tools like openfinance_list_transactions by noting it resolves accounts internally without needing prior 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?
Provides explicit guidance on when to use this tool: instead of calling openfinance_list_accounts first. Includes specific use-case queries and explains how to target one bank or all banks. Also mentions bulk support with item_ids.
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, idempotentHint=true, and destructiveHint=false, so the tool is non-destructive and safe. The description adds value by specifying the data source (public status page) and the output fields (global indicator, degraded components, open incidents, affected banks), but does not contradict or significantly extend beyond the annotations' implicit safety profile.
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, around three sentences, with the core purpose front-loaded. Each sentence adds value (purpose, usage context, output details). While it is not overly verbose, it could be slightly more streamlined without losing essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description thoroughly covers the tool's purpose, usage context, and the nature of its returns. It explains what the output includes (global indicator, degraded components, open incidents, affected banks) and when to use it, making it complete for an agent to understand and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and schema coverage is 100%, so the baseline is 3. The description does not need to add parameter information, and it does not add any parameter-related semantics beyond the schema, so it meets the baseline without improvement.
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. It uses specific verbs ('checks') and resources ('provider status'), and distinguishes itself from the sibling tool `openfinance_get_item_status` by noting it's separate from the user's connection status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to use this tool: 'whenever data looks incomplete or stale even though a connection shows UPDATED... it reveals an upstream outage'. It contrasts with the sibling tool and provides clear context for its use, effectively guiding the agent on appropriate scenarios.
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, idempotent, non-destructive. The description adds important behavioral context: returns a hint if no keywords, non-Open-Finance connectors have a caveat, and the tool honors user plan (PF hides PJ banks, PJ covers both). 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 somewhat long but front-loaded with the main purpose and then details. It is well-structured, though slightly verbose. Every sentence adds value, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description thoroughly explains what is returned: connector id, access type, audience, linked connections, accounts (if include_accounts), and connect_url. It also covers plan behavior and caveats, making the tool fully understandable.
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 compensates by explaining that 'keywords' is an array of strings (e.g., ['nubank','btg']) and is REQUIRED despite not being marked as such. It also explains the 'include_accounts' toggle. It adds meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'searches', the resource 'bank connectors', and the scope 'by name'. It lists the return fields and special caveats, and it distinguishes itself from sibling tools like 'connect' by specifying it is the preparatory step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Call this BEFORE connecting to hand the user a one-click link to the right bank.' It also implies not to call without keywords. However, it does not explicitly mention alternatives among siblings, 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_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, teaches Pluggy by creating a Category Rule for similar future transactions, and handles batch errors per item. No contradiction with annotations (readOnlyHint=false, 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?
The description is comprehensive but somewhat verbose; however, every sentence contributes value. The main purpose is front-loaded, and the structure logically flows from action to parameters to side effects to response shape.
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 lack of output schema, the description fully explains the return format (updated, results with per-item details, errors). It covers side effects, batch behavior, and parameter semantics, making the tool's usage complete and understandable.
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 the `items` parameter structure, including required fields (transaction_id, category_id) and their sources (openfinance_list_transactions, openfinance_list_categories). This 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 clearly states the tool corrects transaction categories, specifies the HTTP method (PATCH /transactions/:id), and explains the input format. It distinguishes itself from related tools like openfinance_list_transactions and openfinance_list_categories by referencing their output as input sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (fix miscategorized transactions, improve future categorization) and provides prerequisites (IDs from other tools). It warns about the side effect of creating a Category Rule. However, it does not explicitly state when not to use it or mention alternatives beyond the linked list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
report_bugAReport a bug, missing feature, or send feedback. Include the conversation array with recent messages for reproduction.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| message | Yes | ||
| conversation | No | [] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the agent knows it's a write operation but not destructive. The description adds that the conversation array should be included for reproduction, which is useful but doesn't significantly expand 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?
The description is two sentences, front-loads the purpose, and contains no superfluous words. Every sentence provides essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (3 parameters, no output schema, no nested objects), the description is largely complete. It covers the main action and key parameter guidance, though it could optionally mention what happens after a report is submitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'conversation' parameter ('include the conversation array with recent messages'), but 'message' and 'context' are not described. This provides partial but incomplete parameter information.
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 action 'Report' and the resources 'bug, missing feature, or send feedback', distinguishing it from the sibling tools which are primarily Open Finance operations. The verb and resource are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reporting issues or feedback but does not explicitly state when to use this tool versus alternatives. No exclusions or 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.
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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying exactly what versions are shown (platform and adapter), providing context beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that gets straight to the point. No unnecessary words or details, front-loading the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description fully covers what an agent needs to know. The annotations complement it well, making this a complete and minimal definition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema description coverage, the description does not need to add parameter details. The empty schema is self-explanatory, and the description effectively sets expectations for what the tool does.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: showing current MCP platform and adapter versions. The verb 'show' and the resource 'version' are specific, and it distinguishes itself from siblings like 'toolkit_info' and 'openfinance_*' tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided, but the tool's simplicity (no parameters, harmless action) makes it clear that it can be used anytime to retrieve version info. The lack of alternatives is acceptable given the tool's straightforward nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
toolkit_infoAReturns the current toolkit state: installed MCPs, their connection status, the accounts connected to each one, and how many catalog tools each exposes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value by specifying the composition of the returned state (installed MCPs, connection status, accounts, tool counts), which is meaningful context beyond the annotations. 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?
A single, front-loaded sentence states the action and the complete return payload. Every word earns its place; there is no fluff or repetition of schema/annotation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple nature (no params, no output schema), the description sufficiently lists the key pieces of information returned. It does not describe the exact structure or format of the returned data, but for a status/summary tool this is adequate and matches the tool's low 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?
The tool has zero parameters, and the schema coverage is 100% (empty properties object). The baseline for zero-parameter tools is 4, and the description correctly focuses on return content rather than parameter details. Nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') with a clear resource ('current toolkit state') and enumerates exactly what is included: installed MCPs, connection status, accounts, and catalog tool counts. This clearly distinguishes the tool from siblings like openfinance_* data tools and show_version.
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 makes the tool's purpose obvious, so when to use it is implied: whenever one needs an overview of the toolkit's setup and connectivity. However, it does not explicitly mention alternatives or provide when-not-to-use guidance, so usage guidance is adequate but not explicit.
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.