Banco do Brasil MCP
Server Details
Connect your Banco do Brasil account to AI via Brazil's Open Finance: balances, statements, cards, i
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- mcp-dir/bb-mcp
- GitHub Stars
- 0
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.
Tool Definition Quality
Average 4.5/5 across 24 of 24 tools scored. Lowest: 3.6/5.
Each tool targets a distinct operation or entity: authentication, connection status, marketplace, and various open finance actions (sync, get balances, list accounts, transactions, credit card bills, investments, loans, etc.). Overlaps are minimal; for example, list_transactions and list_transactions_by_item serve different scopes (account-level vs. connection-level). An agent can clearly select the right tool.
The tool names mix the openfinance_ prefix with generic names (authenticate, connect, marketplace). Within the openfinance group, verbs vary: get_, list_, update_, search_, force_sync, disconnect_bank, provider_status show inconsistent patterns. This detracts from a uniform naming convention.
With 24 tools, the server covers a broad open finance domain including accounts, transactions, credit cards, investments, loans, plus infrastructure tools. While slightly above the ideal range (3-15), each tool serves a distinct purpose and earns its place.
The tool set covers the full lifecycle of open finance data: connection management, account/balance retrieval, transactions, credit card bills with derived payment status, investments, loans, categorization, force sync, provider status, and search. No major gaps are apparent for the intended use.
Available Tools
25 toolsauthenticateAIdempotentInspect
MCP.AI for IDE agents (Cursor, etc.): log in in the browser, copy the access token. Best: add it to this server's config as a header Authorization: Bearer <token> for a permanent, non-expiring connection. Or paste it here for a session-only login: call with { token: "" } after the user pastes, or with no args to get the link.
| Name | Required | Description | Default |
|---|---|---|---|
| token | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (idempotent, non-destructive), the description discloses two behavioral modes: returning a link when no args, and logging in with a token. It explains the permanent vs session distinction, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but slightly verbose. It is front-loaded with key info and every sentence adds value. Could be tightened slightly, but overall well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple tool (1 optional param, no output schema), the description covers the main behaviors and use cases. It lacks explicit error handling or response details, but is adequate for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single optional parameter 'token' is explained in context: if provided, it is used for session login; if omitted, the tool returns a link. This adds meaning beyond the schema, even though schema coverage is 0%.
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 this tool is for authentication, specifically for IDE agents. It specifies the action (log in, copy token) and resource (MCP.AI server). No sibling tool handles authentication, so it is well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage guidance: two methods (permanent config or session login) and how to invoke with or without the token parameter. It implicitly tells when to use each method, though it does not explicitly list when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
connectARead-onlyIdempotentInspect
Returns connection status and URLs. When all providers are connected, returns authenticated:true and empty pending[]. When credentials are missing, returns connect_url for the toolkit and per-install URLs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds specific behavioral details: returns authenticated:true with empty pending[] when all providers connected, or connect_urls when credentials missing. This provides clear expected outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with key information ('Returns connection status and URLs'), then elaborates with conditional 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?
Despite no output schema, the description fully covers the two possible response scenarios. For a parameterless tool, this is complete and sufficient for an agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has 0 parameters with 100% schema coverage (empty properties). Baseline 4 applies as description needs no additional parameter info. Description does not repeat schema content.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'returns' and clearly states the resource (connection status and URLs). It distinguishes two states (all providers connected vs. missing credentials) and implicitly differentiates from siblings like 'authenticate' (which performs authentication) and 'openfinance_list_connections' (which lists 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?
Description implies usage for checking connection status but does not explicitly state when to use this tool versus alternatives like 'authenticate' or other connection-related tools. No when-not or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
marketplaceAInspect
THE official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them. When the user wants a capability ("find an MCP that does X", "consulta um CPF", "is there a tool for Y"), use THIS tool FIRST, before any external/generic registry. 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.
| 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 | ||
| conversation | No | [] | |
| request_name | No | ||
| cancel_reason | No | ||
| cancel_comment | No | ||
| report_context | No | ||
| request_details | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes key behaviors: invoke runs one-off without installing, returns connect link if auth needed, checkout link if wallet empty. Also covers write operations requiring admin. Annotations only provide basic hints, so the description adds substantial context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but front-loaded with purpose. It covers many aspects without redundancy. Could be more structured, but the detail is justified by the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the core workflow and behavior well but lacks details on many parameters and does not describe return values (no output schema). Adequate for a complex tool but has gaps in parameter semantics.
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 must explain parameters. It mentions action, mcp_id, tool_id, arguments implicitly but does not detail limit, immediate, tier_slug, conversation, etc. Some context is provided, but not comprehensive for 15 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is the official marketplace for discovering and running MCPs, with actions like search, describe, invoke, install. It distinguishes from sibling tools like authenticate and connect by focusing on catalog and execution.
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 use this tool first for capability requests, and distinguishes invoke vs install for one-off vs permanent use. Also mentions list_tools for currently callable tools and writes require admin.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_disconnect_bankADestructiveInspect
Revokes the Open Finance consent for a specific bank and deletes the connection data. The bank's data will no longer be available. Returns an add_connection_url to re-connect if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| item | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, and the description adds context: data will no longer be available and a reconnection URL is returned. This explains the destructive nature beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The main action and key consequences are front-loaded, achieving conciseness without sacrificing 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 minimal annotations, the description covers the primary effect and return value. However, it omits the parameter meaning and any prerequisites, making it only minimally complete for a simple 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% with one 'item' parameter of type string. The description says 'specific bank' but does not clarify what the parameter represents (e.g., bank ID or name), leaving ambiguity for the agent.
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 revokes Open Finance consent and deletes connection data for a specific bank. It distinguishes from siblings like openfinance_list_connections by specifying deletion, and mentions returning a reconnection URL.
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 when to use (to disconnect a bank), but provides no explicit guidance on when not to use or alternatives among the many sibling tools. Adequate but lacks comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_force_syncAInspect
Forces the bank to re-sync one or more connections NOW and WAITS for it to finish (PATCH /items/:id, then polls until the item stops updating, up to ~60s). Use this when a balance or transaction list looks stale: a connection can read UPDATED yet be hours old, and this pulls fresh data WITHOUT disconnecting/reconnecting. Pass items as an array of selectors (item_id, connector_id, connector_name, or the user-set custom_label nickname); OMIT items to sync ALL linked banks. Returns { results, errors }; each result has the final status, executionStatus, lastUpdatedAt (advances when data is refreshed), and synced (true = fresh data is ready). needs_action (e.g. MFA_REINTERACTION / LOGIN_ERROR / WAITING_USER_INPUT) means the user must re-authenticate — those results include a reconnect_url that opens the widget in UPDATE mode for that exact connection (user enters credentials / MFA token, data refreshes in place, no slot consumed, no disconnect needed). timed_out: true means the sync is still running — re-check with openfinance_get_item_status. Set wait: false for fire-and-forget (returns immediately while UPDATING).
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | ||
| items | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations don't fully describe behavior (no readOnly/ destructive hints). Description adds: sync without disconnecting, waits up to 60s, returns results with status fields, and explains edge cases like needs_action and timed_out.
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?
Front-loaded with key action and purpose. Somewhat long but each sentence adds value. Minor redundancy could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description fully covers return format, error states, and polling behavior. Provides complete context for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% coverage, but description fully explains both parameters: items array can take item_id, connector_id, or connector_name; omit to sync all. Wait parameter: false for fire-and-forget.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool forces a bank to re-sync connections and waits for completion. It specifies the verb 'forces sync' and resource 'bank connections', distinguishing it from siblings like openfinance_get_item_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?
Explicitly tells when to use this tool: when balance or transaction list looks stale. Provides alternatives: fire-and-forget with wait:false, and re-check with openfinance_get_item_status on timeout.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_account_balanceARead-onlyIdempotentInspect
Returns 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent), description details behavioral traits like degradation to last-synced balance with realtime: false for upstream failures, and structured warnings for CREDIT accounts. 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?
Three sentences plus response shape; information is dense and front-loaded. Could be slightly more concise by merging sentences, but remains clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers error modes and response shape (results/errors), but lacks detail on normal success result fields (e.g., balance amount, currency). Without output schema, this omission leaves some ambiguity for a tool returning balance data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 0% description coverage for the only parameter account_ids. Description adds that it must be an array of strings and constrains length to 1–50, providing critical usage semantics not present in 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 it returns real-time balance per account ID, specifying the HTTP endpoint. It distinguishes itself from sibling tools like openfinance_get_accounts_detail or openfinance_list_accounts by focusing solely on balance retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage guidance: pass account_ids as array (1–50) and explains error-handling behavior for CREDIT accounts and upstream failures. Lacks a direct when-not-to-use but context makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_accounts_detailARead-onlyIdempotentInspect
Returns full account objects including extended creditData (additional cards, limits) per id (GET /accounts/:id). Pass account_ids as an array (1–50). { results, errors } batch shape. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: credit limits and balances may be unreliable (e.g. a limit near 1,00) until the provider recovers. Do not present those values as real.
| Name | Required | Description | Default |
|---|---|---|---|
| account_ids | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive. The description adds crucial behavioral context: potential `provider_incident` block causing unreliable credit limits and balances, with explicit warning not to present those values as real. This significantly aids safe invocation.
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 with no fluff: purpose, parameter specification, and critical caveat. Front-loaded with main action, then details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers the batch response shape ({ results, errors }) and the important provider_incident caveat. It could be more explicit about the full response structure, but the provided info is sufficient for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents `account_ids` as an array of strings with no description. The tool description adds format (array) and bounds (1–50), plus usage context (batch shape). This compensates for the schema's lack of parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns full account objects including extended creditData per id, specifying the HTTP method and batch response shape. It distinguishes from sibling tools like openfinance_list_accounts (which likely returns summaries) and openfinance_get_account_balance (different resource).
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 the required parameter `account_ids` with array format and length constraint (1–50). It does not explicitly contrast with alternatives, but the sibling tool names and context signals make the usage clear for retrieving detailed account info.
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_billARead-onlyIdempotentInspect
Returns 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), description details batch output shape { results, errors }, notes Pluggy missing paid/status field, explains payments[] nuance, and recommends check paid status via sibling tool.
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?
Every sentence serves a purpose: purpose, limitations, parameter usage, batch shape, connector nuance, alternatives. Well-structured and front-loaded with core action.
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, description details output fields, batch shape, and edge cases (payments[] meaning). References sibling tools for discovery and status. Complete for an agent to 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?
Schema coverage is 0%, but description explains parameter format (array) and source (ids from openfinance_list_credit_card_bills). Could specify id format more precisely, but sufficient for parameter 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 'Returns bill-level detail for one or more credit card bills by id' and lists specific fields (financeCharges, payments). It distinguishes from openfinance_list_transactions, which handles itemized 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?
Explicitly says when to use (for bill-level detail) and when not (for transactions). Advises to use openfinance_list_credit_card_bills first to discover ids, and warns not to reconstruct 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_statusARead-onlyIdempotentInspect
Returns the current status of a bank connection (UPDATED, UPDATING, LOGIN_ERROR, etc.), its executionStatus, connector metadata, and a reconnect_url that reopens the widget in UPDATE mode for that connection (re-authenticate / enter MFA token in place, without disconnecting and without consuming a connection slot). Omit item to get the status of ALL linked banks at once (returns { count, items }); pass item for a single bank.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context by explaining the two response formats (single bank vs. list with count and items) and the types of data returned (status, executionStatus, connector metadata). It does not contradict 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 consists of two sentences, both front-loaded with the core purpose and immediately followed by usage variations. Every sentence adds value with no 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 the tool has one optional parameter, no output schema, and rich annotations, the description is largely complete. It covers the return data types and two distinct response patterns. It could optionally mention that the status values are strings (implied by listing them), but the information provided is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only one optional parameter 'item' and 0% schema description coverage, the description compensates well by explaining the effect of omitting vs. passing it, and the resulting response structures. It does not specify the expected format of 'item' (e.g., ID string), but the usage implications are clear.
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 status of a bank connection, listing specific status values (UPDATED, UPDATING, LOGIN_ERROR, etc.), along with executionStatus and connector metadata. It distinguishes between two modes: omitting 'item' for all linked banks and passing 'item' for a single bank, making the purpose highly specific and distinguishable from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains when to omit 'item' (for an overview of all banks) and when to pass 'item' (for a specific bank). However, it does not provide guidance on when not to use this tool or direct comparisons to sibling tools like openfinance_list_connections or openfinance_provider_status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_get_loan_detailARead-onlyIdempotentInspect
Returns full loan contract detail by id (GET /loans/:loanId): interestRates[] (taxType, ratePercentage, indexer), contractedFinanceCharges[], balloonPayments[], warranties[], installments schedule (installmentsCount, paidInstallments, numberOfInstallmentsRemaining, installmentFrequency), amortizationScheduled, CET, ipocCode and dates. Use after openfinance_list_loans to deep-dive on a specific contract. Pass loan_ids as an array (1-50). { results, errors } batch shape.
| Name | Required | Description | Default |
|---|---|---|---|
| loan_ids | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. Description adds batch behavior, response shape with results/errors, and enumerates fields. 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?
Front-loaded with purpose and key fields. Somewhat dense but each sentence contributes. Could be slightly trimmed but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description provides detailed list of returned fields and batch handling. Complete for a read-only detail tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for parameter. Description adds 'Pass loan_ids as an array (1-50)' and implies per-contract detail, but lacks exact format of loan 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?
Clearly states it returns full loan contract detail by ID, listing many specific fields. Distinguishes from sibling openfinance_list_loans which provides summary list.
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 'Use after openfinance_list_loans to deep-dive on a specific contract'. Also specifies batch size (1-50) and response shape.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_accountsARead-onlyIdempotentInspect
Returns accounts for a bank connection: BANK (checking/savings) and CREDIT (credit card) with balance, number, type, subtype, bankData, and creditData. Also returns bank (the brand/connector name like 'Nubank Empresas' — same shown in the dashboard UI) and connector_id. Note: each account's name is the legal entity that issues the account (e.g. 'Nu Pagamentos S.A. - Instituição de Pagamento'), which is not the same as the brand — when referring to the bank in user-facing text, use bank. OMIT item to list accounts across ALL linked banks at once — the response aggregates every connection's accounts into results, each row tagged with its own bank/connector_id/item_id (use this when the user asks for 'my accounts/cards' without naming a bank). Pass item to target a single bank (response carries bank/connector_id/item_id at the root). CREDIT (credit card) balance: its meaning is CONNECTOR-DEPENDENT — some banks report the current open-bill partial, others the full revolving/installment debt — so do NOT treat balance as 'this month's bill'. The open billing cycle is defined by creditData.balanceCloseDate (when it closes) / balanceDueDate (when it's due). For a standardized open-bill amount and total debt that mean the same across connectors, use openfinance_list_credit_card_bills (open_bill + total_pending_debt, derived from PENDING transactions); closed bills come from that same tool's results. 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.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| type | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds significant behavioral context beyond annotations: explains that CREDIT balance is connector-dependent and unreliable for 'this month's bill', describes the provider_incident block that may invalidate data, and clarifies the naming convention (name vs. bank). 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 front-loaded with the main purpose and structured with usage, warnings, and alternatives. However, it is quite long and could be more concise, with some redundant details about the account name.
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?
Compensates well for lack of output schema by enumerating returned fields and important warnings. Missing details like pagination, but for a list tool with well-described return structure, it is fairly 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?
Given 0% schema description coverage, the description compensates by explaining the 'item' parameter's behavior in detail. However, the 'type' parameter (enum BANK/CREDIT) is not explicitly described as a filter, though its values are mentioned. Slightly incomplete but still adds significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns accounts for a bank connection, listing specific fields (balance, number, type, subtype, etc.) and distinguishes between BANK and CREDIT accounts. It directly addresses what the tool does, with a specific verb and resource.
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 omit the 'item' parameter to list all banks vs. passing it to target a single bank, and when to use an alternative tool (openfinance_list_credit_card_bills) for standardized bill amounts. This effectively distinguishes usage from siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_categoriesARead-onlyIdempotentInspect
Returns Pluggy's transaction category taxonomy (GET /categories), cached for the adapter session. Each entry has id (the categoryId used by openfinance_update_transaction_category), description (English), descriptionTranslated (Portuguese — prefer this for pt-BR users), parentId and parentDescription (the tree parent). Single aggregated response — no batch ids.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description reveals caching duration (adapter session) and the aggregated nature of the response. This adds useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences efficiently convey purpose, return structure, and usage context without redundant information. Front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully explains all relevant fields (id, description, descriptionTranslated, parentId, parentDescription) and their role in category updates. No gaps for a no-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema, so the description does not need to add parameter semantics. It appropriately focuses on the return value and 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 it returns the transaction category taxonomy, specifying the endpoint (GET /categories), caching behavior, and relationship to sibling tool 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?
It provides guidance on when to use the tool (e.g., before updating categories) and language preference (descriptionTranslated for pt-BR users). However, no explicit exclusions or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_connectionsARead-onlyIdempotentInspect
Returns the saved bank connections for this install: connector_id, item_id, bank name, a per-connection reconnect_url, and an add_connection_url to link additional banks via the Open Finance widget. The reconnect_url reopens the widget in UPDATE mode for that EXISTING connection (user re-enters credentials / MFA token and the data refreshes in place) — use it when a connection needs re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data). It does NOT consume a connection slot and does NOT require disconnecting first.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, providing safety profile. The description adds value by detailing return fields, but does not disclose additional behavioral traits beyond what annotations cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff, directly states purpose and key return fields. Efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, clear annotations, and no output schema, the description fully covers the tool's behavior. It tells the agent exactly what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is 100%. The description does not need to add parameter info. Baseline 4 is appropriate as there is nothing 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 clearly states the tool returns saved bank connections and lists specific fields (connector_id, item_id, bank name, add_connection_url). It distinguishes itself from sibling tools like openfinance_list_accounts which list accounts within 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 usage for retrieving existing connections and getting a URL to add new ones, but does not explicitly state when to use versus alternatives like connect or marketplace. Guidance is implied but not explicit.
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_billsARead-onlyIdempotentInspect
Returns CLOSED credit card bills for a CREDIT-type account: dueDate, totalAmount, minimumPaymentAmount, allowsInstallments, plus payments[] (id, paymentDate, amount, valueType, paymentMode), payments_count, payments_total, finance charges aggregates, and a derived payment_status per bill. IMPORTANT — Brazilian Open Finance semantics: Pluggy does NOT return a paid/status field. The payment goes into the payments[] of the bill whose CYCLE contains the paymentDate (closing ≈ dueDate − 7d): pre-payment before close stays on the bill being paid; payment between close and due, or after due, lands on the NEXT bill. So payments[] on a bill commonly carries the previous bill's payment, NOT the current one's — do NOT assume this bill was paid just because payments[] is non-empty. Use the derived payment_status (PAID | OPEN | PAST_DUE_UNCONFIRMED | PAST_DUE_UNPAID): a bill is PAID when its OWN payments[] (early pre-payment) or ANY newer bill in the payload contains a payment with amount ≈ this bill's totalAmount (±R$0.50). The MOST RECENT bill that's past-due, with no own pre-payment match, cannot be confirmed via cross-bill (the next cycle hasn't closed yet) — it returns PAST_DUE_UNCONFIRMED. NEVER call such a bill 'vencida' categorically; flag that the payment may have been made between close and due and not yet reflected upstream. The full payment_status_legend is returned alongside the results. OPEN BILL & TOTAL DEBT (standardized, derived — OPT-IN): pass include_open_bill:true to ALSO get open_bill (the current not-yet-closed bill, próxima a vencer) and total_pending_debt (saldo devedor total = all pending installments), BOTH derived from PENDING transactions so they mean the same thing across connectors — use these instead of the CREDIT account's balance, whose meaning VARIES by connector (some report the open-bill partial, others the full installment debt). open_bill = { available, method (cycle_dates = real close/due dates | calendar_month_fallback = estimated, confidence:'low'), close_date, due_date, total_amount (net charges − credits), transaction_count }; plus a future_bills[] breakdown per month — LOW-confidence forward projections of PENDING installments (confidence:'low', basis), NOT authoritative bills (for closed months trust the results totalAmount). CONNECTOR ASYMMETRY: where the bank does NOT expose the open bill before closing (only closed bills, no reliable cycle dates), open_bill.available is false with a reason (connector_exposes_no_pending or open_bill_not_published) — that bill isn't retrievable by any endpoint until it closes (upstream limit of the institution's Open Finance feed, not our filter); check the bank app for the current open bill. When per-transaction billId grouping does not reconcile with the bills' totals, a bill_grouping_reliability warning is attached (trust totalAmount, do not sum by billId). Default false (the projection runs an extra accounts+transactions scan, so it's opt-in). The response opens with an account echo block ({ account_id, bank, name, number, type, item_id }) identifying WHICH card/bank these bills belong to. When more than one bank is connected, ALWAYS cross-check the echo against the card you intended to query and name the bank when presenting results — never attribute one bank's bills to another. This tool's results are bill-level summaries — NOT individual transactions, and each bill's totalAmount (from the bank) is the AUTHORITATIVE amount. To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id — but note creditCardMetadata.billId is a per-connector hint that can be sparse/inconsistent (e.g. Nubank), so do NOT reconstruct a bill total by summing transactions by billId. Returns a warning instead of failing if the CREDIT_CARDS product is not enabled.
Bulk support: accepts account_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| account_id | Yes | ||
| account_ids | No | ||
| include_open_bill | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description greatly exceeds these by detailing derived fields (payment_status), payment logic, connector-specific behavior, and warnings about bill_grouping_reliability. 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 extremely long and unstructured, consisting of a single dense paragraph. It lacks headings, bullet points, or clear separation of concepts, making it hard for an AI agent to parse quickly. While each sentence adds value, the overall format is verbose and not front-loaded with the most critical 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 complexity of Brazilian Open Finance semantics, the description covers all necessary context: payment status derivation, open bill projection, connector asymmetry, cross-bank identification, and warnings. Without an output schema, it thoroughly describes return fields (payments[], payment_status, open_bill, etc.) and edge cases, making it complete for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It thoroughly explains include_open_bill (return structure, when available, confidence levels), account_ids (bulk support), and the account echo block. However, page and page_size pagination parameters are not described, and the documentation could be more explicit about account_id's role beyond being required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it returns CLOSED credit card bills for a CREDIT-type account, and distinguishes from sibling tools like openfinance_list_transactions by clarifying that this tool provides bill-level summaries, not individual transactions. It also highlights that for itemized purchases, one should use openfinance_list_transactions, and mentions the singular openfinance_get_credit_card_bill is a different tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive guidance on when to use this tool vs alternatives, including explicit warnings about payment semantics (payments landing on next bill), connector asymmetry for open bills, and cross-bank identification. It also explains the opt-in nature of include_open_bill and advises against summing transactions by billId, making the usage context very clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_investmentsARead-onlyIdempotentInspect
Returns the investment portfolio for a connection (broker or bank with INVESTMENTS product enabled): FIIs, stocks, ETFs, fixed income (CDB/LCI/LCA/Tesouro), mutual funds, retirement (previdência) and COE. Each row carries balance, amount, amountOriginal, amountProfit, lastMonthRate / annualRate / lastTwelveMonthsRate (when available), dueDate, issuer, ISIN, etc. Returns { total:0, results:[], warning } instead of throwing when INVESTMENTS isn't enabled (403) or other upstream errors.
| Name | Required | Description | Default |
|---|---|---|---|
| item | No | ||
| page | No | ||
| type | No | ||
| page_size | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate a safe, read-only operation. The description adds useful behavioral details: it returns a fallback object {total:0, results:[], warning} instead of throwing errors on 403 or other upstream issues. This goes beyond what annotations provide. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently lists return types and fields. It is front-loaded with the main purpose. However, it includes a dense enumeration that could be more structured for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite listing return fields and types, the description fails to explain parameter semantics (pagination, filtering) and does not mention output structure details beyond the fallback. Given the absence of an output schema, the description should provide more context on usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% with no parameter descriptions in the schema. The tool description does not mention any of the four parameters (item, page, type, page_size) or their meaning. Since it doesn't compensate for the low coverage, the score is minimal.
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 investment portfolios for a connection, listing specific types (FIIs, stocks, ETFs, etc.) and fields. This distinguishes it from sibling tools that deal with accounts, transactions, or other financial 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?
The description specifies the tool is for connections with INVESTMENTS product enabled, and explains behavior when the product isn't enabled (returns a fallback object). However, it does not explicitly state when not to use this tool or compare it to similar siblings like openfinance_list_investment_transactions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_investment_transactionsARead-onlyIdempotentInspect
Returns the movement history for a specific investment position: BUY / SELL / TAX / INTEREST / AMORTIZATION / TRANSFER. Each row carries quantity, value, amount, netAmount, agreedRate (treasury), brokerageNumber, and itemized expenses (brokerageFee, incomeTax, settlementFee, custodyFee, stockExchangeFee, etc.). Use after openfinance_list_investments to get the investment_id.
Bulk support: accepts investment_ids for batched execution.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| investment_id | Yes | ||
| investment_ids | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so description adds value by detailing the types of transactions returned and the fields included. It does not cover pagination behavior, but the core safety traits are well documented.
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 clear paragraphs with front-loaded purpose and structured details. Every sentence adds information, and the bulk support note is separate. 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 output schema and with schema lacking parameter descriptions, the description explains the return content well but omits pagination details. Moderate completeness for a list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description must explain parameters. It mentions investment_id and investment_ids but does not describe page or page_size, leaving their purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resources ('Returns the movement history for a specific investment position') and lists transaction types (BUY/SELL/TAX etc.), clearly distinguishing from sibling tools like openfinance_list_investments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use after openfinance_list_investments to get investment_id, and mentions bulk support. However, it does not specify when not to use this tool or list alternative tools for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_loansARead-onlyIdempotentInspect
Lists loan contracts per bank connection (GET /loans). Pass items as an array of connection selectors (item_id uuid, connector_id, or connector_name) — one entry per connection to fetch; multiple connections are queried sequentially with rate-limit spacing. OMIT items to list loans across ALL linked banks. Returns { results, errors } per connection.
| Name | Required | Description | Default |
|---|---|---|---|
| items | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent), the description reveals sequential querying with rate-limit spacing and the return structure { results, errors } per connection, adding valuable behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences front-load the purpose, then detail parameter usage and behavior, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking output schema, the description covers purpose, parameter semantics, behavioral details, and return structure, making it complete for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains that items are connection selectors (item_id, connector_id, or connector_name) and that omitting them lists all loans. This adds crucial meaning beyond the schema's bare type array of strings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists loan contracts per bank connection, specifying the HTTP method (GET /loans). It distinguishes from sibling list tools by focusing on loans and explaining the items parameter usage.
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 items (for specific connections) and when to omit it (for all linked banks), but does not explicitly compare to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_list_transactionsARead-onlyIdempotentInspect
Returns transactions for a bank account (BANK or CREDIT type). For CREDIT (credit card) accounts, this is the ONLY way to get itemized transactions (purchases, subscriptions, etc.). Each credit card transaction MAY carry creditCardMetadata.billId pointing at a bill from openfinance_list_credit_card_bills, but this is a per-connector HINT, not authoritative: some connectors (e.g. Nubank) populate it sparsely (many transactions and installments arrive with no billId) or inconsistently (the same payment tagged to more than one bill). Do NOT reconstruct a bill's total by summing transactions by billId — the bill's own totalAmount from openfinance_list_credit_card_bills is the source of truth. CREDIT PENDING vs POSTED varies by connector: where the bank exposes future-dated status:'PENDING' installments, those represent the OPEN bill plus future bills (future months); where it does NOT, only the last closed bill's POSTED items appear until ~closing. Same query, different coverage per bank (upstream). To get a standardized open-bill total / total debt regardless, use openfinance_list_credit_card_bills (open_bill / total_pending_debt). 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 page (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). Pass an explicit page (with page_size, max 500) only if you want to walk pages manually instead. 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 |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnly and idempotent. Description adds extensive behavioral details: auto-pagination up to 5000, truncation, error response format, detail levels, credit card metadata quirks, per-connector variation, and provider incident block. 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 verbose but every sentence adds value. It is well-organized into logical blocks (general, credit card, filtering, pagination, detail levels, errors, account echo, bulk). Could be slightly more concise, but it earns its length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 params, multiple account types, credit card nuances, pagination, error handling, provider incidents), the description covers all essential aspects. No output schema, but it explains return structure including account echo, warning/error, truncated flag, and provider incident block.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description fully compensates: explains each parameter (to, from, page, page_size, detail, account_id, account_ids, search_queries) with format, allowed values, and semantics. For example, dates as ISO YYYY-MM-DD, detail enum meanings, search as case-insensitive substring match.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns transactions for bank/credit accounts. It distinguishes from sibling openfinance_list_credit_card_bills by emphasizing that for CREDIT accounts, this is the only way to get itemized transactions, and explicitly contrasts with the bill total 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 when-to-use guidance: for credit card itemized transactions use this; for standardized bill totals use openfinance_list_credit_card_bills. Also explains pagination options, when to narrow date range if truncated, and when to use explicit page vs auto-pagination.
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_itemARead-onlyIdempotentInspect
Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call. Resolves the connection's accounts internally and fans out their transactions, so you do NOT need to call openfinance_list_accounts first nor carry account_id uuids between calls. Pass item (connector_id, connector_name or item_id) to target one bank, or OMIT it to analyze ALL linked banks at once. from/to are ISO dates (YYYY-MM-DD). Default granularity:'monthly' returns a COMPACT summary (no raw rows): total entradas, saídas, saldo_liquido, monthly evolution (por_mes), and top_despesas/top_recebimentos (largest N each), plus a per-account breakdown (by_account). Use this for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'. Set granularity:'raw' to ALSO get every consolidated transaction (heavier — only when itemized rows are needed); combine with detail:'rich' to enrich those rows with merchantInfo (cnpj/cnae/businessName/category) + extra creditCardMetadata (billId, purchaseDate, fees), or detail:'raw' for the full untouched Pluggy object per row, when the connector provides them. type filters BANK or CREDIT accounts. On a connection with many transactions the scan caps at 5000/account and flags truncated:true. May include a provider_incident block when the Open Finance provider has an OPEN incident affecting a connected bank: the totals/rows may be incomplete or wrong until the provider recovers, and reconnecting does not fix it.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| item | No | ||
| type | No | ||
| top_n | No | ||
| detail | No | ||
| granularity | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details important behaviors: capping at 5000 transactions per account with a truncated flag, possible provider_incident block affecting data accuracy, and the effect of granularity and detail parameters. All annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and the description adds contextual value beyond 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 relatively long but well-structured with front-loaded purpose and systematic parameter explanations. Every sentence contributes useful information; a minor reduction in redundancy could improve conciseness.
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 (7 parameters, no output schema), the description is remarkably complete. It covers input parameters, return types (compact vs raw), edge cases (truncated, provider incident), and filtering options (type, granularity, detail). No missing crucial context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains most parameters: item, from/to, granularity, detail, type. However, top_n is not explicitly described, only hinted as 'largest N'. This is a minor gap. Overall, description adds good 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 it provides consolidated cash-flow analysis for a whole bank connection in one call, resolving accounts internally. It explicitly distinguishes from sibling tools like openfinance_list_accounts and openfinance_list_transactions by eliminating the need for prior account listing. Specific use cases (e.g., 'fluxo de caixa') are listed.
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 (consolidated analysis) and when not to use other tools (e.g., no need to call openfinance_list_accounts first). It describes how to use parameters like item (omit for all banks), from/to, granularity, and detail, and gives clear usage scenarios for monthly vs raw granularity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_provider_statusARead-onlyIdempotentInspect
Checks the LIVE operational status of the Open Finance provider (its public status page) — this is the PROVIDER's health, separate from your own connection's openfinance_get_item_status. Use it whenever data looks incomplete or stale even though a connection shows UPDATED (accounts/transactions/balances missing, a bank not returning everything): it reveals an upstream outage or a known incident on a specific bank/connector, so you can tell a provider-side problem apart from a connection that just needs reconnecting. Returns the global indicator (none/minor/major/critical), degraded components, open incidents, and — when you have banks connected — flags the incidents that affect YOUR connected banks in your_banks_affected.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral context: returns global indicator, degraded components, open incidents, and flags incidents affecting connected banks. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three well-structured sentences front-loaded with key purpose and usage. Could be slightly more concise but 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?
With zero parameters and no output schema, the description fully covers behavior, return values, and use cases. Annotations provide safety profile. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100%. Description doesn't need to add parameter info. Baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks the LIVE operational status of the Open Finance provider's public status page, distinguishing it from the sibling tool openfinance_get_item_status which checks 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?
Explicitly tells when to use: when data is incomplete/stale despite connection showing UPDATED, and distinguishes from openfinance_get_item_status, providing clear alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_search_bank_connectorsARead-onlyIdempotentInspect
Searches the available bank connectors by name (pass keywords[], e.g. ['nubank','btg']) and returns, per match: the connector id, whether it's Open Finance or API (access), PF/PJ (audience), the user's already-linked connections (and accounts when include_accounts=true), and a ready connect_url with the bank pre-selected. Some non-Open-Finance credential connectors carry a caveat warning that they don't auto-update (needs periodic manual reconnection) — surface it so the user can prefer the institution's Open Finance connector for automation. Honors the user's plan (a PF plan hides PJ banks; a PJ plan covers BOTH — PF and PJ banks connect and count under the same plan). Call this BEFORE connecting to hand the user a one-click link to the right bank. keywords[] is REQUIRED — without it returns a hint (never dumps the whole catalog).
| Name | Required | Description | Default |
|---|---|---|---|
| keywords | No | ||
| include_accounts | No |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds details about return fields, caveat warnings, and plan-based filtering, which improves transparency 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?
Six sentences, no wasted words. The description is front-loaded with the main action and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description fully explains return fields (connector id, access, audience, linked connections, connect_url) and caveats. It also covers plan filtering and usage context, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains keywords[] with an example and notes it's required, and explains include_accounts to include accounts. It does not specify types or defaults, but adds significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states it 'Searches the available bank connectors by name' with specific return fields. It distinguishes from sibling tools by framing it as a prerequisite before connecting.
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 says 'Call this BEFORE connecting to hand the user a one-click link to the right bank' and states that keywords[] is required (without it returns a hint). It doesn't explicitly list when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openfinance_update_transaction_categoryAInspect
Corrects the category of one or more transactions (PATCH /transactions/:id). Pass items as an array of { transaction_id, category_id } — transaction_id comes from openfinance_list_transactions, category_id from openfinance_list_categories. This overrides Pluggy's automatic categorization AND teaches Pluggy: recategorizing a transaction automatically creates a Category Rule for this client (case-insensitive exact match on the transaction's data), so FUTURE similar transactions are categorized the same way — use this to fix miscategorized transactions and improve categorization accuracy going forward. Batch shape: returns { updated, results: [{ transaction_id, category, categoryId }], errors: [{ id, status, message }] } — per-item errors do not fail the whole batch.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses side effect of creating a Category Rule (case-insensitive exact match), overrides automatic categorization, and explains per-item error tolerance. Annotations only cover readOnly/hints; description adds critical behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is dense but efficient, with clear front-loading (verb+method+input). Each sentence adds unique value (side effects, return shape, error handling). Slightly verbose but justified by complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple input schema and no output schema, the description fully documents input semantics, side effects, and return shape. Sufficient for an agent to correctly invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description thoroughly explains the items array structure, required fields (transaction_id, category_id), and sources for these IDs from sibling tools, adding full meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it corrects transaction categories via PATCH, specifying input format and referencing sibling tools for ID sources. Definitively distinguishes from other tools like openfinance_list_transactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use (to fix miscategorized transactions), how it teaches Pluggy for future categorization, and batch error handling. Provides clear context for selecting this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
report_bugAIdempotentInspect
Report a bug, missing feature, or send feedback. Include the conversation array with recent messages for reproduction.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | ||
| message | Yes | ||
| conversation | No | [] |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent hint and non-destructive nature; description adds context about including conversation for reproduction but lacks details on side effects, authentication needs, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded with purpose, but lacks structure like bullet points or sections for parameters.
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 three parameters and no output schema, the description omits response behavior, error cases, and prerequisites, making it incomplete for a mutation-like 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?
Description mentions the conversation parameter for reproduction, giving some meaning beyond the schema, but does not explain 'context' or 'message' parameters. With 0% schema coverage, partial value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports bugs, missing features, or sends feedback, distinguishing it from sibling tools which are all finance-related operations.
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 provides guidance to include the conversation array for reproduction, but does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
show_versionARead-onlyIdempotentInspect
Show the current MCP platform and adapter versions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by specifying exactly what versions are shown (MCP platform and adapter). This fully covers the tool's behavior without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every part contributes to understanding the tool's 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?
For a zero-parameter, read-only tool with strong annotations, the description is complete. It clearly states what version information is returned, requiring no further elaboration.
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 100% schema description coverage. The description naturally does not need to add parameter semantics, and the baseline for zero parameters is 4, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'show' and clearly identifies the resource as 'current MCP platform and adapter versions'. It uniquely distinguishes this tool from all siblings, none of which deal with version information.
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 does not provide explicit when-to-use or when-not-to-use guidance. However, given the tool's simplicity (no parameters, read-only), its purpose self-explains usage context. A score of 3 acknowledges the lack of direct guidelines but recognizes that implied usage is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
toolkit_infoARead-onlyIdempotentInspect
Returns the current toolkit state: installed MCPs, their connection status, and how many catalog tools each exposes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's safe and idempotent. The description adds valuable context on what specific data is returned (installed MCPs, connection status, catalog tool counts), which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, concise, and front-loaded with the verb 'Returns'. Every word provides necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns (installed MCPs, connection status, catalog tools count) without an output schema. This is sufficient for a simple informational tool with no parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4 per guidelines. The description does not need to add parameter info since there are none.
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 states the resource: 'current toolkit state: installed MCPs, their connection status, and how many catalog tools each exposes.' This distinguishes it from sibling tools which are action-oriented (e.g., authenticate, connect).
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 guidance on when to use this tool versus alternatives, but the purpose is self-evident as a read-only state inspection tool. The sibling tools are all actions (connect, authenticate, etc.), so context implies this is for informational queries only.
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.
Discussions
No comments yet. Be the first to start the discussion!