Banco Bmg MCP

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

The description adds behavioral context beyond annotations by explaining the two different outcomes (link vs. token acceptance) and the session/permanent distinction. It does not contradict the idempotentHint and destructiveHint annotations.

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

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

The description is informative and well-structured, starting with the principal action and then outlining two use cases. It is slightly dense but not overly verbose, earning a score just below the highest tier.

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

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

Given the simple tool with one optional parameter and no output schema, the description covers most needed context: token origin, usage modes, and the config alternative. It could be more explicit about the return format when no args are provided, but overall it 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?

With 0% schema description coverage, the description fully compensates by explaining that 'token' should be a JWT from browser login, and that omitting it returns a link. This gives complete semantic meaning.

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

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

The description clearly states the tool's purpose: authenticate MCP.AI for IDE agents by providing an access token or obtaining a login link. It distinguishes from sibling tools by focusing solely on 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 provides explicit guidance on two modes: using a config for permanent access or pasting a token for session-only login. It also tells the user to call with no args to get the link. However, it does not explicitly contrast with sibling tools like 'connect'.

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 behavior. The description adds value by detailing the two possible return states (authenticated:true vs connect_urls). No contradictions with annotations.

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

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

Two sentences, front-loaded with the main purpose, no wasted words. Efficiently conveys 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?

For a simple status check with no output schema, the description covers the two main scenarios (all connected vs missing credentials). It might not cover other partial states or errors, but given the read-only nature, it is likely 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?

No parameters exist, so schema coverage is effectively 100%. The description does not need to add parameter information beyond what the schema provides. Baseline 4 is exceeded because no parameters simplifies the need.

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, explains two distinct states (all connected vs missing credentials). It is specific about the resource (connection status) and verb (returns). However, it does not explicitly differentiate from sibling tools like 'authenticate' or 'openfinance_list_connections', which could be confused.

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 checking overall connection health but does not specify when to use this vs alternatives like 'authenticate' or 'openfinance_list_connections'. No explicit when-not or recommendations are given.

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=false, openWorldHint=true, etc.), the description discloses key behavioral details: invoke works even when the MCP is not installed (one-off run without adding to toolkit), returns connect/checkout links for missing credentials or payment, and search/describe flag installed status. It also mentions that writes require owner/admin, adding valuable context not covered by 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 dense and front-loaded with purpose, but it is a large wall of text covering many actions and the prompt library. Every sentence adds value, yet a structured format (e.g., bullets) could improve readability. It is appropriately sized for the tool's complexity but slightly verbose.

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

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

Given the tool's high complexity (14 actions, 23 params, no output schema), the description is remarkably complete. It explains the core flow, edge cases like connect/checkout links, auth requirements, and the prompt library's search/get/publish lifecycle. It also covers what each main action returns, compensating 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?

Schema description coverage is 0%, so the description carries the burden of explaining parameters. It explains the core 'action' enum and several key parameters (e.g., tool_id, mcp_id, prompt-related fields) through workflow examples, but does not explicitly describe every one of the 23 parameters (e.g., limit, immediate, tier_slug). The high-level guidance compensates substantially, but a few parameters remain under-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 is the official mcp.ai marketplace, acting as both a catalog of every MCP/tool and the way to run them. It differentiates itself from siblings by focusing on discovery, description, invocation, and management of MCPs, with a clear primary verb+resource structure. It also distinguishes between MCP-related actions and the prompt library.

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: prefer invoke for occasional use, use install only to make an MCP permanent, and lists actions like search, describe, list_tools, subscribe/cancel, report_bug, and request_mcp with their intended purposes. It also clarifies that writes require workspace owner/admin, providing clear exclusions and operational 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 mark destructiveHint=true. The description adds value by stating that bank data will no longer be available and that an add_connection_url is returned for reconnection, providing useful behavioral context beyond annotations.

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

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

Three concise sentences that front-load the action, then explain consequences and return value. No 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?

For a tool with one parameter and no output schema, the description explains the outcome and return value fairly well. However, it lacks parameter details and prerequisites (e.g., must have an existing connection). Overall adequate but not exhaustive.

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 'item' parameter is required but has no schema description. The description mentions 'specific bank' but does not clarify the format or source of the item. With 0% schema coverage, the description should compensate but does not provide enough detail.

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

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

The description clearly states the tool revokes Open Finance consent for a specific bank, deletes connection data, and makes data unavailable. It uses specific verbs and resource, and is distinct from sibling tools like openfinance_list_connections or openfinance_get_account_balance.

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

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

Description implies usage when disconnecting a bank but does not explicitly compare to alternatives or state when not to use it. No exclusions or context about prerequisites are 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?

Adds rich behavioral details beyond annotations: polling up to 60s, return format with final status, synced flag, needs_action with reconnect_url, timed_out fallback. Annotations are minimal and not contradicted.

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 paragraph is well-organized and front-loaded but could be slightly more structured with bullet points. Still very effective and efficient.

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

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

Covers all aspects: purpose, usage, parameters, return values, error handling, edge cases, and interaction with other tools. No output schema, but description fully compensates.

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?

Both parameters are thoroughly described despite 0% schema coverage. Items explained as array of selectors and optional meaning sync all; wait explained as true/false with fire-and-forget semantics.

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 forces a sync of connections and waits for completion. Distinguishes from siblings by focusing on force re-sync vs. other actions like get status or list.

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

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

Explicitly says when to use (stale balances/transactions) and what it does not do (disconnect/reconnect). Provides guidance on items and wait parameters and handling of needs_action results.

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 annotations (readOnlyHint, idempotentHint, destructiveHint). It discloses that CREDIT accounts may return warnings instead of errors, and that results degrade to last-synced balance with realtime: false when upstream is unavailable. No contradictions with annotations.

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

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

The description is concise with three sentences covering purpose, usage, and edge cases. It is front-loaded with the main function. Slightly more structured formatting (e.g., bullet lists) could improve readability, but overall efficient.

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

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

The description covers the response shape ({ results, errors }) and error scenarios thoroughly. With only one parameter and no output schema, it provides adequate completeness 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 schema has 0% description coverage and the description partially compensates by stating account_ids is an array of strings with size 1-50. However, it does not explain the format or source of the IDs (e.g., how to obtain them from other calls). Baseline 3 for partial coverage.

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

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

The description clearly states the tool returns real-time balance payload per account id, specifying the endpoint path (GET /accounts/:id/balance). It distinguishes from sibling tools like openfinance_get_accounts_detail which return account details rather than balances.

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

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

The description provides explicit guidance: pass account_ids as an array (1-50). It explains behavior for CREDIT accounts (BALANCE_FETCH_ERROR with warning) and degradation when upstream is unavailable. However, it does not explicitly compare to alternative tools for balance retrieval.

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 crucial behavioral context beyond annotations: the batch shape `{ results, errors }` and the `provider_incident` block warning that credit limits/balances may be unreliable. This helps the agent handle edge cases, and annotations already indicate read-only and idempotent, so no contradiction.

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

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

The description is concise at four sentences, each serving a distinct purpose: purpose, parameter usage, batch shape, and provider incident warning. No extraneous information, and critical details are front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema), the description is complete enough. It covers the return structure and the key caveat about provider incidents. However, it could mention error handling or the specific format of `creditData`, but these are not essential.

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

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

The description clarifies that `account_ids` must be an array of 1–50 strings, adding a constraint not present in the schema (which only defines type). While schema coverage is 0%, this single piece of guidance is valuable and covers the only parameter.

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

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

The description clearly states the tool returns full account objects including extended creditData per ID, with a batch shape. The verb 'Returns' and resource 'account objects' are specific, and the operation is distinguished from listing tools by focusing on detail 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 specifies to pass `account_ids` as an array (1–50), giving clear parameter usage. However, it lacks guidance on when to use this tool versus siblings like `openfinance_list_accounts` or alternatives, and does not mention prerequisites or exclusions.

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 critical context: batch shape (results/errors), that payments may be from previous cycle, that Pluggy lacks a paid status field, and that transaction billId hints are unreliable. 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 relatively long but each sentence adds essential value. It front-loads the main purpose, then systematically addresses edge cases and usage notes. Some minor redundancy could be trimmed, but overall it's well-structured.

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

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

Given no output schema, the description thoroughly explains return fields (financeCharges, payments with subfields) and batch shape. It also addresses domain-specific nuances (Brazilian Open Finance, payment cycle interpretation, billId inconsistency). This makes the tool highly usable without external documentation.

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

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

With 0% schema description coverage, the description compensates by explaining the purpose of bill_ids and how to obtain them (via list siblings). It clarifies it's an array, which is sufficient for a simple string array parameter.

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 like financeCharges and payments. It also distinguishes itself from the sibling tool openfinance_list_transactions, 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?

Explicitly tells when to use (get bill details) and when not to (not for transactions, not to reconstruct totals). Provides step-by-step guidance to first use openfinance_list_credit_card_bills to discover IDs, and warns about common pitfalls regarding payment interpretation and billId inconsistencies.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: the reconnect_url reopens the widget in UPDATE mode without disconnecting or consuming a slot. No contradictions with annotations.

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

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

The description is two sentences, front-loading the primary purpose and return values. While the first sentence is dense, it efficiently conveys multiple 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, the description adequately covers return elements (status, executionStatus, metadata, reconnect_url) and behavior for single vs. bulk queries. It could clarify conflict handling when both `item` and `item_ids` are provided, but overall it's sufficient for a read-only 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?

Schema coverage is 0%, so the description must explain parameters. It clarifies `item` for single bank retrieval and `item_ids` for batched execution, but does not explain `item_id` (possibly an alias). The description partly compensates for the missing schema descriptions.

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

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

The description clearly specifies the tool returns the current status of a bank connection with enumerated values (UPDATED, UPDATING, LOGIN_ERROR, etc.), along with executionStatus, connector metadata, and reconnect_url. It distinguishes between single-item and bulk retrieval, setting it apart 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 explains when to omit or include the `item` parameter for single vs. all banks, and mentions bulk support via `item_ids`. However, it does not explicitly compare to alternatives like `openfinance_list_connections` or state when not to use this 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 readOnly=true and idempotent=true. Description adds batch behavior, error shape (`{ results, errors }`), and field details, enhancing transparency without 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?

Single paragraph with purpose upfront, followed by structured list of return fields and usage hint. Efficient but could be more organized.

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

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

For a single-parameter read tool with annotations, the description provides rich field details, batch error handling, and usage context, making it 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 coverage is 0%, but description explains `loan_ids` as an array of 1-50 IDs, partially compensating. No type or format details beyond schema, leaving room for 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?

Description clearly states 'Returns full loan contract detail by id' and lists specific fields, distinguishing it from sibling openfinance_list_loans by indicating deep-dive usage.

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

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

Explicitly says 'Use after openfinance_list_loans to deep-dive on a specific contract', providing sequential guidance. Lacks explicit when-not-to-use but gives clear 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 indicate read-only and idempotent. Description adds critical behavioral context: connector-dependent CREDIT balance, deduping for duplicate accounts, and potential unreliability during provider incidents. 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?

Description is appropriately front-loaded with main purpose, then adds necessary caveats. While long, every sentence contributes value; minor redundancy could be tightened.

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 4 optional parameters, description fully covers response fields, edge cases (provider incident, identity notice), and references sibling tools for further details. No gaps.

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

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

With 0% schema coverage, description compensates by explaining usage of `item` (omit vs. pass) and `item_ids` for bulk. However, `type` parameter is only implicitly described via BANK/CREDIT reference, and `item_id` not explicitly detailed.

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

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

The description clearly states the tool returns accounts for bank connections, listing specific fields (balance, type, subtype, etc.) and distinguishes from sibling tool openfinance_list_credit_card_bills by noting which tool to use for 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?

Explicitly tells when to omit `item` to list all accounts, when to pass `item` for a single bank, and warns against treating CREDIT `balance` as current bill. Provides guidance on `provider_incident` and `identity_notice` edge 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?

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. Description adds caching behavior, single aggregated response, and field details, providing context beyond annotations.

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

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

Two sentences, no fluff. Front-loaded with the main action, then details.

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

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

Complete for a parameterless tool: details field structure, language preference, and connection to another tool. No output schema needed.

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

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

No parameters; baseline 4 applies since description need not add parameter info.

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 Pluggy's transaction category taxonomy, specifies the GET endpoint, and highlights that it's cached for the session. Distinguishes itself by linking the id to openfinance_update_transaction_category.

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

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

Implies usage when category IDs are needed for updates and notes caching efficiency, but lacks explicit when-to-use or when-to-avoid guidance compared to 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, destructiveHint, idempotentHint. The description adds value by explaining that reconnect_url does not consume a slot and does not require disconnection, which is useful behavioral detail.

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

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

Two sentences, no wasted words. First sentence states purpose and outputs; second adds critical usage detail. 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?

For a zero-parameter, list-only tool with no output schema, the description adequately explains return fields and key behavior. Could mention if any default filtering applies, but overall complete enough.

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

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

No parameters exist, so the description is not required to explain them. Schema coverage is 100%, so baseline of 4 is appropriate.

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

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

The description uses a specific verb 'Returns' and names the resource 'saved bank connections', listing exact fields. It clearly distinguishes from sibling tools like openfinance_list_accounts.

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 describes when to use the reconnect_url (for re-authentication), but does not provide comprehensive guidance on when to use this tool vs. alternatives. Context is clear but lacks exclusions.

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, destructiveHint, idempotentHint. The description adds critical context about derived fields, payment_status logic, cross-bill payment matching, connector-specific limitations (e.g., open bill unavailability), and warning behavior. No contradiction with annotations.

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

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

The description is lengthy but every sentence serves a purpose given the tool's complexity. It is front-loaded with core output, then detailed caveats. Could be slightly more concise, but information density justifies length.

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

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

For a tool with no output schema and complex logic, the description fully covers return fields, derived statuses, error/warning behavior, and parameter implications. It anticipates agent confusion (e.g., payment_status derivation, connector asymmetry) and provides complete 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 description coverage is 0%, so the description carries full burden. It explains account_id (required), include_open_bill (opt-in with effects), account_ids (batch), and implies page/page_size (standard pagination). Lacks explicit details on page/page_size defaults, but adds substantial meaning overall.

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

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

The description clearly states it returns closed credit card bills with specific fields like dueDate, totalAmount, and derived payment_status. It distinguishes itself from sibling tools like openfinance_list_transactions by specifying it provides bill-level summaries, not individual transactions.

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

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

Provides extensive when-to-use and when-not-to-use guidance, including opt-in for open bill, connector asymmetry warnings, and explicit alternatives (e.g., use openfinance_list_transactions for itemized purchases). It advises against reconstructing totals from transactions and names sibling tools correctly.

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 behavior. The description adds critical detail: error handling (returns warning instead of throwing on 403), data integrity cross-checks for suspect zeroed rows, and explicit instructions to exclude those from portfolio sums. This goes 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 front-loaded with purpose and includes detailed integrity warnings. While long, each sentence adds value; however, it could be more structured with separate sections for parameters and output.

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 covers key response fields (balance, amount, etc.) and error handling. However, the lack of parameter documentation leaves gaps, especially with 0% schema coverage. The tool complexity demands more complete parameter descriptions.

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 6 parameters with 0% description coverage. The description only mentions 'item_ids' for bulk support, ignoring the other 5 parameters (item, page, type, item_id, page_size). It fails to add meaning for most 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 that the tool returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It distinguishes from sibling tools like openfinance_list_investment_transactions by focusing on positions rather than 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 implies usage for obtaining portfolio data but does not explicitly compare to alternatives or state when not to use it. It hints at bulk support via item_ids but lacks clear context for exclusion.

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. Description adds value by detailing return fields (quantity, value, netAmount, etc.) and specific expense breakdown, which goes beyond the structured annotations. No contradictions found.

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 paragraphs: first explains core functionality and return fields, second mentions bulk support. Information is front-loaded and efficient, though pagination parameters could be briefly noted.

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 adequately explains return fields and transaction types. Covers prerequisite and bulk usage. However, missing details on pagination behavior and potential error cases. Annotations cover safety profile sufficiently.

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

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

Schema description coverage is 0%, so description carries the burden. It explains investment_id (via prerequisite) and investment_ids (bulk support), but does not describe page and page_size parameters. The explanation covers half the parameters, thus partially compensates.

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?

Clear verb 'Returns' with specific resource 'movement history for a specific investment position' and enumerates transaction types (BUY/SELL/etc.) and fields. Distinguishes from siblings like openfinance_list_transactions by focusing on investments, and explicitly mentions prerequisite to use after openfinance_list_investments.

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

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

Explicitly states 'Use after openfinance_list_investments to get the investment_id', providing clear context for when to invoke. Also mentions bulk support with investment_ids. Does not explicitly list when not to use, but the context is well-defined.

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 annotations (readOnlyHint, idempotentHint, destructiveHint), description adds important behavioral details: sequential processing with rate limiting, return structure `{ results, errors }`, and the effect of omitting `items`. No contradictions.

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

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

Three sentences, front-loaded with the core purpose. Every word earns its place. Efficient and clear.

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

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

Given the tool's simplicity (1 optional parameter, no output schema, clear annotations), the description fully covers behavior, parameter semantics, and return type. No gaps.

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

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

The schema has 0% description coverage, but the description explains that `items` is an array of connection selectors (item_id, connector_id, or connector_name) and the behavior of omitting it. This adds crucial meaning not present in the raw schema.

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

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

Description clearly states 'Lists loan contracts per bank connection (GET /loans)', specifies the HTTP method and endpoint, and distinguishes from sibling tools like openfinance_get_loan_detail by indicating it lists multiple loans. The behavior with the `items` parameter is explicitly 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?

Provides explicit guidance on when to pass `items` (to list specific connections) and when to omit it (all banks). Mentions sequential querying with rate-limit spacing. Lacks explicit exclusion of alternatives, but the context is clear enough.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds extensive behavioral context: per-connector credit card behaviors, pagination mechanics (auto vs manual, 5000 ceiling, truncated flag), error returns, detail level trade-offs, account echo block, provider incident handling, and bulk support. No contradictions with annotations.

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

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

The description is long due to tool complexity, but well-structured and front-loaded. Each sentence adds value, though some detail could be condensed. Overall, it strikes a balance between completeness and 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 complexity (8 params, special behaviors, no output schema), the description covers all necessary aspects: return structure, error handling, provider incidents, cross-references to related tools, and handling edge cases. It is fully informative for AI 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?

Schema description coverage is 0%, but the description fully compensates by explaining all parameters: account_id (required), from/to (ISO dates), search_queries (substring match, OR semantics, limits), page/page_size (pagination modes), detail (enum values compact/rich/raw with trade-offs), account_ids (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 clearly states it returns transactions for a bank account (BANK or CREDIT type). It specifies the verb 'returns' and resource 'transactions'. It distinguishes from sibling tools by noting that for CREDIT accounts, this is the only way to get itemized transactions, and contrasts with openfinance_list_credit_card_bills for bill totals.

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

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

The description provides explicit guidance on when to use this tool vs alternatives. It warns not to sum transactions by billId, advising to use openfinance_list_credit_card_bills for bill totals. It explains credit card pending/posted behavior variability and when to check connection health via openfinance_get_item_status.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: truncation at 5000/account, provider_incident block affecting data completeness, and behavior of granularity/detail modes. No contradictions with annotations.

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

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

The description is structured logically: purpose, internal mechanics, parameter details, use cases, caveats. While long, every sentence adds value. Could be slightly more concise, but well-organized.

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

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

Given no output schema, the description explains return values for both granularity modes, including truncation and provider_incident indicators. It covers bulk support and filter options. Does not detail structure of by_account or por_mes, but overall sufficient for a tool with 9 parameters.

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

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

With 0% schema description coverage, the description explains most parameters (item, from, to, granularity, detail, type, item_ids, top_n is implied but not explicitly tied to top_n parameter). However, the interaction between granularity and detail is slightly confusing, and top_n parameter is not explicitly mentioned.

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: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It distinguishes from siblings by noting that it resolves accounts internally, eliminating the need for openfinance_list_accounts, and contrasts with openfinance_list_transactions by handling multiple accounts without explicit account IDs.

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 scenarios: 'análise anual/mensal', 'fluxo de caixa', etc. It explains when to omit item to analyze all banks and when to set granularity to raw. However, it does not explicitly contrast with sibling openfinance_list_transactions, though the distinction is 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details such as the return of global indicators, degraded components, open incidents, and flags for affected banks. While it provides good context, it could mention potential rate limits or update frequency to be fully transparent.

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

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

The description is well-structured and compact. It front-loads the purpose, then provides usage context, and finally lists return values. Every sentence adds value without being verbose.

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

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

Given the tool has no parameters, no output schema, and annotations cover safety, the description provides sufficient context: it explains what the tool does, when to use it, and what it returns. It also distinguishes from the sibling tool, ensuring completeness.

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

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

With zero parameters, the baseline is 4. The description does not need to add parameter semantics since there are none, and schema coverage is 100%. The description is appropriately concise for this scenario.

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, distinguishing it from the sibling tool openfinance_get_item_status which checks the user's own connection. It uses specific verbs and resources, leaving no ambiguity.

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

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

The description explicitly provides when to use the tool: when data seems incomplete or stale despite the connection showing UPDATED. It also mentions it can diagnose upstream outages. However, it could have included more explicit 'when not to use' guidance, but the context is sufficiently 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 indicate read-only and non-destructive behavior. The description adds valuable context: never dumps full catalog without keywords, returns hints, surfaces caveat warnings for non-Open-Finance connectors, and explains plan handling. 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 several sentences long but every sentence adds essential information. It front-loads the main purpose. A minor improvement could be truncating some repetitive wording, but overall efficient.

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

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

Despite no output schema, the description covers return fields, caveat behavior, plan handling, and required keyword behavior. It adequately informs the agent about the tool's outputs and edge cases, though it could briefly mention error handling.

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, so the description carries the full burden. It explains keywords[] with examples and describes include_accounts' effect on returning accounts. This adds meaning beyond the bare schema, though not extremely detailed.

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 the tool searches bank connectors by name using keywords[], and returns specific fields like connector id, access type, audience, and connect_url. It distinguishes itself by being the pre-connection search step, unlike sibling tools like openfinance_list_connections which list all 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?

Clear guidance to call this BEFORE connecting to present a one-click link. Highlights that keywords[] is required, and describes plan-based filtering. However, it does not explicitly compare to alternatives or state when not to use it, so slightly less than perfect.

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 reveals a crucial behavioral detail beyond annotations: recategorizing creates a Category Rule affecting future transactions. Annotations only indicate destructiveHint=false and no idempotentHint, so the description adds significant transparency about 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 relatively long but well-structured, front-loading the core action then providing batch behavior details. Every sentence adds value, though minor tightening could improve conciseness.

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

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

Given no output schema, the description fully documents the response format ({ updated, results, errors }) and error handling behavior. The tool has one parameter with clear structure, and the description covers all necessary context for correct invocation.

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

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

Despite 0% schema description coverage, the description thoroughly explains the 'items' parameter structure (array of objects with transaction_id and category_id) and tells the agent where to obtain these IDs from sibling tools. This adds essential semantic meaning.

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

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

The description clearly states the action 'Corrects the category' with the HTTP method and endpoint (PATCH /transactions/:id). It distinguishes from sibling tools by specifying where transaction_id and category_id come from (list_transactions, list_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 explains when to use it: to fix miscategorized transactions and improve categorization accuracy. It provides explicit sources for input values and mentions the side effect of creating a Category Rule. No explicit 'when not to use' but the context is clear.

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

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

Annotations provide idempotentHint=true, and description adds context about including conversation. However, it does not explain what happens after submission or if there are limits. The description adds moderate value beyond annotations.

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

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

Description is a single, front-loaded sentence that covers purpose and key usage instruction. 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?

For a simple tool with 3 parameters and no output schema, the description covers the core purpose and how to use it (include conversation). It is fairly complete but could mention the 'context' parameter.

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%, but the description explains the 'message' parameter implicitly and 'conversation' explicitly. 'context' is not mentioned, leaving some ambiguity. It adds some meaning but not fully compensating for lack of schema descriptions.

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

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

The description clearly states the tool's purpose: report bugs, missing features, or feedback. It distinguishes from sibling tools which are mainly openfinance or authentication related.

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

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

The description gives explicit guidance to include the conversation array for reproduction. It does not explicitly state when not to use, but the purpose is specific and no alternative tools exist for this 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 already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds specific behavioral details about what constitutes 'version' (MCP platform and adapter versions), which is beyond the annotations. No contradiction.

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

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

The description is a single sentence with no extraneous information. Every word is necessary and earns its place.

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

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

Given the tool's extreme simplicity (no parameters, no output schema, trivial behavior), the description is complete enough. However, it could optionally hint at the return format (e.g., 'returns a JSON object with version strings') but the lack is not a major gap.

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 100% (no parameters), so the baseline is 4. The description does not add parameter-level details because none exist, but it confirms the tool takes no arguments.

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

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

The description uses the specific verb 'Show' and clearly identifies the resource ('current MCP platform and adapter versions'). It is unambiguous and distinguishes itself from sibling tools, none of which are version-related.

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

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

While no explicit when/when-not guidance is given, the tool is simple and self-explanatory. The description implies its use when version information is needed. No alternatives exist among siblings, so no exclusions are necessary.

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, covering safety. The description adds useful behavioral context by specifying the exact information returned (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations. It does not contradict annotations (the tool 'returns' state, consistent with read-only).

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

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

A single, front-loaded sentence immediately states the action ('Returns') and then lists the exact content delivered. Every word earns its place, with no filler or repetition of annotation information. This is highly concise 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?

For a simple read-only state tool with no parameters and no output schema, the description is fully sufficient. It enumerates all categories of returned data (installed MCPs, connection status, accounts, catalog tool counts), giving the agent a complete mental model of what to expect. No additional explanation is necessary.

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 is empty and coverage is 100%. No parameter explanation is needed, and the baseline for zero-parameter tools is 4. The description adds no param info because there are none to describe, 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 a specific verb ('Returns') and resource ('current toolkit state'), and enumerates the exact contents: installed MCPs, connection status, accounts, and catalog tool counts. This distinguishes it from sibling tools like openfinance_list_accounts or show_version, which target specific data rather than overall toolkit state.

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 phrase 'current toolkit state' provides clear context for when to use this tool—when an agent needs an overview of what MCPs are installed, their connectivity, and associated accounts. It does not explicitly name alternatives or exclusionary conditions, but the purpose makes the usage scenario evident, distinguishing it from data-access siblings. This fits 'clear context, no exclusions.'

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