Uber Conta by Digio MCP

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the workflow: it returns a login link when called with no args and accepts a JWT for session login. It also notes that a config-based header is preferred for permanent access. This goes beyond the annotations (idempotentHint=true, readOnlyHint=false) without contradicting them, though it does not detail side effects or session expiration.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but well-structured, with the main flow explained in a few sentences. It front-loads the audience and purpose, then explains the two modes. No unnecessary fluff, though it could be tightened slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description covers the essential behaviors: how to trigger the login link and how to pass the token. It does not explicitly describe the response when a token is provided, but the context is mostly complete for agent 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 provides a bare 'token' property with no description, but the description fully explains its meaning: a JWT to paste for session-only login. It also clarifies that omitting the token returns the login link, adding crucial semantic context that the schema lacks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: authenticate an IDE agent to the MCP.AI server. It explains the two authentication modes (permanent via config header, session-only via token) and distinguishes from simply connecting. The verb 'authenticate' is specific and the resource is implied.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given on when to use the tool: for a permanent connection, the user should add the token to the server config instead of using the tool; for a session-only login, call with the token or with no args to get the browser link. This provides clear 'when to use' and 'when not to use' context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing a safe read operation. The description adds valuable behavioral detail about the response shape in different states, including the authenticated flag and pending array, 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?

The description is two sentences, front-loads the core purpose, and includes only meaningful conditional details. No wasted words or redundant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-input status tool, the description fully covers the two relevant states and the returned URLs. No output schema exists, so the conditional return-value descriptions are 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?

The tool has zero parameters, so the schema provides complete coverage. The baseline for zero parameter tools is 4; the description appropriately focuses on output behavior rather than parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns connection status and URLs, with a specific verb ('Returns') and resource ('connection status'). It also distinguishes the tool by explaining both success and missing-credential cases, setting it apart from sibling tools like provider_status or authenticate.

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 contextual triggers: when all providers are connected, and when credentials are missing. It implies this tool is used to check overall connection status or obtain connect URLs, though it does not explicitly name alternative tools or state 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the sparse annotations. It discloses that invoke works even for uninstalled MCPs, returns connect/checkout links for auth/payment, and that writes require workspace owner/admin. It also explains the one-off install behind invoke and the behavior of search/describe regarding installed status.

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 long, dense paragraph that packs substantial information, but lacks structural breaks or lists. It is front-loaded with the main purpose, yet the run-on format makes it harder to scan. Every sentence contributes, but the structure could be improved with bullets or sections.

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 and high complexity, the description covers the main flows, authorization requirements, edge cases (connect/checkout links), and the prompt library. It does not thoroughly describe return formats for all actions, but the core behavior is well covered for a tool of this scale.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description must compensate for parameter understanding. It explains the roles of key parameters like action, mcp_id, tool_id, and arguments through the action flow, but many parameters (e.g., immediate, tier_slug, prompt_vars, prompt_targets, cancel_reason) remain undocumented in both schema and 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 identifies the tool as the official mcp.ai marketplace, a catalog and execution engine for MCPs, and outlines the core search/describe/invoke flow. It distinguishes this from sibling tools by naming the prompt library and explicit workflow, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance is given: prefer invoke for one-off use, use install for permanent toolkit additions, and list_tools shows what is callable now. It also clarifies when to use subscribe/cancel, report_bug, and request_mcp, providing clear decision-making criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the destructiveHint annotation, the description discloses that connection data is deleted and bank data becomes unavailable. It also mentions the return of an add_connection_url, adding useful behavioral context without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences: the action, the consequence, and the return value. 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?

For a simple one-parameter destructive tool, the description covers the main behavior, impact, and return value. It lacks parameter clarification and error/edge-case details, but given the tool's simplicity and annotations, it is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required parameter 'item' with no description (0% coverage). The description fails to explain that 'item' likely identifies the bank or connection, leaving the agent to infer this. It does not compensate for the missing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: revoke Open Finance consent and delete connection data. This is a specific verb+resource combination that distinguishes it from sibling tools like 'connect' and listing functions.

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 the tool is used when a bank needs to be disconnected and notes the reconnection URL. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it for disconnecting a bank.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses polling behavior up to ~60s, the return shape ({results, errors}), the meaning of status fields (synced, needs_action, timed_out), and the reconnect_url flow. It adds significant context beyond the sparse annotations (readOnlyHint=false, etc.), including that re-authentication needs user interaction. No contradiction with annotations; it clarifies the non-destructive nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence adds value: it states the core action first, then use case, parameter syntax, return semantics, and error handling. There is no redundancy; it is front-loaded with the most critical information and structured logically. Despite length, it is the minimal complete explanation for such a complex tool.

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 carries all the burden and succeeds: it covers purpose, use cases, parameters, return values, edge cases (needs_action, timed_out), and follow-up actions. It is complete enough for an agent to select and invoke the tool correctly, including knowing when to use wait:false and how to 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?

Schema coverage is 0%, but the description fully explains both parameters: items as an array of selectors with concrete examples (item_id, connector_id, connector_name, custom_label), and wait as a boolean with behavioral implications. It also explains omission of items means all linked banks, providing more than the schema could.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise action: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish'. It specifies the resource (connections), the operation (re-sync), and differentiates from siblings by mentioning 'WITHOUT disconnecting/reconnecting' and referencing openfinance_get_item_status for timeout. This clearly distinguishes it from other finance tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance: 'Use this when a balance or transaction list looks stale' and contrasts with disconnecting/reconnecting. It also explains when to set wait:false for fire-and-forget and when to re-check with openfinance_get_item_status. It says OMIT items to sync ALL linked banks, providing clear selection rules.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses significant behavioral nuances: CREDIT accounts may return BALANCE_FETCH_ERROR and instead include a structured warning; upstream 5xx or non-Open Finance connectors cause a degradation to last-synced balance with `realtime: false`, `updatedAt`, and `warning`. It also defines the response shape, clarifying error handling without throwing exceptions. This adds substantial transparency beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each with a distinct purpose: first states the core function, second covers error/degradation behavior, third gives the response envelope. No filler or redundancy, and it is front-loaded with the main purpose. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description explains the response shape (`{ results: [...], errors: [{ id, status, message }] }`) and the two edge-case behaviors (credit errors and degradation), which is good for a tool without an output schema. However, it does not describe the inner structure of each result item (e.g., balance amount, currency, updatedAt fields), leaving some ambiguity about the 'balance payload' contents. Overall, it is fairly complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining that `account_ids` must be an array of 1–50 items, and the purpose is per account id. It doesn't detail the format or origin of the IDs, but the range limit and the phrase 'per account id' provide meaningful semantics beyond the raw schema (which only says 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 'Returns real-time balance payload per account id', specifying both the verb and the resource. It also includes the API endpoint (GET /accounts/:id/balance), which explicitly matches the tool name and differentiates it from sibling tools like openfinance_list_accounts (which lists accounts) or openfinance_get_accounts_detail (which gets details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on what the tool does, particularly the input parameter `account_ids` and its 1–50 array constraint. However, it does not explicitly mention when to use this tool over alternatives such as openfinance_get_accounts_detail or openfinance_list_accounts, nor does it state when not to use it. The intent is inferable from the name and description, but explicit exclusion is absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/destructive hints, lowering the bar. The description adds valuable behavioral context: the {results, errors} batch envelope and the provider_incident block with warnings about unreliable limit/balance data. This is beyond what annotations convey and is crucial for safe interpretation of results.

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 tight and well-structured: first sentence states the core function, second covers the parameter, third explains the response envelope, and fourth delivers an important caveat. Every sentence earns its place without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description covers the return shape, the parameter constraint, and a critical provider-incident edge case. It is complete enough for a single-parameter read-only batch tool, with no major gaps in operational understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates for the single parameter. It explains account_ids as an array of IDs, explicitly stating the 1–50 limit, and ties it to the batch operation. This gives the agent complete semantic understanding despite the sparse schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns full account objects with extended creditData, per ID via GET /accounts/:id. This specific verb+resource distinguishes it from siblings like list_accounts or get_account_balance, which target summaries or individual data points.

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 context: fetch full details for a batch of account IDs (1–50). It does not explicitly mention alternatives or exclusions, but the intent is clear versus list-only or balance-only tools. It could be stronger with a direct comparison, but the batch pattern and data scope imply typical use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds significant behavioral context beyond annotations: Pluggy does not return a paid/status field, payments[] reflect previous bill payments, and creditCardMetadata.billId is sparse/inconsistent. These are critical non-obvious behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries essential information: purpose, return fields, exclusions, alternatives, caveats, and usage instructions. It is well-structured, front-loaded with the primary purpose, then detailed nuances.

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 having no output schema, the description covers return fields, batch shape, limitations (no paid status), and payment semantics. It is fully sufficient for an agent to understand the tool's behavior and integrate it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

While the schema only has one parameter with no description, the description explains bill_ids is an array and instructs to discover ids via openfinance_list_credit_card_bills first. It also clarifies the batch shape, adding 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?

The description clearly states it returns bill-level detail for credit card bills by id, listing specific fields (financeCharges, payments[]). It also explicitly distinguishes itself 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?

Provides explicit when-to-use and when-not-to-use guidance. It says to use openfinance_list_transactions for itemized transactions, to discover ids via openfinance_list_credit_card_bills, and to prefer that tool for paid status checks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and the description adds substantial non-obvious behavior: reconnect_url reopens the widget in UPDATE mode without disconnecting or consuming a connection slot, and omitted `item` returns a `{ count, items }` envelope. This goes well beyond what annotations convey.

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 appropriately concise: two dense sentences with front-loaded purpose, plus a short bulk-support note. Every sentence adds information and there is no filler or repetition of schema/annotations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and zero parameter descriptions, the description does a good job of covering return values, single vs. all behavior, bulk semantics, and the reconnect_url implication. It loses a point for not addressing `item_id` and for lacking explicit when-not-to-use guidance.

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 `item` and `item_ids` well, but the `item_id` parameter is never mentioned, leaving one of three parameters ambiguous. This is a real gap in an otherwise helpful 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 states a specific verb and resource: 'Returns the current status of a bank connection' and lists concrete return contents (status, executionStatus, connector metadata, reconnect_url). This unambiguously distinguishes it from sibling tools like openfinance_list_connections by emphasizing the reconnect_url and update-mode behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear usage context: omitting `item` retrieves all banks, passing `item` retrieves one, and `item_ids` is available for batch execution. It does not explicitly name alternatives or exclusions, but the guidance is sufficient and practical.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context by listing the specific return fields and the batch result/errors structure. It does not mention side effects or permissions, but none are relevant for a read-only GET endpoint. The added detail goes beyond annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core action and endpoint, then lists specific return fields in a compact, well-structured format. Each sentence serves a purpose: what it does, what fields to expect, when to use it, and how to pass parameters. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description thoroughly enumerates the response fields (interestRates, contractedFinanceCharges, balloonPayments, etc.), covers the parameter constraint, and provides usage guidance. It also discloses the batch response shape. For a read-only detail endpoint, this is highly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only defines loan_ids as an array of strings. The description adds essential meaning: 'Pass `loan_ids` as an array (1-50)' – specifying the array length constraint and invocation pattern. It also clarifies this is a batch operation. This directly compensates for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Returns full loan contract detail by id (GET /loans/:loanId)'. It clearly distinguishes from siblings like openfinance_list_loans by positioning itself as a follow-up deep-dive tool. The scope and output are well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use after openfinance_list_loans to deep-dive on a specific contract.' This gives a clear sequential context and differentiates from the list tool. It also notes the batch shape (`{ results, errors }`), which is important for correct invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (read-only, idempotent), the description reveals critical behavioral traits: connector-dependent credit balance meaning, provider_incident unreliability, identity_notice deduplication requirements, and bulk execution support. This goes far beyond what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, then adds essential nuances in a structured, dense manner. Every sentence carries significant meaning—from field semantics to incident caveats—with no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description sufficiently explains return structure (e.g., `results` array, root-level fields when `item` is passed) and covers edge cases like provider incidents and identity notices. It also cross-references a sibling tool for bill data, making it contextually complete for safe 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 0% schema coverage, the description compensates by explaining the role of `item` (target a single bank) and `item_ids` (bulk execution), and the enum for `type` is implicitly clear. However, the distinction between `item` and `item_id` is not explicitly addressed, leaving a minor gap for an otherwise thorough 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 it returns accounts for a bank connection, enumerating the account types (BANK and CREDIT) and the included fields. It distinguishes itself from the sibling tool openfinance_list_credit_card_bills by explicitly referencing it for bill data, making the tool's purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: omit `item` for all linked banks, pass `item` for a single bank, and use openfinance_list_credit_card_bills for standardized bill amounts. It also warns against misinterpreting credit balance, providing clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful behavioral context beyond the annotations: it discloses that results are 'cached for the adapter session' and that it returns a 'single aggregated response — no batch ids'. These are operational details that the readOnlyHint/idempotentHint annotations do not cover, enriching the agent's understanding of performance and response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and each clause earns its place. It efficiently describes the return fields, caching behavior, and relationship to another tool without any fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully covers the return structure (id, description, descriptionTranslated, parentId, parentDescription), the aggregated nature, and caching. It also notes the intended usage for transaction categorization, making the description complete for a low-complexity, zero-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?

The tool has zero parameters, so schema coverage is trivially 100%. The description does not add parameter-specific semantics because there are none to describe. It does clarify output field semantics (e.g., descriptionTranslated for pt-BR), but since this dimension focuses on input parameters, the baseline of 4 for zero-parameter tools 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 'Returns Pluggy's transaction category taxonomy' with a specific verb and resource, distinguishing it from sibling tools that deal with transactions, accounts, or balances. It also references the specific API endpoint (GET /categories), leaving no ambiguity about the tool's function.

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 this tool by mentioning that the returned `id` is used by `openfinance_update_transaction_category`, giving a concrete use case. However, it does not explicitly state when to prefer this tool over alternatives or provide exclusions, but the context of category taxonomy for updating transactions is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/destructive hints, but the description adds substantial behavioral detail: the reconnect_url opens a widget in UPDATE mode, requires re-entering credentials/MFA, and refreshes in place. It also clarifies the add_connection_url purpose and the no-slot/no-disconnect 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?

Two sentences, front-loaded with the main purpose, and every clause adds value—listing fields, explaining URL semantics, and stating constraints. No filler.

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 tool with no output schema, the description covers the main return fields and semantics of both URLs. It could add example output structure or error states, but it's largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters (input schema is empty), and the baseline for 0 params is 4. The description doesn't need to explain parameters; it focuses on return values, 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?

Description states 'Returns the saved bank connections for this install' with a specific verb and resource. It lists the returned fields including unique URLs, distinguishing it from sibling list tools like openfinance_list_accounts or openfinance_list_transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the reconnect_url's use case ('use it when a connection needs re-authentication') and clarifies that it doesn't consume a slot or require disconnecting. While it doesn't name alternative tools, it provides clear context for when this tool's outputs are needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

This goes far beyond the readOnlyHint annotation by disclosing that Pluggy does not return a paid/status field, explaining how payments land in the bill whose cycle contains the paymentDate, and describing the derived payment_status semantics. It also surfaces connector asymmetry, open_bill fallback confidence, bill_grouping_reliability warnings, and warning-instead-of-failure behavior—none of which are visible in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long, but every section addresses a specific misuse risk—payment cycle semantics, open-bill fallback, connector asymmetry, authoritative totals, and sibling-tool guidance. It is front-loaded with the core return fields and uses uppercase labels to organize critical caveats without wasted filler.

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 bill semantics and the absence of an output schema, the description provides an unusually complete picture: return structure, derived fields, edge cases like PAST_DUE_UNCONFIRMED, upstream connector limitations, and explicit instructions on how to avoid cross-bank attribution errors.

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 (opt-in, default false, derived semantics) and account_ids bulk support. However, the pagination parameters page and page_size are not described at all, leaving a gap for a listing endpoint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Returns CLOSED credit card bills for a CREDIT-type account' and enumerates specific fields, making the tool's verb, resource, and scope immediately clear. It also distinguishes this listing tool from transaction-level tools like openfinance_list_transactions and from the singular get_credit_card_bill sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance, including 'To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id' and advises using the derived open_bill instead of the account balance because balance meaning 'VARIES by connector.' It also explains when a bill is not retrievable and tells the agent to check the bank app, covering exclusions and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare read-only/idempotent/non-destructive. The description adds significant behavioral detail: it returns a { total:0, results:[], warning } envelope instead of throwing on 403 or upstream errors, and it performs a data-integrity cross-check that flags contradictory zeroed positions with integrity:'suspect_zeroed' and instructs agents to treat them as unavailable rather than R$0. This greatly exceeds the annotation baseline.

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 purpose and includes well-delimited sections for return behavior, data integrity, and bulk support. The data-integrity paragraph is long but necessary for a non-obvious failure mode; overall it is structured efficiently, though it could be tightened slightly without losing meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema, the description covers the return envelope, the per-row fields (balance, amount, dueDate, issuer, ISIN, etc.), error handling, a complex integrity warning, and bulk invocation. It is arguably complete for the tool's complexity and gives an agent all needed operational context except parameter-level semantics (captured 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?

Schema coverage is 0% and the description only clarifies item_ids (bulk support). Params such as page, page_size, type, item, and item_id remain undocumented in both schema and description, leaving agents to guess their semantics. Schema coverage being 0% makes the description responsible for explaining all parameters, which it fails to do except for item_ids.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence identifies the tool as returning the investment portfolio for a connection, with a specific list of covered asset types (FIIs, stocks, ETFs, fixed income, mutual funds, retirement, COE). The verb 'Returns' and resource 'investment portfolio' clearly differentiate it from sibling tools like openfinance_list_investment_transactions and openfinance_list_transactions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states the tool is for a connection with the INVESTMENTS product enabled, which is a clear prerequisite. It doesn't explicitly name alternatives or exclusions, but the resource distinction is self-evident from the portfolio focus; a 'when to use' note like 'for transactions use list_investment_transactions' would earn a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value beyond annotations by detailing the row structure (quantity, value, amount, netAmount, agreedRate, brokerageNumber, itemized expenses) and disclosing bulk execution support. It does not mention pagination behavior, but this is a minor gap given the safety profile is clear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded: the first sentence states the core purpose, followed by a list of returned fields. The second paragraph adds bulk usage without excess. Every sentence contributes useful information, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain return values, which it does thoroughly by listing the fields per row. It also covers input requirements (investment_id), usage context (after list_investments), and batch capability. For a read-only list tool, this is sufficiently 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 description coverage is 0%, so the description must compensate. It explains how to obtain investment_id via openfinance_list_investments and clarifies that investment_ids enables batch processing. The page/page_size parameters are left to standard conventions, which is acceptable, but not fully documented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns movement history for a specific investment position, enumerating transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER). It distinguishes itself from sibling tools like openfinance_list_transactions by focusing on investment-specific movements and referencing a prerequisite tool (openfinance_list_investments) to obtain the required investment_id.

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 sequencing guidance: 'Use after openfinance_list_investments to get the investment_id.' Also mentions bulk support via investment_ids for batched execution. However, it does not explicitly state when to use this tool over alternatives like openfinance_list_transactions, only implying the investment-specific context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral detail beyond that: 'multiple connections are queried sequentially with rate-limit spacing' and the return structure '{ results, errors } per connection'. This helps set expectations without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose and endpoint, then providing parameter details. No wasteful words; every sentence contributes essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema), the description is largely complete. It specifies the return format and the rate-limit behavior. Minor gaps like pagination or error handling details are not mentioned, but for a list tool with annotations, this is sufficient.

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 provides only 'items' as an array of strings with no description (coverage 0%). The description fully compensates by explaining the parameter meaning: connection selectors (item_id uuid, connector_id, or connector_name), one per connection, and the behavior when omitted. This adds substantial value 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?

The description clearly states the tool's purpose: 'Lists loan contracts per bank connection (GET /loans)'. The verb 'Lists' + resource 'loan contracts' + scope 'per bank connection' is specific and distinguishes it from siblings like get_loan_detail (singular) and list_credit_card_bills.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear guidance on how to use the tool: passing `items` for specific connections or omitting it for all linked banks. While it doesn't explicitly name alternatives, the distinction from get_loan_detail is implied by the plural and 'per connection' scope. No exclusions are stated, but the usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context beyond annotations: auto-pagination vs manual, 5000-row ceiling with truncated flag, upstream error return shape, provider_incident handling, per-connector inconsistency in billId and PENDING/POSTED coverage, and bulk support. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized and dense with essential information. It loses minor points for repeated billId caveats and some rambling sentence structures, yet every section (pagination, detail, incident handling, bulk) earns its place given 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?

With no output schema and 8 parameters, this description is exceptionally complete. It covers return fields, truncation, error behavior, incident awareness, cross-account echo validation, and fallback alternatives, making it fully actionable 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?

Schema coverage is 0%, so the description carries full weight. It explains all parameters: ISO YYYY-MM-DD for from/to, case- and accent-insensitive OR-semantics for search_queries, page/page_size manual vs default auto-pagination behavior, detail compact/rich/raw meanings and cost trade-offs, account_id, and account_ids for bulk.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Returns transactions for a bank account (BANK or CREDIT type).' It also clearly distinguishes this tool from siblings by stating that for CREDIT accounts it is the ONLY way to get itemized transactions, and explicitly routes bill-total needs to openfinance_list_credit_card_bills.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use and when-not-to-use guidance. It directs users to openfinance_list_credit_card_bills for standardized open-bill totals, to openfinance_list_accounts for closing/due dates, and to openfinance_get_item_status/openfinance_force_sync for sync failures. It also explicitly warns not to reconstruct bill totals by summing transactions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes well beyond the annotations by disclosing critical behavioral traits: it caps at 5000 transactions per account and flags truncated:true, includes a provider_incident block explaining that data may be incomplete during incidents, and clarifies that granularity:'raw' is heavier. These details help the agent anticipate potential incomplete results and performance implications, adding significant value beyond the readOnly/idempotent annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is lengthy but information-dense; each sentence contributes meaningful details. It covers functionality, parameters, return values, edge cases, and usage guidance in a compact manner. While it could be broken into clearer paragraphs, it remains efficient for the tool's complexity and avoids redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 9-parameter schema and absence of an output schema, the description must explain both inputs and outputs. It does this thoroughly: it describes the compact summary fields (total entradas, saídas, saldo_liquido, por_mes, top_despesas, top_recebimentos, by_account), the raw row behavior, the truncation flag, and the provider_incident block. It also covers optional behavior like bulk execution, making it highly complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description takes on the burden of parameter semantics. It successfully explains item (connector_id, connector_name, or item_id), from/to as ISO dates, granularity (monthly vs raw), detail (rich/raw), and type (BANK/CREDIT). However, top_n is only implied through 'top_despesas/top_recebimentos' and item_id/item_ids are not individually clarified, leaving some ambiguity for the remaining 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's function: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It uses specific verbs and resources, and explicitly distinguishes itself from siblings by noting it resolves accounts internally, so users don't need to call openfinance_list_accounts first. It also lists concrete use cases like 'análise anual/mensal', 'fluxo de caixa', and 'maiores gastos/recebimentos', making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides detailed guidance on when to use the tool: it suggests using it for monthly/annual analysis, cash flow, and top expenses/revenues, and explicitly says to set granularity:'raw' only when itemized rows are needed. It also mentions the bulk support via item_ids, which is another usage scenario. However, it does not explicitly name alternative sibling tools like openfinance_list_transactions, so the exclusion is only implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, idempotent, and non-destructive, but the description adds substantial context beyond that: it returns the global indicator (none/minor/major/critical), degraded components, open incidents, and flags incidents affecting the user's connected banks. It also clarifies the tool reads a public status page, which adds operational 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 longer than typical but every sentence adds useful information: the core purpose, the diagnostic trigger, the distinction from connection status, and the return format. It is front-loaded with the main purpose and then elaborates. Minor redundancy in the long parenthetical examples could be trimmed, but overall it is efficient for a complex diagnostic tool.

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 carries full responsibility for explaining what the tool does and what it returns. It fully covers the global indicator, degraded components, incidents, and the `your_banks_affected` field. It also provides real-world usage context, making the tool self-contained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters, so the baseline is 4. The description correctly focuses on behavior and output rather than inventing unnecessary parameter explanations. It also explains what the response includes, which is the relevant semantic 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?

The description states a specific verb ('Checks') and resource ('LIVE operational status of the Open Finance provider') and immediately distinguishes this from the sibling tool `openfinance_get_item_status`. It clearly identifies the provider's health as separate from the user's own connection status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: 'whenever data looks incomplete or stale even though a connection shows UPDATED' and explains that it helps differentiate provider-side problems from connection issues. It names the alternative tool (`openfinance_get_item_status`) and describes the diagnostic benefit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly and idempotent, so the bar is lower, but the description adds substantial context: return fields (connector id, access, audience, accounts), the caveat about non-auto-updating connectors, plan-based visibility (PF/PJ), and the behavior of returning a hint when keywords are omitted. These go well 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 long but information-dense, starting with the main action and then flowing through return details, caveats, plan rules, and usage timing. It earns its length, though a slightly tighter structure could improve scannability.

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?

Since there is no output schema, the description must fully explain return values and behavior. It covers all key aspects: match output (id, access, audience, connections, accounts), caveat warnings, plan coverage, and the required keywords behavior. This is complete for a search tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has zero description coverage, but the description fully compensates: it explains keywords with examples ('nubank','btg'), describes include_accounts=true behavior, and explicitly states keywords is required (with a hint fallback). Every parameter gets meaningful semantic clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Searches the available bank connectors by name.' It clearly differentiates itself from sibling tools by emphasizing pre-connection search and a ready connect_url, unlike list_connections or 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?

It explicitly states 'Call this BEFORE connecting to hand the user a one-click link to the right bank,' giving clear when-to-use guidance. It also implies when to prefer Open Finance connectors for automation, though it does not name alternative tools explicitly, so it misses an explicit when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description thoroughly discloses critical behavioral traits beyond annotations: it overrides Pluggy's automatic categorization and teaches Pluggy by creating a Category Rule that affects future transactions. It also explains batch behavior including per-item error isolation. Annotations provide no such detail, making this description the primary source of transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the tool's purpose and uses efficient, dense language. Every sentence adds critical information: operation, parameter format, side effects, batch response shape, and per-item errors. Though lengthy, it is well-structured and avoids redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for the tool's complexity: it covers the operation, parameter construction, side effects (rule creation), batch response shape, and error handling. Since no output schema exists, the description compensates by detailing the return structure. No critical gaps remain for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite zero schema description coverage, the description fully explains the `items` parameter structure, the required fields (transaction_id and category_id), and provenance of each ID. This goes far beyond what the minimal schema provides, making parameter semantics exceptionally 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's function with a specific verb ('Corrects the category'), identifies the HTTP method (PATCH /transactions/:id), and differentiates it from sibling tools like openfinance_list_transactions and openfinance_list_categories by focusing on modification rather than 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?

The description provides clear usage context, specifying that the tool is for fixing miscategorized transactions and improving future categorization. It also explains where input parameters come from (openfinance_list_transactions and openfinance_list_categories). However, it does not explicitly mention alternatives or when not to use the tool, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate non-destructive and idempotent. The description adds the requirement to include the conversation array, which gives useful behavioral context for how the tool should be invoked.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, using two short sentences to convey purpose and usage without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 3-param tool with no output schema, the description adequately covers the essential details, though it doesn't explain the response or all 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?

Schema coverage is 0%, but the description clarifies the `conversation` parameter and implies `message` is the report content. `context` remains undefined, but it has a default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: reporting bugs, missing features, or feedback. It uses specific verbs and is distinct from the sibling OpenFinance tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives clear context that the tool is for reporting issues and specifies to include the conversation array for reproduction. No alternatives are mentioned, but none exist among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds minimal context by noting 'current' versions, but does not disclose additional behavioral details like return format or potential network calls.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence that immediately communicates the tool's function with no unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only version tool with no parameters and strong annotation coverage, the description is fully adequate. It clearly states what is returned and requires 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, so the baseline is 4. The description does not need to add parameter semantics 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 clearly states the tool displays current MCP platform and adapter versions, using a specific verb and resource. It is distinct from sibling tools that focus on finance operations, authentication, or connectivity.

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 vs alternatives is provided, but the purpose is self-evident. Usage is implied for retrieving version information, which is sufficient for such a simple tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds meaningful context beyond annotations by specifying what the state contains (installed MCPs, connection status, accounts, catalog tool count). This helps the agent understand the return value and scope without requiring an output schema. It does not contradict any annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core action ('Returns the current toolkit state') and then lists the key dimensions of that state. Every word adds value, with no repetition, filler, or redundant detail. It is maximally efficient for the information it conveys.

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 informational tool, the description is fully complete. It tells the agent exactly what will be returned: installed MCPs, connection status, accounts, and catalog tool count. There is no output schema, but the description covers the return content sufficiently. No additional exclusions, prerequisites, or error conditions are relevant for such a straightforward status 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 tool has zero parameters, and the schema's coverage is 100% (empty properties). With no parameters to explain, the baseline is 4. The description does not need to add parameter semantics, and it correctly avoids inventing any nonexistent inputs.

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 specifies the tool's function with a specific verb ('Returns') and a distinct resource ('current toolkit state'), then enumerates exactly what that includes (installed MCPs, connection status, accounts, catalog tool count). This distinguishes it from sibling tools like openfinance_list_accounts or connect, which focus on specific operations rather than an overall status overview.

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 as a status/overview tool, but it does not explicitly state when to use it versus alternatives or when not to use it. It neither names alternatives nor provides context like 'check this before connecting.' The intended use is inferable from the name and description, but no explicit guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.