Banco BRB MCP

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

The description adds significant behavioral context beyond annotations, such as explaining the permanent vs. session modes, the JWT token format, and the behavior when called with no arguments. Annotations (idempotentHint=true) are consistent and supported.

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 concise but could be slightly more structured (e.g., bullet points). It front-loads the context and delivers all necessary information without 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's simplicity (one optional param, no output schema), the description is mostly complete. It covers the two usage modes and what to expect. Minor omission: no mention of error conditions or token validation.

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

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

Despite 0% schema description coverage, the description fully explains the sole parameter 'token': it's a JWT for session-only login, and omitting it returns a login link. This adds complete meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose: authentication for MCP.AI in IDE agents. It specifies two distinct methods (permanent config or session token) and implicitly distinguishes from sibling tools like 'connect' which likely handle other authentication flows.

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 context on when to use each method: adding to config for a permanent connection or pasting a token for a session. It also notes that calling with no args returns a link. However, it does not explicitly exclude other tools or mention 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 (readOnlyHint=true, destructiveHint=false) already indicate safe read operation. The description adds behavioral context by specifying the return format (authenticated, pending, connect_url) for different states, but does not disclose additional traits like rate limits or side effects.

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

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

The description is concise with two sentences. It front-loads the primary purpose and efficiently covers two key states without unnecessary words.

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

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

Given the simplicity of the tool (no parameters, safe operation, no output schema), the description is complete. It explains both success and missing-credentials scenarios, which is sufficient for an agent to understand and use the tool effectively.

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

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

There are no parameters, and schema coverage is 100%. The description does not need to explain parameters but adds value by describing the output behavior, which compensates for the absence of 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 returns connection status and URLs, and explains two scenarios (all connected vs missing credentials). However, it does not explicitly differentiate from siblings like 'authenticate' or 'openfinance_list_connections', which could have overlapping purposes.

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 any guidance on when to use this tool versus alternatives. It lacks context on prerequisites or conditions under which this tool should be preferred over similar tools like 'openfinance_get_item_status' or 'openfinance_list_connections'.

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 key behavioral traits well beyond the sparse annotations: invoke runs a tool one-off without adding to the toolkit, writes require workspace owner/admin, credential/payment issues return connect/checkout links, and search/describe flag installed status. It also mentions the prompt library's behavior with shareable links. All of this adds meaningful context that the annotations alone do not provide.

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

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

The description is a single dense paragraph but is front-loaded with the tool's identity and each clause adds operational detail. It covers a lot of ground without redundant wording, though it would be easier to parse if broken into sections (MCP flow vs prompt library). Given the tool's complexity, the length is justified, and there is no obvious padding.

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

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

For a tool with 14 actions, 23 parameters, and no output schema, the description covers the main workflows, permission requirements, and the install-versus-invoke distinction. It does not explicitly mention the `resume` action, and some parameters receive no explanation, but the core functionality and edge cases (credentials, payment, owner/admin) are addressed, making it largely complete for practical use.

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

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

With 23 parameters and 0% schema coverage, the description must compensate and largely does: it explains the core `action` enum values (search, describe, invoke, install, subscribe, cancel, report_bug, request_mcp, list_tools, and the prompt actions) and gives context for `tool_id`, `prompt_slug`, and the overall routing logic. However, several parameters such as `tier_slug`, `immediate`, `conversation`, and `prompt_targets` are not explicitly mentioned, so coverage is strong but not complete.

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 clear identity: 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It goes on to describe a concrete core flow (search → describe → invoke) and distinguishes it from sibling financial tools by framing it as a catalog/runner rather than a domain-specific service. This goes beyond a vague 'marketplace' label.

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 provided: 'Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use.' It also explains when to use search/describe/invoke, clarifies that invoke works without installation, and outlines the roles of list_tools, subscribe/cancel, and prompt-specific actions, giving strong when-to-use versus alternative guidance.

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 indicate destructiveHint=true. The description adds that consent is revoked, connection data is deleted, and data becomes unavailable. It also notes the return of a re-connect URL, providing non-obvious behavioral detail beyond annotations.

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

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

Three sentences, front-loaded with the main action, followed by consequence and return value. No redundant or extraneous 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 covers the return value without an output schema, which is helpful. However, it omits details about the input parameter and potential errors. Given the low complexity and zero schema coverage, the description is adequate but not fully 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% and the description does not clarify the 'item' parameter. It says 'for a specific bank' but does not specify what value to provide (bank ID, connection ID, etc.). The description adds minimal 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 the action: revokes consent and deletes connection data. It specifies the resource (specific bank) and the consequence (data no longer available). The return of an add_connection_url distinguishes this from other 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?

The description implies use for disconnecting a bank but does not explicitly state when to use versus alternatives or provide context on prerequisites. No mention of 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?

Discloses waiting behavior (~60s), polling mechanism, and result fields including error states (needs_action, timed_out). Annotations only indicate non-readonly/non-destructive, but description adds crucial 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 long but every sentence adds value. Could be slightly more concise, but front-loads the core action and provides comprehensive details without redundancy.

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

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

Given no output schema, description thoroughly explains return structure (results, errors, status fields) and error handling (reconnect_url for auth issues). Covers all user-facing aspects of the 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 2 parameters with 0% description coverage; description compensates fully by explaining wait's effect on synchronization mode and items' flexible selectors (item_id, connector_name, etc.) and default behavior.

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 forces a bank to re-sync connections and waits for completion. Distinguishes from sibling tools like openfinance_get_item_status by specifying it triggers a sync and returns final 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 describes when to use (stale balances/transactions), how to use (array of selectors or omit for all), and when not (wait: false for fire-and-forget). Mentions alternative tool for checking status if timeout.

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 mark the tool as read-only, idempotent, and non-destructive, and the description adds substantial behavioral detail beyond that: the balance is a snapshot anchored to the last upstream sync, not a live read; credit accounts may return specific Pluggy errors; non-Open Finance connectors or upstream 5xx responses degrade to a last-synced balance with realtime:false and a warning instead of throwing. These details are not present in the annotations and materially affect how an agent interprets 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 long but densely informative, and each sentence earns its place. It opens with the core behavior, then logically covers freshness caveats, error modes, degradation, and response shape. No fluff or repetition; every detail supports correct invocation and interpretation.

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?

Even though there is no output schema, the description specifies the response envelope ({ results, errors }) and the key row fields (updateDateTime/updatedAt, realtime, warning) plus error and degradation behaviors. An agent has enough information to invoke the tool, anticipate failures, and correctly interpret the returned 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?

The schema only defines account_ids as an array of strings with zero description, so the description carries the entire semantic burden. It adds the crucial constraint that account_ids must be an array of 1–50 items, which directly supplements the bare schema. It does not provide an example or explain how to obtain account IDs, but for a single-parameter tool this is reasonable compensation.

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

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

The description clearly states it returns the latest available balance per account id and directly identifies the underlying endpoint (GET /accounts/:id/balance). It also differentiates itself from related tools by referencing openfinance_force_sync and openfinance_list_transactions in the data-freshness flow. There is no ambiguity about the operation or 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 gives explicit conditional guidance: if a recent movement is not reflected or the balance disagrees with transactions, run openfinance_force_sync and re-read. It also explains when errors occur and how to recover from consent issues. It does not explicitly state 'use this when you need the latest balance' in a standalone sentence, but the snapshot caveat and sync suggestions make the intended context 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 indicate read-only and idempotent. Description adds critical context: provider_incident block that may affect data reliability, and instructs not to present unreliable values. This goes beyond annotations, enhancing 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?

Four sentences, each adding value: main action, parameter usage, batch shape, and warning. Front-loaded with the core purpose. 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 adequately covers return shape (full objects with creditData, batch results/errors) and alerts about provider incidents. Lacks details on exact fields, but sufficient for a retrieval tool with rich annotations.

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

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

Schema has 0% description coverage, so description provides the only guidance. It specifies the array length constraint (1-50) and batch behavior, adding significant meaning beyond the schema type definition.

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 account objects with extended creditData per ID, specifying the batch shape. Distinguishes from list_accounts by focusing on detail retrieval, though not explicitly contrasting with 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?

Describes parameter usage (array of 1-50 IDs) and batch shape, implying use for detailed retrieval. No explicit guidance on when to use vs. alternatives like list_accounts, or 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?

Beyond the readOnly, idempotent, and non-destructive annotations, the description explains non-obvious behavior: bills don't contain transactions by default, transactions can only be enriched with account_id and include_transactions, transactions_basis may be an exact bill_id or an estimated date_window, and payments[] does not mean the current bill was paid. This is exactly the kind of behavioral context annotations cannot 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 dense but high-signal every sentence earns its place. It front-loads the core return fields, then explains the optional transaction behavior, then covers estimates and payment caveats. There is little padding relative to the complex semantics it communicates.

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?

Even with no output schema, the description specifies the return fields, the batch response shape { results, errors }, transactions-basis semantics, estimate confidence, and cross-tool guidance. It covers the complex edge cases of pending bills, payment timing, and authoritative totals, so the tool can be invoked and interpreted correctly from the descriptions alone.

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 carries the burden of explaining parameters. It clearly explains bill_ids as an array discovered via a list tool, account_id as required for transaction enrichment because the bill lacks an account reference, and include_transactions as the boolean opt-in for itemized purchases. However, transactions_detail is never mentioned, leaving its enum values completely ambiguous.

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

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

The description opens with a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id', and then lists concrete fields (dueDate, billClosingDate, totalAmount, payments). It distinguishes itself from sibling tools by explicitly naming openfinance_list_transactions and openfinance_list_credit_card_bills for adjacent but different use cases.

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 routing: use openfinance_list_credit_card_bills first to discover bill IDs, use openfinance_list_transactions when transactions are needed for other purposes, and prefer openfinance_list_credit_card_bills to check paid status because this tool returns no paid/status field. An agent can choose the correct tool without additional documentation.

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 readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing a safe, read-only profile. The description adds valuable behavioral context beyond annotations, such as the reconnect_url behavior (reopening widget without disconnecting or consuming a slot) and bulk execution support. 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 paragraph but is relatively concise and front-loaded with the core purpose. It efficiently explains key details (bulk support, reconnect_url) without extraneous information. A slightly more structured format (e.g., bullet points) could improve scannability, but it remains clear.

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

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

Given the complexity (3 optional parameters, no output schema, multiple sibling tools), the description covers the main usage patterns but lacks explicit details on the return structure for single items (beyond 'returns the current status') and does not clarify the distinction between 'item' and 'item_id'. The bulk return format is mentioned as '{count, items}', which is helpful.

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% for parameter descriptions, so the description carries the full burden. It explains that 'item' is optional (omit for all, pass for single) and that 'item_ids' supports batched execution. However, it does not clarify the difference between 'item' and 'item_id' (both are strings), leaving ambiguity.

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 current status of a bank connection, lists possible statuses, and explains what is included (executionStatus, connector metadata, reconnect_url). It also distinguishes between querying a single connection via 'item' and all connections, which differentiates it from siblings like openfinance_list_connections.

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

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

The description provides explicit usage context: when to omit 'item' vs. pass it, and mentions bulk support via 'item_ids'. It gives helpful details on the reconnect_url feature. However, it does not explicitly state when not to use this tool or compare it to alternative sibling tools.

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 batch shape { results, errors } and input limit (1-50), enhancing behavioral understanding 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 concise, well-structured with bullet-like detail fields, and front-loaded with the main purpose. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description outlines key response fields and batch shape, providing sufficient context for a detail endpoint. Minor gaps in error details don't detract significantly.

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 explains the lone parameter 'loan_ids' as an array of loan IDs with a batch size of 1-50, and indicates the response structure.

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

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

The description clearly states the tool returns full loan contract detail by ID, specifying the resource and action. It distinguishes the usage from the sibling tool openfinance_list_loans.

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

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

The description explicitly advises use after openfinance_list_loans for deep-dive on a specific contract, providing clear context for when 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 far beyond the annotations, detailing subtle behaviors such as `balance_notice`, `provider_incident`, `identity_notice`, and stale `bankData` fields. These are crucial for correct agent behavior and are not inferable from the read-only or idempotent hints.

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 primary purpose and every caveat is substantive. However, it is quite long and could be tightened or grouped more aggressively without losing important 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 that there is no output schema, the description compensates well by covering output fields, notional notices, provider incidents, edge cases, and cross-tool routing. An agent has enough context to invoke the tool and interpret results correctly in most real scenarios.

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 the burden. It thoroughly explains `item` and `item_ids` behavior, but it does not explicitly describe the `type` filter or the singular `item_id` parameter, leaving minor ambiguity.

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 that the tool returns bank and credit accounts with balance, number, type, subtype, bankData, and creditData. It also distinguishes itself from related tools like openfinance_list_credit_card_bills by clarifying that it does not provide standardized billing amounts.

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

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

The description gives explicit when-to-use guidance: omit `item` for all accounts, pass `item` for a single bank, and use openfinance_list_credit_card_bills for standardized open-bill amounts. It also warns against misinterpreting credit balance and directs when to consult other sources.

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 significant behavioral context beyond the annotations: it reveals the backend API (GET /categories), caching behavior (cached for the adapter session), aggregation (single aggregated response, no batch ids), and the exact structure of each entry. Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; the description enriches these with concrete operational details. 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 paragraph of three sentences, each adding essential information: the main action and caching, the output fields and their significance, and a note about aggregation. There is no redundancy or filler. The most critical information (caching, id usage) appears early.

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

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

Given that the tool has no parameters and no output schema, the description fully explains what it returns (fields, structure) and how it behaves (cached, aggregated). It also links to the sibling tool that consumes the output. For a list tool with this complexity, the description is complete and leaves no ambiguity about the response content or lifecycle.

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 coverage is 100% by definition. Per the rubric, this yields a baseline score of 4. The description does not need to add parameter information since there are none; it focuses on the output, 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 clearly states that the tool returns Pluggy's transaction category taxonomy via the GET /categories endpoint, cached for the session. It specifies the output fields (id, description, descriptionTranslated, parentId, parentDescription) and explicitly links the id to the sibling tool openfinance_update_transaction_category. This distinguishes it from other list tools (e.g., openfinance_list_transactions) and makes 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 indicates that the id field is used by openfinance_update_transaction_category, providing a clear use case for calling this tool (to obtain category identifiers for updates). It also notes that the response is cached for the adapter session, implying it can be called repeatedly without penalty. However, it does not explicitly contrast with other list tools or state when not to use it, which would be helpful given the many sibling tools.

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 valuable context about non-consumption of slots and reconnect_url behavior, 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-loaded with the main purpose, but somewhat dense. It communicates efficiently without unnecessary words.

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

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

With no output schema, the description covers the return fields adequately and explains the reconnect_url usage. It is complete for the tool's simplicity.

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

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

There are zero parameters, so schema coverage is 100%. The description compensates by explaining the output fields, providing 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 the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, etc.) and distinguishes the reconnect_url behavior. It is a specific verb and resource, and the sibling tools are differentiated by 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?

Provides clear context on when to use the reconnect_url (re-authentication needs), and states what the tool does not do (consume connection slots, require disconnecting). However, it does not explicitly compare against sibling tools for listing vs. other operations.

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, destructiveHint=false. The description adds rich behavioral context: explains payment semantics across cycles, derivation of payment_status, connector asymmetry (open_bill availability), and reliability warnings. There is no contradiction with annotations.

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

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

The description is thorough and well-structured with clear sections (payment_status, open_bill, etc.) and front-loaded with the purpose. However, it is quite lengthy and could be more concise, especially in the payment_status derivation. Despite this, every part adds value given the subject'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, the description fully explains the return fields (payments[], payment_status, open_bill, future_bills, etc.) and covers edge cases (connector asymmetry, payment timing, reliability warnings). It also provides instructions for cross-referencing with other tools and handling multiple banks. The description is 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?

The input schema has 5 parameters with 0% description coverage, so the description must compensate. It thoroughly explains include_open_bill, including its opt-in nature, what it returns, and connector asymmetry. It also mentions account_id implicitly and account_ids for bulk. However, it does not describe page and page_size, which are standard but could benefit from clarification (e.g., defaults, max values). This is a minor gap.

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

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

The description clearly states the tool returns closed credit card bills for CREDIT-type accounts, listing key fields and the derived payment_status. It distinguishes from siblings like openfinance_list_transactions (for itemized transactions) and openfinance_get_credit_card_bill (for a single bill), ensuring the agent selects the correct 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 explicit when-to-use guidance (e.g., to get closed bills, use payment_status for payment status) and when-not-to-use (e.g., do not assume payment from payments[] array, do not sum by billId). It names alternatives like openfinance_list_transactions for itemized charges and warns against reconstructing totals from transactions. It also notes bulk support with account_ids.

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?

Discloses handling of 403 errors with a structured response, data integrity checks for mass zeroing, and the `data_integrity_warning` flag, adding significant detail beyond annotations that indicate a safe, read-only operation.

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 with multiple paragraphs and technical details; it could be more concise while retaining key 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?

Covers return structure, error handling, and edge cases well, but lacks explanation of pagination parameters (`page`, `page_size`), making it slightly incomplete for a tool with no output schema.

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 only explains `item_ids` for batching, leaving other parameters (e.g., `item`, `page`, `type`, `page_size`) unexplained.

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 investment portfolio for a connection and lists specific types (FIIs, stocks, ETFs, etc.), distinguishing it from sibling 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?

Implies usage for retrieving investment data and mentions bulk support, but lacks explicit when-to-use or when-not-to-use guidance compared to alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds field details and batch execution capability, providing useful context beyond annotations.

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

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

Two well-structured paragraphs: first defines purpose and output fields, second adds bulk support. No extraneous 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?

Lists returned fields and expense breakdown, prerequisite, and batch support. Lacks explicit pagination guidance and output structure, but is mostly complete for a list tool without output schema.

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 explains investment_id and investment_ids, but not page and page_size. With 0% schema description coverage, it partially compensates but leaves pagination undefined.

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 investment positions, listing specific transaction types. It distinguishes from sibling openfinance_list_investments, which is mentioned as a prerequisite.

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 using after openfinance_list_investments to get investment_id, and mentions bulk support. Does not explicitly exclude alternatives like openfinance_list_transactions, 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.

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds sequential querying with rate limiting and response format {results, errors}, which are behavioral traits beyond annotations.

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

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

Three sentences, no wasted words. Front-loaded with purpose, then explains parameter and behavior. 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 no output schema, the description still explains the return shape. Covers input modes and behavior. Sufficient for tool selection among similar siblings.

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 the description thoroughly explains the 'items' parameter: its type (array of connection selectors), valid values (uuid, connector_id, connector_name), and behavior when omitted. Fully compensates for missing schema descriptions.

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

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

Explicitly states 'Lists loan contracts per bank connection (GET /loans)', clearly identifying the resource and verb. Distinguishes between two usage modes (with items array or without), making it distinct from siblings like get_loan_detail.

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

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

Provides clear guidance on when to use each mode: pass items for specific connections, omit for all. Mentions rate-limit spacing for multiple connections. Could explicitly mention alternatives for single loan details, but still strong.

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 far more than annotations already provide: auto-pagination behavior, the 5000-transaction ceiling, truncated results, scheduled rows and date ordering, per-connector PENDING variance, upstream error envelopes, provider_incident blocks, and creditCardMetadata caveats. It does not conflict with the readOnlyHint/idempotentHint annotations.

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

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

The description offers a wealth of operationally relevant details and clusters topics logically, but it is long and lightly redundant—especially the billId/summing caution that appears twice. Overall, each sentence earns its place despite some 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?

Since there is no output schema, the description covers essentially all return-shape information an agent needs: account echo, scheduled_count, notice, warning/error envelope, provider_incident, and per-credit metadata. It is comprehensive enough to make correct invocation decisions without additional lookup.

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 fully compensate. It does this by thoroughly explaining every parameter: ISO from/to filters, OR-semantics search_queries, omission vs explicit page/page_size, max values, detail enum semantics, and the influence of account_id through the echoed account block.

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 transactions for a bank account') and explicitly identifies CREDIT open finance transactions as a use case only this tool covers. This differentiates it from sibling tools like openfinance_list_credit_card_bills and openfinance_list_transactions_by_item.

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 routing decisions: use openfinance_list_credit_card_bills for authoritative billed totals, use openfinance_list_accounts for statement closing/due dates, and use openfinance_get_item_status when a CREDIT total is zero. It also tells the agent when to default to 'compact' detail and when to use 'rich' or 'raw'.

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, idempotentHint, and destructiveHint. The description significantly expands on these with critical behavioral details: a 5000-transaction-per-account cap flagged by truncated:true, a provider_incident block warning of incomplete data during provider outages, and detailed output structure (e.g., 'por_mes', 'top_despesas'). There is no contradiction with annotations, and the description adds substantial transparency 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 key benefit and structured logically: purpose, parameter details, use cases, then behavioral notes. However, it is quite verbose, with some repetition (e.g., repeated mention of no need to call list_accounts). The length is justified by the tool's complexity, but trimming unnecessary phrases could improve conciseness without losing clarity.

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

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

Given the tool's 9 parameters, no required fields, and absence of output schema, the description provides a complete understanding of the tool's behavior. It covers input parameter semantics, output structure (including the compact vs raw returns, per-account breakdown, and incident flags), usage boundaries (5000 cap, bulk support), and error/edge cases (provider incidents). The description compensates fully for the lack of an output schema.

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 every parameter: item (accepts connector_id, connector_name, item_id), from/to (ISO dates), granularity (default 'monthly' vs 'raw'), detail (compact/rich/raw with specific output differences), type (BANK or CREDIT), top_n (implied in 'largest N'), item_ids (batch execution). The semantic meaning is fully conveyed, enabling correct use without schema descriptions.

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

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

The description clearly states that the tool provides 'consolidated cash-flow analysis for a whole bank connection over a period, in ONE call'. It explicitly distinguishes from siblings by noting that it resolves accounts internally, eliminating the need to call openfinance_list_accounts first. The specific use cases and output structure are detailed, 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?

The description provides strong usage guidance by listing concrete scenarios like 'análise anual/mensal', 'fluxo de caixa', and explains when to use different granularity and detail options. It also mentions bulk support and the ability to omit the item parameter to analyze all linked banks. While it does not explicitly state when NOT to use this tool, the context of sibling tools and the detailed parameter descriptions offer clear direction. A slightly more explicit exclusion would improve the score.

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, but the description adds valuable behavioral context: it reveals upstream outages, returns global indicator, degraded components, open incidents, and flags affected banks. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph of about 60 words. It starts with the core purpose, then usage guidelines, then details of what it returns. Every sentence adds value with no redundancy.

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

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

Given no parameters, good annotations, and no output schema, the description fully explains what the tool returns (global indicator, components, incidents, your_banks_affected) and when to use it. It is complete for a read-only status check tool.

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

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

The input schema has zero parameters (100% coverage), so there is nothing to describe. Baseline for zero parameters is 4; no additional information is needed.

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

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

The description clearly states it checks the LIVE operational status of the Open Finance provider's public status page, distinguishing it from openfinance_get_item_status. The verb 'Checks' and resource 'provider status' are specific and unambiguous.

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

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

The description explicitly states when to use this tool: 'whenever data looks incomplete or stale even though a connection shows UPDATED' and contrasts it with openfinance_get_item_status, telling the agent to use it to differentiate provider-side problems from connection issues.

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 indicate read-only, idempotent, non-destructive. Description adds significant context: return fields, plan behavior, caveat warnings for non-Open-Finance connectors, and that missing keywords returns a hint. 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?

Dense with information but every sentence adds value. Slightly verbose due to multiple clauses; could be more structured but remains efficient and front-loaded.

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

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

No output schema exists, but description comprehensively covers return values, edge cases (missing keywords), caveats, and plan integration. Provides all necessary context for an agent to use the tool correctly.

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

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

Schema has 0% description coverage, but description fully explains both parameters: keywords as required array with examples, include_accounts for including accounts in results. Adds crucial usage context 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?

Clearly states the tool searches bank connectors by name keywords and returns specific details including a connect URL. Differentiates from sibling tools like openfinance_list_connections by focusing on search and pre-selection.

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

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

Explicitly instructs 'Call this BEFORE connecting' and highlights that keywords are required, never dumping the whole catalog. Also explains plan-based filtering, providing clear guidance on when and how 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 discloses significant behavioral details beyond annotations: it overrides automatic categorization and creates a Category Rule for future similar transactions. It also explains batch error handling ('per-item errors do not fail the whole batch'). Annotations only indicate non-read-only, non-destructive, which are consistent.

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

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

The description is a single paragraph that is information-dense but not overly verbose. Every sentence adds value, though it could be slightly restructured for readability. It front-loads 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?

Given the tool's complexity (batch mutation with side effects and error handling) and no output schema, the description covers the return format, error behavior, and the non-obvious rule creation side effect. It is complete for an AI agent to correctly invoke.

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 descriptions (0% coverage). The description compensates fully by explaining the items array structure, required fields (transaction_id, category_id), and where to obtain them from sibling tools.

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 'Corrects the category of one or more transactions (PATCH /transactions/:id)', which is a specific verb and resource. It distinguishes from siblings as the only tool for updating transaction categories.

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

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

The description clearly tells how to use the tool by specifying the source of transaction_id and category_id from sibling tools. It explains the effect of creating Category Rules, guiding when to use. It lacks explicit when-not-to-use or alternatives, but no sibling performs the same function.

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 are present (readOnlyHint: false, destructiveHint: false, idempotentHint: true), but the description adds no behavioral context beyond them. It does not mention side effects, rate limits, or what happens after submission, such as whether a confirmation is returned.

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 long, with the first sentence stating the purpose and the second providing a key usage tip. Every sentence adds value, and it is front-loaded with the most important 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 (3 parameters, no output schema), the description covers the main purpose and a key usage detail. However, it lacks explanation of the 'context' parameter and does not describe the expected response or side effects, leaving some gaps.

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

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

With 0% schema description coverage, the description partially compensates by explaining that 'message' is the report text and 'conversation' should contain the conversation array for reproduction. However, it does not explain the 'context' parameter, leaving it ambiguous.

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

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

The description clearly states that the tool is for reporting bugs, missing features, or sending feedback, which is a specific verb+resource combination. It is distinctly different from the sibling tools, which are mainly open finance data retrieval and management tools.

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

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

The description implies that this tool should be used to provide feedback or report issues, but it does not explicitly state when to use it versus alternatives. Since there are no similar sibling tools, the lack of explicit guidance is less critical, but still a gap.

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, destructiveHint=false, so behavioral traits are well covered. The description adds no extra behavioral context beyond the function purpose, but is consistent 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?

Single sentence, no wasted words, ideally front-loaded. Perfectly concise for the tool's simplicity.

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 and annotations covering behavior, the description is mostly complete. Minor missing details about return format, but likely sufficient for a version display tool.

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

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

With no parameters (100% schema description coverage), the description does not add parameter-level meaning, but the baseline 3 applies since schema already covers all.

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 shows current MCP platform and adapter versions, using specific verb 'show' and resource 'versions'. It distinguishes from sibling tools which are mainly finance operations or authentication.

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

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

The description implies use when version info is needed, but lacks explicit guidance on when to use this vs alternatives like 'toolkit_info', which might also provide version information. No exclusions or context provided.

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 the safety profile is covered. The description adds value by detailing the content of the returned state (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations and helps the agent anticipate the tool's output.

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

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

The description is a single sentence that is front-loaded with the action ('Returns') and the resource ('current toolkit state'), followed by a clear enumeration of the contents. Every word contributes meaning, with no fluff 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?

The tool has no parameters, no output schema, and annotations cover the safety aspects. The description fully explains what the tool returns by listing the specific state components, which is sufficient for an agent to understand the tool's purpose and output without ambiguity.

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

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

The input schema is an empty object with 0 parameters, so there are no parameter semantics to document. The baseline for 0 parameters is 4, and the description correctly avoids adding any parameter-related information that would be irrelevant.

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 'Returns' and identifies the resource as 'the current toolkit state'. It further enumerates the exact components (installed MCPs, connection status, accounts, catalog tool counts), which distinguishes it from sibling tools like show_version or openfinance_list_connections that focus on different aspects.

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 for when to use the tool: when an agent needs an overview of the toolkit's installed MCPs, their connections, and exposed tools. It does not explicitly name alternatives or exclusions, so it stops short of a 5, but the context is unambiguous and easy to infer.

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