Bradescard MCP

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

Annotations provide idempotentHint true, destructiveHint false. Description adds behavioral context: returns a link if no args, or logs in with token. 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?

Description is front-loaded with purpose, then details. Slightly wordy but no fluff. Every sentence adds value.

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

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

Given no output schema, description explains return behavior (link or success). Covers authentication flow adequately for the tool's moderate complexity.

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

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

Schema coverage is 0%, so description must explain parameter. It clarifies that `token` is optional: omit to get a login link, provide to authenticate with a JWT. Adds meaning beyond schema.

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

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

The description clearly states the tool's purpose: authenticating a user for MCP.AI IDE agents. It distinguishes from sibling tools (e.g., openfinance_*) by focusing on authentication mechanism.

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 usage context: two methods (permanent via config, session via token) and when to use each. Does not explicitly state when not to use, but context is sufficient.

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, idempotentHint, and destructiveHint. The description adds valuable context on how the output varies based on connection state (authenticated vs missing credentials), which goes beyond the annotation 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 two sentences, front-loaded with the main purpose, and contains no extraneous information. Every sentence contributes meaning.

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

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

Without an output schema, the description adequately explains the return values in both scenarios (connected and missing credentials). No parameters to document, so the description is complete for this 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?

There are zero parameters, and schema coverage is 100%. The description does not need to add parameter details, as none exist. Baseline of 4 is appropriate.

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

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

The description clearly states that the tool returns connection status and URLs, and explains the output for both connected and missing credentials states. It distinguishes itself from siblings like 'authenticate' and 'openfinance_list_connections' by focusing on status and URLs.

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 checking connection status but does not explicitly state when to use versus alternatives like 'openfinance_provider_status'. No exclusion criteria or when-not-to-use guidance is provided.

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

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

The description goes far beyond the minimal annotations by explaining that invoke can run non-installed MCPs, that credential/payment gaps return connect or checkout links, that install/uninstall/subscribe/cancel require workspace owner/admin, and that invoke is a one-off without toolkit bloat. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose: core flow, invoke edge cases, install vs invoke trade-offs, permission requirements, and prompt library. It is front-loaded with the main purpose and structured into readable thematic segments.

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 (15 actions, 23 params, no output schema), the description covers the most important behaviors: main flow, persistence semantics, billing/auth handling, permissions, and prompt library. Minor gaps remain, such as what 'resume' does and how 'tier_slug' or 'immediate' are used, but overall the operational context is well covered.

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

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

The description adds meaning to the action enum and highlights key parameters like tool_id, but with 23 parameters and 0% schema coverage, most parameters (limit, query, message, immediate, tier_slug, cancel_*, request_*, prompt_*) receive no direct explanation. It only partially compensates for the absent 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 identifies the tool as the official mcp.ai marketplace catalog and execution layer, and enumerates its main actions and sub-areas (search/describe/invoke, install/subscribe, prompt library). This clearly distinguishes it from the sibling openfinance_* tools, which are finance-specific.

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 decision guidance: use search→describe→invoke as the core flow, prefer invoke for one-off use, use install only to make an MCP permanent, use list_tools for current callability, and use request_mcp when nothing fits. This is strong when-to-use vs 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 already mark this as destructive (destructiveHint=true), and the description confirms that data will be deleted and no longer available. It adds value by mentioning the return of an add_connection_url for reconnection. 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 extremely concise with two sentences that efficiently convey the action, consequence, and return value. 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 one parameter, no output schema, and clear annotations, the description covers the essential behavior and result. It could be improved by clarifying the 'item' parameter, but overall it is adequately complete for selection and basic usage.

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

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

The input schema has one required parameter 'item' (string) with 0% description coverage. The description does not explain what 'item' refers to (e.g., bank ID or connection identifier). With no parameter details in the schema and no elaboration in the description, the agent lacks semantic guidance for this 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 revokes consent and deletes connection data for a specific bank. It specifies the outcome (data no longer available) and provides additional context (returns reconnection URL). This distinguishes it from sibling tools like connect or openfinance_force_sync.

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 when you want to disconnect a bank and delete its data. However, it does not provide explicit guidance on when not to use it or suggest alternatives among the many finance-related sibling tools. No exclusions or context 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?

Describes the sync behavior (PATCH, poll up to 60s), return structure, error states (needs_action, timed_out), and that it doesn't disconnect. Annotations confirm non-read-only and non-destructive, with 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 well-organized and front-loaded with key action. While slightly lengthy, every sentence adds necessary detail 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 thoroughly explains the response structure, including status fields, error handling, and reconnection URLs. Covers all essential behavioral aspects.

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

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

With 0% schema coverage, the description fully explains both parameters: 'items' as array of selectors or omit for all, and 'wait' for blocking vs fire-and-forget. No enum parameters, but explanation is 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 clearly states the tool forces a bank re-sync, waits for completion, and distinguishes from alternatives like fire-and-forget or manual reconnection. It also mentions using when data is stale, which differentiates it from sibling 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?

Explicitly says when to use ('when balance or transaction list looks stale') and provides alternatives: fire-and-forget mode (wait: false), re-check via openfinance_get_item_status on timeout, and re-authentication guidance for needs_action.

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 signal read-only, idempotent, non-destructive behavior, and the description adds substantial context beyond that: snapshot semantics tied to upstream sync, degradation behavior with realtime:false, structured warnings instead of thrown errors, and specific error scenarios.

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

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

The description is longer than average, but every sentence carries operational weight: freshness, retry guidance, error modes, degradation, and response shape. It is front-loaded with the core behavior and then layered with caveats.

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

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

Covers the return shape, error handling, degraded responses, retry logic, and account_id limits. With no output schema available, the description fully bridges the gap an agent needs to correctly invoke and interpret the result.

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 provides only type and requiredness. The description adds that account_ids must be an array of size 1–50 and clarifies they identify the accounts whose balances are returned, compensating for the 0% schema coverage.

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

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

States a specific verb (Returns) and resource (latest available balance per account id), and gives the exact endpoint. This clearly distinguishes it from sibling listing and mutation 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?

Explains when the balance may be stale, when to re-read, and explicitly directs the agent to run openfinance_force_sync before re-reading when data seems outdated or inconsistent. It also provides recovery guidance for consent errors via reconnection.

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 important behavioral context beyond annotations, such as the potential presence of a provider_incident block and the warning that credit limits/balances may be unreliable. Annotations already indicate readOnly and idempotent, so the description enhances transparency.

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

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

The description is three concise sentences: first sentence defines the core purpose, second explains the batch shape, third provides a critical reliability warning. 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?

The description covers the purpose, parameter constraints, batch shape, and a reliability caveat. While no output schema exists, the description provides enough context for safe usage, though additional detail on the account object structure could be beneficial.

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 the account_ids parameter, including array length constraints (1-50) and the batch shape. This adds meaning beyond the raw schema.

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

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

The description clearly states the tool returns full account objects including extended creditData, specifies the HTTP endpoint, and mentions the batch shape. This distinguishes it from siblings like openfinance_list_accounts, which likely returns summaries.

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 constraints on account_ids (array of 1-50) and warns about provider incidents affecting data reliability, but does not explicitly state when to use this tool versus alternatives like openfinance_list_accounts or openfinance_get_account_balance.

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 significant behavioral detail well beyond the annotations: billClosingDate defines which purchases belong to the cycle; totalAmount is authoritative and should not be rebuilt from transactions; transactions_basis can be exact only when the bank tagged the transaction, otherwise it is an estimate with low confidence; payments[] refer to the previous bill in Brazilian Open Finance; Pluggy returns no paid/status field. This gives the agent both what the tool doesn't say and how to interpret ambiguous data.

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 opening sentence is a good front-loaded summary, and every sentence is technically informative. However, the description becomes long and dense, blending alert warnings, domain notes, batch shape, and parameter semantics into a single unstructured block. Some passages, especially the alternating transactions_basis clauses, feel redundant and could confuse an agent by obfuscating the core rules.

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

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

For a tool with no output schema, the description is unusually complete: it explains the default bill-level response, the optional transaction enrichment, the reconciliation basis, the batch shape `{ results, errors }`, and the payment-status caveat. The only material gap is the underdocumented `transactions_detail` parameter and the meaning of its three enum values. Overall, the agent has enough context to call the tool correctly in most situations.

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 entire semantic burden. It provides rich meaning for bill_ids (array), account_id (required only when include_transactions is true), and include_transactions (changes the response shape, adds transactions[], transactions_count, transactions_sum, reconciles_with_total). However, it does not explain the fourth parameter, transactions_detail, with its compact/rich/raw enum, which is a meaningful gap for correct invocation of the richer transaction modes.

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 opens with the verb-resource statement: 'Returns bill-level detail for one or more credit card bills by id' and names the GET endpoint. It goes beyond a basic ID fetch by enumerating the key response fields, and clarifies that this is the detailed bill data tool rather than a list tool. It could more explicitly distinguish itself from openfinance_list_credit_card_bills, though using 'by id' and 'discover ids' already points in that direction.

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 tells the agent to discover bill IDs via openfinance_list_credit_card_bills first, and explains when to pass include_transactions and account_id. It also gives the agent an explicit alternative for pulling transactions yourself through openfinance_list_transactions and recommends openfinance_list_credit_card_bills for paid-status checks. It does not, however, state a crisp and general when-to-use versus when-not-to condition, leaving that partially to inference.

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 details beyond annotations: explains returned fields (executionStatus, connector metadata, reconnect_url), behavior for missing item, and bulk support. No contradiction with annotations (readOnlyHint, idempotentHint).

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 front-loaded main purpose. Every sentence adds value, though could be slightly more structured (e.g., bullet points for modes). Still concise 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?

No output schema, but description explains return format for both single and bulk modes. Covers essential behavior. Could mention error handling, but sufficient for a 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?

Describes 'item' and 'item_ids' well, but 'item_id' in the schema is not mentioned. With 0% schema coverage, description should cover all parameters; it partially does but misses one.

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 the status of a bank connection with specific status values. Distinguishes between single and bulk modes, and references a reconnect_url. Differentiates from sibling tools 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?

Explains when to omit item (all banks) vs pass item (single bank), and mentions bulk support with item_ids. Does not explicitly exclude scenarios, but the context is clear. Could note alternatives like 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?

Annotations (readOnlyHint, idempotentHint, destructiveHint) already indicate safe read operation. Description adds behavioral context by noting batch response shape '{ results, errors }' and enumerating returned fields (interestRates, installments, etc.), which goes beyond what annotations 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?

Single sentence packs many field names and guidance, but remains readable. Could benefit from bullet points for the field list, but it is concise with no wasted words.

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

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

With no output schema, description enumerates key returned fields (interestRates, charges, installments, dates) and input constraints (array size). Also mentions batch shape. Missing details on pagination or potential errors, but adequate 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?

Schema coverage is 0%, so description must compensate. It adds meaning by noting array size limit (1-50) and batch response shape. Though schema lists one parameter, description provides actionable constraints and error handling pattern, adding value beyond the raw schema.

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

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

Description starts with 'Returns full loan contract detail by id' and lists specific fields, clearly indicating the tool retrieves detailed loan data. It explicitly distinguishes from sibling tool openfinance_list_loans by advising to 'use after' it for deep-diving on a specific contract.

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: 'Use after openfinance_list_loans to deep-dive on a specific contract.' Also specifies input constraints ('Pass loan_ids as an array (1-50)'). Missing explicit when-not-to-use instructions, but 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?

Beyond the readOnlyHint/idempotentHint/destructiveHint annotations, the description discloses substantial behavioral nuance: connector-dependent `balance` semantics, the `balance_notice` meaning (0.00 while the issuer payload indicates an outstanding amount), lagging `bankData.closingBalance`/`automaticallyInvestedBalance` after first connection, provider_incident blocks that make balances unreliable, and identity_notice deduplication guidance for joint accounts. This is rich, actionable transparency that annotations alone could 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 prose is dense and information-rich but long, with several clauses chained inside single sentences (e.g. the `bank` explanation and the `balance_notice` sentence). Key guidance is front-loaded at the start, but the wall-of-text format makes it harder for an agent to parse quickly. It earns its place overall, but structural brevity would improve it.

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 read-only listing tool with no output schema, the description covers return fields, aggregation behavior, tricky data quality notices, and cross-tool routing. It does not explicitly describe pagination or envelope details beyond mentioning `results`, and a few parameters (`type` filtering, singular `item_id`) are only implied, so it is not perfectly complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the two central parameters (`item` versus `item_ids` for bulk) and how omitting `item` changes aggregation semantics. However, `type` is only implicitly covered by the BANK/CREDIT listing in the first sentence, and `item_id` (singular) is not explicitly explained beyond the bulk note. Still, the description adds meaning the bare schema never conveys.

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

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

The description opens with a precise verb-resource pair ('Returns accounts for a bank connection') and immediately enumerates the two account types (BANK and CREDIT) plus the returned fields. It distinguishes itself from openfinance_list_credit_card_bills and openfinance_get_accounts_detail by explaining which tool owns standardized bill amounts and closed bills.

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

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

The description gives explicit, decision-ready usage guidance: omit `item` when a user asks for 'my accounts/cards' across all linked banks, pass `item` to target a single bank, and use openfinance_list_credit_card_bills when standard open-bill amounts or total debt are needed instead of connector-dependent `balance` values. It also warns against treating `balance` as 'this month's bill' and explains when a force sync is relevant.

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 non-destructive. Description adds caching behavior and details the structure of entries (id, description, descriptionTranslated, parentId, parentDescription), providing value beyond annotations.

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

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

The description is concise, with no wasted words. It efficiently conveys purpose, structure, caching, and linkage to another tool in a few sentences.

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, no output schema, but rich annotations, the description covers caching, entry structure, and relationship to another tool. It is nearly complete, though it could explicitly state it requires no inputs.

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 properties, so schema coverage is 100%. With no parameters, the description need not add parameter info; baseline 4 is appropriate.

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

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

The description clearly states it returns Pluggy's transaction category taxonomy, cached for the session, and specifies the endpoint. It distinguishes from siblings by noting it's a single aggregated response with no batch 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 implies usage: to get category taxonomy, and links to openfinance_update_transaction_category via the id field. However, it does not explicitly state when not to use or list alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds value by explaining the reconnect_url behavior (opens widget in UPDATE mode, does not consume a connection slot) and the add_connection_url, providing useful behavioral context 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 a single well-structured paragraph that starts with the main purpose, lists returned fields, and then provides detailed usage notes for key fields. Every sentence adds value without redundancy, achieving high conciseness.

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

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

Given the tool's simplicity (no parameters, read-only, no output schema), the description comprehensively covers the tool's function, returned fields, and specific usage guidelines for reconnect_url and add_connection_url. The annotations cover safety, making the description complete for effective agent 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?

The tool has no parameters, and schema description coverage is 100%. Per guidelines, baseline is 4 for zero parameters. The description does not need to explain parameters, and it appropriately focuses on the tool's purpose and returned data.

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 saved bank connections, listing specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes itself from sibling list tools by focusing on connections rather than accounts or transactions, fulfilling the requirement for a specific verb+resource+scope.

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

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

The description provides implicit usage context by explaining the reconnect_url's purpose for re-authentication, but does not explicitly state when to use this tool over alternatives or give exclusions. The agent can infer that listing connections is appropriate for retrieving saved connections, but lacks explicit guidance on sibling tool selection.

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, and destructiveHint=false. The description adds significant behavioral context: the tool returns a warning instead of failing if CREDIT_CARDS product is not enabled, the open_bill is an extra scan, and connector asymmetry can make open_bill unavailable with reasons. 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 quite lengthy and could be more concise. While it front-loads the main purpose, it includes extensive detail that might be better structured. Some redundancy exists (e.g., multiple mentions of payment_status logic). However, every sentence provides valuable 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 complexity (5 parameters, no output schema, numerous edge cases), the description is remarkably complete. It covers return fields, payment semantics, connector differences, open_bill availability conditions, reliability warnings, and cross-tool references.

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

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

The input schema has 0% description coverage for parameters, so the description must compensate. It explains the purpose of account_id (implicitly), account_ids (bulk support), include_open_bill (detailed with effects), and implies page/page_size for pagination. This adds substantial 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 that this tool returns closed credit card bills for a CREDIT-type account, listing specific fields. It distinguishes itself from related tools like openfinance_get_credit_card_bill (singular bill) and openfinance_list_transactions (transactions vs. bills).

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

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

Extensive usage guidance is provided: when to use include_open_bill (opt-in due to extra scan), how to interpret payment_status, warnings about connector asymmetry and bill grouping reliability, and when to use openfinance_list_transactions for itemized purchases. It explicitly states what NOT to assume about payments.

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), the description adds significant behavioral context: graceful handling of 403 errors, returning a structured response with total/results/warning, and the data integrity cross-checking mechanism that flags suspect_zeroed rows. This informs the agent about important safety-limit behavior not captured in annotations.

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

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

The description is relatively long but well-structured: main purpose first, then field details, error handling, data integrity warning. It is front-loaded and each section adds value. However, some redundancy or excessive detail could be trimmed without losing meaning, so it is not maximally concise.

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

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

Given the complexity of the tool (multiple investment types, data integrity issues) and the lack of output schema, the description covers the return format, error handling, and special case handling (suspect_zeroed). It also mentions bulk support. However, it omits details about pagination (page, page_size) and filtering by type, leaving some gaps for an agent.

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

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

With 0% schema description coverage, the description must compensate. It only adds meaning for item_ids ('Bulk support: accepts item_ids for batched execution'). The other five parameters (item, page, type, item_id, page_size) are not explained. The type parameter's enum values are present in the schema but no further semantics are provided. The description fails to adequately clarify the purpose of 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 explicitly states 'Returns the investment portfolio for a connection' and lists specific asset types (FIIs, stocks, ETFs, fixed income, etc.), clearly distinguishing it from sibling tools like openfinance_list_investment_transactions which deal with transactions. The verb 'returns' and resource 'investment portfolio' 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 does not explicitly state when to use this tool versus siblings (e.g., openfinance_list_investment_transactions) or when not to use it. While it implies use when portfolio data is needed, there are no exclusion criteria or alternative recommendations. The data integrity warning provides handling guidance but not usage selection.

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. Description adds value by detailing the return data (quantity, value, expenses, etc.) and bulk execution capability, which are not in annotations.

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

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

Description is concise: two sentences in first paragraph, one in second. It front-loads the main purpose and key detail. However, the bulk support sentence could be integrated better, but no unnecessary text.

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 partially explains return fields but omits pagination parameters. It mentions bulk support. However, for a tool with 4 parameters (0% schema coverage), more detail on page/page_size would be expected. Adequate but not comprehensive.

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

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

Input schema has 0% description coverage. Description explains investment_id (from previous tool) and investment_ids (for bulk), but does not mention page and page_size parameters at all. Thus, half the parameters lack any semantic help.

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 it returns movement history for an investment position with specific transaction types (BUY/SELL/etc.) and fields. It distinguishes itself from openfinance_list_investments by advising to use that tool first to get the investment_id.

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

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

Description explicitly says 'Use after openfinance_list_investments to get the investment_id', providing a clear prerequisite. It also mentions bulk support for batched execution. However, it does not explicitly state when not to use or compare with other siblings.

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

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

Description adds behavioral context beyond annotations: it's a GET request, sequential with rate-limit spacing, returns per-connection results. Annotations already provide readOnlyHint, idempotentHint, destructiveHint. 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?

Two sentences, front-loaded with purpose, no fluff. Every sentence adds information. 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?

Given no output schema, the description explains the return value ('{ results, errors } per connection'). It also covers rate-limit behavior and the optional parameter. Complete for a 1-param 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 only parameter 'items' has 0% schema description coverage, but the description fully explains its meaning: an array of connection selectors (item_id uuid, connector_id, or connector_name), and the effect of omitting it. This adds substantial value.

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

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

The description clearly states it lists loan contracts per bank connection, specifies the HTTP endpoint, and explains the behavior when 'items' is provided vs omitted. It distinguishes itself from sibling tools like openfinance_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?

The description explains when to pass 'items' and when to omit it, and mentions sequential querying with rate-limit spacing. It doesn't explicitly point to alternatives like get_loan_detail for a single loan, 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 indicate read-only, idempotent, non-destructive behavior, and the description adds extensive behavioral transparency without contradicting those. It covers auto-pagination vs. manual pagination, the 5000-transaction ceiling, truncation behavior, per-connector credit card metadata inconsistencies, scheduled flag semantics, error responses instead of throws, and the provider_incident block. This level of disclosure is especially valuable given the complex constraints.

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

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

The description is long but exceptionally informative. It is front-loaded with the core purpose and keeps high-value behavioral guidance accessible. However, it is somewhat redundant, particularly the billId sparse/inconsistent caveat which appears multiple times, and the long paragraphs could benefit from clearer visual breakdown or bullets.

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

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

Given the absence of an output schema, the description thoroughly describes what the agent can expect: the account echo, results shape, scheduled_count, notice, warning/error returns, and provider_incident block. It also covers edge cases like multiple connected banks, per-connector differences, and the need to cross-check the account echo. While not formally exhaustive, it is highly complete for an agent to correctly invoke and interpret 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?

The input schema has 0% schema description coverage, so the description carries the full burden—and it delivers. It explains the ISO date format for from/to, the case- and accent-insensitive substring matching semantics of search_queries, the meaning of page/page_size omission vs. manual pagination, the compact/rich/raw detail levels, and bulk use of account_ids. No parameter is left 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, unambiguous statement: 'Returns transactions for a bank account (BANK or CREDIT type).' It also clearly distinguishes this tool's unique role for CREDIT accounts and differentiates it from related tools like openfinance_list_credit_card_bills. An agent can immediately understand what this tool is for and what it is not for.

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 usage guidance: use this tool when itemized credit card transactions are needed, use openfinance_list_credit_card_bills for standardized open-bill totals, and use openfinance_list_accounts for closing/due dates. It also warns about scheduled future-dated rows, pagination behavior, and when to use rich vs. compact detail. It even directs the agent to openfinance_get_item_status or openfinance_force_sync when a credit account returns zero transactions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds critical details: 5000-transaction cap per account with truncation flag, provider incident block affecting data completeness, internal account resolution and fan-out, and behavior of granularity/detail options. 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?

Description is lengthy but efficient: starts with core value proposition, then parameter details, then caveats. Some repetition (e.g., mentioning item parameter twice) could be trimmed. Overall well-structured for the complexity.

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

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

Given 9 parameters, no required fields, no output schema, the description covers all necessary aspects: parameter semantics, return structure (summary vs raw rows), limitations (cap, provider incidents), and intended use cases. Completely sufficient for an agent to use correctly.

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

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

With 0% schema coverage, description fully compensates by explaining each parameter's purpose, formats (ISO dates, enums), defaults (granularity='monthly'), and what each granularity/detail combination returns. Also clarifies item parameter accepts multiple identifier types and bulk support via item_ids.

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

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

Description clearly states it performs consolidated cash-flow analysis for a whole bank connection, resolving accounts internally. It distinguishes itself from similar tools like openfinance_list_accounts and openfinance_list_transactions by eliminating the need for separate calls and providing aggregated data.

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

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

Explicitly states when to use (e.g., monthly/annual analysis, cash flow, top expenses/revenues) and how to target one bank or all banks. Mentions bulk support. Does not explicitly contrast with sibling openfinance_list_transactions, but the context implies this is the comprehensive version.

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 behavioral details about output (global indicator, degraded components, incidents, affected banks) but no surprises or 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?

Two sentences with front-loaded purpose, usage context, and output details. No wasted words; every sentence adds value.

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

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

No output schema, but description explains return values comprehensively. Parameters absent, so nothing missing. With annotations, tool is fully documented for agent to invoke correctly.

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

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

No parameters in input schema, so description doesn't need to add parameter info. Baseline 4 for 0 params is appropriate; description doesn't attempt to add unnecessary param details.

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

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

Description clearly states it checks the provider's LIVE operational status, distinguishes from the sibling tool openfinance_get_item_status by specifying it's about the provider's health, not the connection's 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 (data incomplete/stale despite updated connection) and differentiates from the connection-specific status tool, providing clear context for appropriate invocation.

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

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

Beyond readOnly/ idempotent annotations, describes return of connect_url, plan-dependent filtering, hint on missing keywords, and caveat about credential connectors. 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?

Single dense paragraph, all sentences valuable, but could be structured with bullet points for easier parsing. Slightly verbose but not wasteful.

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 input requirements, return fields, plan behavior, caveats, and usage ordering relative to other tools. No output schema, but return values described adequately.

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 fully explained: keywords[] with example values, include_accounts with effect on returned data. Schema coverage is 0%, but description compensates completely.

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 searches bank connectors by name, returning connector ID, access type, audience, linked connections, accounts (optional), and a connect URL. It distinguishes this search from sibling tools like 'connect' and 'openfinance_list_connections'.

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

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

Explicitly instructs to call BEFORE connecting, notes that keywords are required (returns hint otherwise), explains plan behavior (PF hides PJ, PJ covers both), and advises surfacing caveats to prefer Open Finance connectors. Provides clear when-to-use and why.

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 (which only indicate non-read-only and non-destructive), the description reveals key behaviors: overriding automatic categorization, creating a Category Rule affecting future transactions, and batch error handling where per-item errors don't fail the whole batch.

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 with information (purpose, parameters, side effect, return shape) in a logical flow, but slightly wordy. It earns its length, but could be trimmed slightly.

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

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

Given no output schema, the description provides return structure. It covers side effects, prerequisites, and error behavior. All necessary context for correct invocation is present.

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 detailing the structure of 'items' as an array of objects with transaction_id and category_id, and linking them to other tool outputs. This adds essential 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 verb 'Corrects' and resource 'category of transactions', and specifies the HTTP method PATCH. It distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_categories by focusing on updating.

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 where to get transaction_id and category_id from, and explicitly states 'use this to fix miscategorized transactions'. While it doesn't list when not to use, it provides clear usage context.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds no further behavioral context beyond these annotations, but does not contradict them. With annotations present, a score of 3 is appropriate as the description does not add significant 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?

The description is extremely concise: two sentences with no wasted words. The first sentence states the purpose, the second provides a key usage tip. Front-loaded and efficient.

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

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

Given three parameters, no output schema, and no parameter descriptions, the description is incomplete. It does not explain the required 'message' parameter, the optional 'context', or the return value of the tool. The conversation tip is helpful but insufficient.

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

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

Schema description coverage is 0%. The description only mentions the 'conversation' parameter, omitting explanation for 'message' (required) and 'context'. It does not clarify the format or purpose of these parameters, leaving the agent underinformed.

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 purpose: 'Report a bug, missing feature, or send feedback.' It uses specific verbs and resources, and the tool is distinct from all sibling tools which are primarily openfinance or system utilities.

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 guidance on usage: 'Include the conversation array with recent messages for reproduction.' It implies when to use this tool (for issue reporting), but does not explicitly state when not to use it, though there are no alternative tools for this purpose.

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, covering safety. Description adds minimal additional context beyond that.

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

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

Single sentence with no waste. Perfectly concise 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 simple version tool with zero parameters and good annotations, the description is complete. Minor gap: no description of return format, but 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?

No parameters in schema, so description adds nothing, but baseline is 4 for zero-parameter 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 clearly states it shows version info, with a specific verb 'show' and resource 'version'. It distinguishes from siblings as none of the other tools are about version.

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

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

No explicit guidance on when to use or alternatives, but the tool is self-explanatory due to its simplicity. Implied usage is fine but lacks explicit 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 indicate read-only (readOnlyHint=true) and idempotent (idempotentHint=true) behavior. The description adds meaningful context about what the state includes (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations. It does not contradict the annotations, and no caveats like response format or performance are disclosed, but for a simple read-only tool this is adequate.

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

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

The description is a single, front-loaded sentence that efficiently lists the return contents without wordiness. Every phrase adds value, and the sentence structure is clear and direct.

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 (0 params, no output schema, strong annotations), the description provides sufficient information about what the response will contain. It does not specify the exact response format, but for a status tool the listed fields are likely adequate. The description is complete enough for an agent to know what to expect.

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

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

The tool takes zero parameters, and the schema coverage is trivially 100%. Per the scoring rubric, a baseline of 4 is appropriate for 0-param tools. The description adds no need for parameter clarification.

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

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

The description uses a specific verb ('Returns') and clearly specifies the resource ('current toolkit state') with detailed contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools like show_version and marketplace by focusing on comprehensive 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 description implies a usage context (checking the toolkit's operational state) but does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Sibling tools exist (e.g., show_version, marketplace) but no differential guidance is provided.

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