Toro MCP

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

The description adds behavioral context beyond annotations by explaining the difference between permanent non-expiring connections and session-only logins. It also indicates that calling with no arguments returns a link, which is useful for the agent.

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 but starts with an awkward parenthetical 'MCP.AI for IDE agents (Cursor, etc.)' that adds clutter. It could be more streamlined, though the core content is 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 tool with one parameter and no output schema, the description covers the purpose, parameter semantics, and both usage modes. It does not describe the expected response, but that is not critical for an authentication flow and the annotations provide additional constraints.

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

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

The schema has one parameter 'token' with no description, but the description explains it as a JWT for session-only login and clarifies that omitting it yields a link. This compensates for the 0% schema description coverage.

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

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

The description clearly states the tool's purpose: authenticate by logging in and obtaining an access token. It distinguishes itself from siblings by focusing on the authentication workflow, though it does not explicitly compare with 'connect' or other tools.

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

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

It provides clear guidance on when to use which method: permanent setup via config header versus session-only login by pasting a token. It also explains the behavior when called with no arguments, giving concrete usage context.

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

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

The description discloses conditional outputs—authenticated:true with empty pending[] when all connected, and connect_url when credentials are missing. This adds behavioral detail beyond the readOnlyHint and idempotentHint annotations, revealing state-dependent behavior.

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

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

The description is two sentences, front-loaded with the primary purpose, and includes necessary conditionals without any fluff. Every sentence earns its place, making it 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?

Despite lacking an output schema, the description fully explains the return values in both connection states, which is sufficient for this simple, parameterless tool. It covers the essential behavioral context needed to invoke and interpret results.

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

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

The tool has no parameters, so there is nothing for the description to add beyond the already complete schema. The baseline of 4 applies because the schema covers all (zero) parameters.

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

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

The description clearly states the tool returns connection status and URLs, with specific conditional behavior. It distinguishes itself from siblings by focusing on the overall connection state rather than individual provider operations. The verb 'returns' and resource 'connection status and URLs' 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 provides context on when different outputs occur (all connected vs. missing credentials) but does not explicitly state when to use this tool versus alternatives like authenticate or openfinance_provider_status. Usage is implied rather than explicitly guided.

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 beyond annotations by disclosing side effects: invoke runs a one-off install without bloating the toolkit, install makes permanent changes, and writes require owner/admin. It also explains what happens with credential paywalls (connect link) and payment issues (checkout link), and that prompt links open without login. These are critical behavioral traits not captured by the generic 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, starting with the core purpose and then logically flowing through the main actions, key caveats, admin requirements, and prompt library. While it is long, each sentence adds necessary context for a complex tool. Minor improvement would be breaking into bullet points, but it remains well-structured 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 the tool's complexity (14 actions, 23 parameters, no output schema), the description covers most actions and return behaviors (e.g., describe returns full profile, invoke returns connect/checkout links). However, it omits some actions like resume, and doesn't explain parameters such as immediate, conversation, or cancel_reason. These gaps make it incomplete, though far from inadequate.

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 meaning of key actions and their associated parameters. It explains how to use action, mcp_id, tool_id, and prompt-related fields (prompt_slug, prompt_vars, etc.) through the described flows. However, not all 23 parameters are individually addressed (e.g., immediate, resume, cancel_reason), so it is not a full replacement for parameter-level documentation.

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

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

The description clearly states the tool's function: it is the official mcp.ai marketplace, a catalog of MCPs/tools and a way to run them. It lists specific actions (search, describe, invoke, install, etc.) and differentiates itself from the openfinance siblings by focusing on the platform's core catalog and execution flow.

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 guidance: prefer invoke for one-off use, use install for permanent additions, and mentions that subscribe/cancel handle billing. It also gives alternative flows (list_tools for callable tools) and prerequisite conditions (writes require owner/admin), making when-to-use 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 flag destructiveHint=true, and the description adds meaningful context: it revokes consent, deletes connection data, makes data unavailable, and returns a reconnection URL. This goes beyond the annotation by specifying the exact destructive effects and the fallback mechanism, without contradicting the annotations.

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

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

Two sentences, front-loaded with the primary action, and no filler. Every clause adds value: what happens, the consequence, and the return value. It is appropriately sized for the tool's simplicity.

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

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

For a simple tool with one parameter, no output schema, and destructive behavior, the description covers the action, effects, and return value. The only gap is the lack of explicit parameter definition, but the overall context is adequate. More detail would be needed if the tool were more complex.

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

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

The schema has one parameter 'item' with no description, and schema description coverage is 0%. The description mentions 'a specific bank' but does not explicitly explain that 'item' should be the bank/connection identifier. The agent must infer this from the tool name and context, which is insufficient for correct invocation.

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

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

The description clearly states the action: 'Revokes the Open Finance consent for a specific bank and deletes the connection data.' This uses a specific verb and resource, and the effect is unambiguous. It distinguishes itself from sibling tools by being the only one focused on disconnecting/revoking access.

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

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

The description implies the use case: when you need to revoke consent and delete connection data for a bank. It notes the consequence ('data will no longer be available') and provides a recovery path ('Returns an add_connection_url to re-connect'). It does not explicitly mention alternatives, but the purpose is distinct enough 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?

The description richly details side effects and runtime behavior: polling until completion (~60s timeout), return structure with status/executionStatus/lastUpdatedAt/synced, needs_action states with reconnect_url, and timed_out semantics. It even explains the UX implication (user re-auth in UPDATE mode). Annotations are minimal (readOnly=false, destructive=false) but consistent; the description adds far more than annotations could convey.

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

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

The description is dense but every sentence earns its place. It opens with the core action, then usage, then parameters, then response format, then error states, then timeout handling. No filler or repetition; the structure flows logically from action to 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?

Given the tool's complexity (waiting, polling, re-authentication, multiple result states), the description covers all essential aspects: return shape, failure modes, timeout behavior, and relationship to sibling tools. No output schema exists, so the explicit description of results and fields is necessary and 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 the description fully explains both parameters: items as an array of selectors (item_id, connector_id, connector_name, custom_label nickname) with the option to omit for all banks, and wait as a boolean controlling synchronous vs fire-and-forget. This adds substantial meaning beyond the bare schema types.

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

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

The description opens with a specific verb+resource: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish.' It clearly states the tool's action and scope, and distinguishes it from siblings like openfinance_get_item_status (polling status) and openfinance_disconnect_bank (no disconnection involved). The mention of the HTTP method (PATCH /items/:id) further grounds its purpose.

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

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

Explicit guidance is provided: 'Use this when a balance or transaction list looks stale' and explicitly states what it does NOT do: 'WITHOUT disconnecting/reconnecting.' It also gives an alternative for timeout cases: 're-check with openfinance_get_item_status.' The wait parameter's fire-and-forget behavior is explained, making usage conditions unambiguous.

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 annotations, disclosing that updatedAt is the sync instant rather than a live read, that errors may be embedded as warnings, and that rows can degrade to last-synced balances with realtime:false. Nothing is hidden.

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 dense, front-loading the core behavior and then layering necessary caveats about freshness, errors, and degradation. Every sentence adds actionable information rather than padding.

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

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

With no output schema, the description supplies the response shape, error structure, degraded behavior, and parameter constraints. It fully equips an agent to call the tool and interpret results 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?

Although schema coverage is 0%, the description compensates by stating that account_ids must be an array with 1–50 items. It doesn't spell out where the account IDs come from, but for a single parameter this is enough to invoke correctly.

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

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

The description opens with a specific verb and resource: 'Returns the latest available balance per account id', and cites the endpoint. This clearly distinguishes the tool from list/transaction/sync siblings.

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

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

It explicitly explains the snapshot nature, tells the agent to call openfinance_force_sync if data seems stale or disagrees with openfinance_list_transactions, and describes degraded responses. This gives concrete when-to-use and when-to-use-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 the tool as read-only and idempotent, and the description adds valuable context: the {results, errors} batch shape, the provider_incident block, and a warning about unreliable credit limits/balances during an open provider incident, with explicit instruction not to present those values as real. This goes beyond annotations and significantly helps the agent handle edge cases.

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 with the main purpose first, then usage, then batch shape, then the incident caveat. Every sentence adds value, but the last sentence on provider_incident is a bit long with a potentially confusing example ('limit near 1,00'). It's still concise overall.

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 covers the return shape, batch behavior, and important data reliability caveats. It provides enough for the agent to use the tool correctly and interpret results safely, leaving no major 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?

Schema has no descriptions (0% coverage), but the description directly explains the only parameter: account_ids is an array, accepts 1–50 items, and is used per id. It also clarifies the batch result shape. This compensates well for the missing schema descriptions, though it doesn't go into exhaustive detail about array item formatting or edge cases.

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 full account objects including extended creditData, which is specific and differentiates from simpler listing/balance tools. It references the endpoint and scopes by id, but doesn't explicitly name sibling tools to distinguish, so it falls short of a 5.

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

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

The description indicates how to pass account_ids (array of 1-50) and mentions batch behavior, implying use for detailed account retrieval. However, it doesn't explicitly state when to use this tool versus alternatives like openfinance_get_account_balance or openfinance_list_accounts, nor does it exclude any use cases.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description discloses extensive behavioral details: the transactions_basis field with three possible values and their implications, the authoritative totalAmount (don't sum transactions), the cost of the opt-in, and the subtle fact that payments[] typically refers to the previous bill's payment. It also notes Pluggy does not return a paid/status field. This goes far 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?

The description is very long, but it is structured with bolded section headers (e.g., 'ITEMIZED PURCHASES (OPT-IN)') and uses inline code formatting for clarity. It front-loads the core purpose in the first sentence. However, it is far from concise; each sentence carries critical caveats, but the sheer volume may overwhelm an agent. The structure helps but is not enough to overcome the 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 0% schema coverage and no output schema, the description is remarkably complete. It explains the response batch shape, the transactions basis logic, the need for account_id, the alternative to opt-in, and the paid-status caveat. It even provides query hints (using billClosingDate as range end). There is no obvious missing information that an agent needs to call it correctly.

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

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

The schema has no descriptions (0% coverage), so the description must compensate. It explains bill_ids (array, discover via list), account_id (needed for include_transactions), and include_transactions (opt-in for transactions). However, it completely omits the 'transactions_detail' parameter with its enum values (compact, rich, raw), leaving that parameter's semantics unexplained. This is a gap given the zero 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?

The description clearly states the tool returns bill-level detail for credit card bills via a specific endpoint (GET /bills/:id), listing exact fields. It distinguishes itself from sibling tools by explicitly mentioning openfinance_list_credit_card_bills for discovery and openfinance_list_transactions for self-fetching transactions, so an agent knows exactly what this tool does and what it doesn't.

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: use the opt-in for transactions only when needed, and notes it costs an extra scan; it says to use openfinance_list_credit_card_bills first to get ids; it also advises against assuming paid status from payments[] and recommends the listing tool for payment_status. This clearly differentiates from alternatives and provides 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 readOnly, idempotent, and non-destructive. The description adds meaningful behavioral context: reconnect_url reopens the widget in UPDATE mode without disconnecting or consuming a connection slot, and returns various status values. This exceeds what annotations provide, though it does not cover all edge cases.

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 with the main behavior, then usage patterns, then bulk support. Every sentence adds useful information without redundancy. It is appropriately concise given the tool's complexity.

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

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

The description covers the main return values (status, executionStatus, connector metadata, reconnect_url) and the bulk response shape. It lacks details on `item_id` semantics and any error conditions, but is otherwise complete for a read-only tool with no output schema.

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

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

Schema coverage is 0%, so description must compensate. It explains `item` (single bank) and `item_ids` (batch), but does not explain `item_id` or its relationship to `item`. This is a partial gap in parameter 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 it returns the current status of a bank connection, including specific fields like executionStatus, connector metadata, and reconnect_url. It distinguishes from sibling tools by describing a unique resource and operation, and mentions bulk support via item_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?

Provides clear context on when to omit or pass `item` for single vs. all banks, and mentions bulk support. However, it does not explicitly compare with alternatives like openfinance_list_connections or openfinance_provider_status, so no exclusions or when-not-to-use 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 indicate a safe read operation (readOnlyHint, idempotentHint, non-destructive). The description adds behavioral context by listing the response fields, the batch shape '{ results, errors }', and the endpoint path, which goes beyond annotation information.

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, information-dense sentence that front-loads the purpose, then uses a colon to enumerate return contents, includes usage guidance, parameter constraints, and batch shape—all without any redundant words.

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

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

Given the tool has only one parameter and no output schema, the description thoroughly covers the return values, usage context, and parameter constraints. It is self-sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 0% for the only parameter, but the description compensates fully by explaining 'loan_ids' as an array with 1-50 items and implying they are loan IDs obtained from the list tool. This gives the agent complete understanding of the 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's function: 'Returns full loan contract detail by id' with a specific verb and resource. It also differentiates from the sibling openfinance_list_loans by indicating this is for a deep-dive 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 usage guidance: 'Use after openfinance_list_loans to deep-dive on a specific contract.' It also specifies the parameter format ('Pass loan_ids as an array (1-50)'). However, it does not mention any when-not-to-use scenarios or alternatives among the many sibling tools.

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

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

Annotations already mark this as read-only and idempotent, but the description goes far beyond that by explaining connector-dependent balance meanings, balance_notice, stale bankData fields, provider_incident unreliable data, and identity_notice duplicates. These are precisely the behavioral caveats an agent needs to avoid misinforming users. No contradiction with annotations exists.

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

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

The description is long but front-loaded with the core return value and bank/brand distinction before diving into caveats. Every major paragraph covers a distinct, decision-relevant edge case, though a little trimming could make the critical flow from normal usage to cautionary notes even clearer.

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

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

Given there is no output schema, the description does an excellent job of covering response fields, root vs. aggregate shapes, edge cases, and alternative-tool routing. It also warns against common misinterpretations such as treating CREDIT balance as the current bill or presenting stale provider-reported values as real. This is as complete as an agent needs to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description carries the full burden. It explains `item` omission vs. presence and the bulk `item_ids` behavior very well. However, the singular `item_id` parameter is not explicitly differentiated from `item`, and `type` is only implicitly covered through the BANK/CREDIT discussion rather than as a filter 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?

States clearly that it returns bank and credit accounts with their balances, types, and associated banking metadata. It also distinguishes itself from sibling tools by naming openfinance_list_credit_card_bills and explaining how it differs from that tool. The description makes the tool's scope immediately actionable.

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

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

Provides explicit when-to-use guidance: omit `item` to list all banks, pass `item` to target a single bank, and use item_ids for bulk execution. It also tells the agent when NOT to use this tool's CREDIT balance and instead call openfinance_list_credit_card_bills for standardized bill data. This is exceptional routing 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds valuable behavioral traits: caching for the adapter session, the exact response fields including `descriptionTranslated` with a language preference, and the lack of batch ids. This exceeds annotation coverage, so a high score is warranted.

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

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

The description is three sentences, front-loaded with the main purpose, then detailing entry fields, and ending with a note about the response format. No redundant or vague language; every sentence contributes.

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 present, the description compensates by fully disclosing the response structure (each entry's fields), the caching behavior, and the cross-link to the update tool. For a low-complexity read-only tool with no parameters, this is complete.

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

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

The tool has zero parameters, and the input schema is empty. With no parameters to explain, the description appropriately omits parameter details, and the baseline for zero-parameter tools is 4.

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

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

The description uses the specific verb 'Returns' and identifies the exact resource: Pluggy's transaction category taxonomy, with the endpoint GET /categories. It distinguishes itself from sibling tools by detailing the field structure and linking to openfinance_update_transaction_category, making its unique purpose clear.

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

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

The description provides clear context: it is cached for the adapter session, implying no real-time data, and it explicitly references openfinance_update_transaction_category for which the returned `id` serves as categoryId. However, it does not explicitly state 'use this when...' or mention when not to use, so it lacks explicit 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 this as a safe read (readOnlyHint=true, destructiveHint=false). The description adds valuable behavioral context beyond annotations: the widget opens in UPDATE mode, data refreshes in place, and reconnect does not consume 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 three sentences, front-loaded with the primary function, followed by concise yet informative details about the URLs. Every sentence earns its place with no fluff or repetition.

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

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

Despite having no output schema, the description sufficiently explains the return fields and the conditions for using the included URLs. It covers the tool's purpose, usage, and edge cases, making it fully adequate for an agent to select and 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?

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameter semantics; instead it clarifies the return payload, which is more relevant. No parameter documentation is required.

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

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

The description clearly states the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url), making it distinct from sibling tools that handle accounts, transactions, or disconnection. The verb 'Returns' is specific and the resource is well-defined.

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

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

The description explicitly explains when to use the reconnect_url (re-authentication for MFA connectors, LOGIN_ERROR, stale non-Open-Finance data) and what add_connection_url is for, providing clear context and distinguishing between use cases. It also advises that reconnect does not consume a connection slot or require disconnecting first.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the absence of a paid/status field, explains the non-obvious payment cycle semantics, introduces the derived payment_status and PAST_DUE_UNCONFIRMED case, and covers connector asymmetry, opt-in open_bill, and reliability warnings. This is extensive context 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?

The description is long but information-dense, with clear paragraph breaks and a front-loaded core purpose. Some redundancy exists but nearly every sentence carries operational importance, though the length may be slightly overwhelming.

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 high complexity, the description defines the response structure, derived fields, payment_status legend, account echo, warnings, and failure behavior. It is sufficiently complete for an agent to invoke correctly and interpret results.

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

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

With 0% schema description coverage, the description compensates by explaining include_open_bill's default/meaning, bulk account_ids support, and the required account_id. However, page and page_size are not described, leaving pagination semantics assumed.

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

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

The description opens with 'Returns CLOSED credit card bills for a CREDIT-type account', immediately specifying the verb, resource, and scope. It enumerates the returned fields and later clarifies these are bill-level summaries, not transactions, which distinguishes it from transaction-list siblings.

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

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

The description explicitly directs users to openfinance_list_transactions for itemized charges and warns against using the CREDIT balance for total debt, recommending derived open_bill/total_pending_debt instead. It also notes when the tool returns a warning instead of failing, providing clear operational 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 indicate read-only/idempotent, but the description adds substantial behavior: it returns { total:0, results:[], warning } instead of throwing, performs cross-checks for mass zeroing, and flags suspect_zeroed rows with instructions to treat them as unavailable. This goes well beyond the annotations and provides crucial guidance.

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: a concise opening statement of purpose, a detailed data-integrity section, and a note on bulk support. It is longer than average but the complexity of the tool warrants the detail; no fluff.

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

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

For a complex tool with no output schema, the description covers return fields, error handling, and data-integrity warnings comprehensively. It omits pagination/filter behavior details, but overall it is complete enough for correct 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?

Schema description coverage is 0%, so the description must explain parameters. It only mentions item_ids for bulk execution; other parameters (item, page, type, item_id, page_size) are left undefined or only inferable from context, which is insufficient.

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

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

The description clearly states the tool returns the investment portfolio for a connection, enumerating asset types (FIIs, stocks, ETFs, etc.) and fields. This distinguishes it from sibling tools like openfinance_list_investment_transactions and 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?

The description says it applies to connections with the INVESTMENTS product enabled and explains the fallback when that product isn't available. It does not explicitly name alternatives or state 'use this instead of X', but the scope is clear enough for most use cases.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations by noting bulk execution support ('accepts investment_ids for batched execution') and describing the return fields (agreedRate, brokerageNumber, itemized expenses). 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 two short paragraphs. The first sentence states purpose and scope, followed by return detail and prerequisite usage. Every sentence adds value, with no redundancy or fluff.

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

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

Given there is no output schema, the description compensates by listing key return fields and transaction types. It also covers the main usage flow and bulk option. It lacks details like pagination defaults or error scenarios, but for a read-only list tool, this is reasonably complete.

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

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

Schema has 0% description coverage, so the description must compensate. It does so by explaining that investment_id comes from openfinance_list_investments and that investment_ids enables bulk execution. It doesn't elaborate on page/page_size, but these are standard pagination parameters with self-explanatory names.

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: 'Returns the movement history for a specific investment position' and enumerates transaction types (BUY/SELL/TAX/etc.). It distinguishes from siblings by emphasizing the investment-specific scope and listing return fields, making it unambiguous.

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

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

The description explicitly instructs to 'Use after openfinance_list_investments to get the investment_id', providing a clear prerequisite and chaining context. It does not explicitly contrast with alternative tools like openfinance_list_transactions, but the investment-specific scope is evident, and bulk support is mentioned.

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

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

Adds significant behavioral context beyond annotations: multiple connections are queried sequentially with rate-limit spacing, and the return structure is `{ results, errors }` per connection. This informs the agent about performance and error handling.

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, each earning its place: the first states the core function, the second explains parameter usage, and the third covers the alternative mode. No filler or redundancy.

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

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

With only one optional parameter and no output schema, the description covers all needed aspects: both usage modes, return shape, and per-connection behavior. The agent can invoke and interpret results correctly without additional information.

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 only shows `items` as a string array with no description. The description fully compensates by explaining valid selector types (item_id uuid, connector_id, or connector_name), the one-entry-per-connection rule, and the omitting behavior, providing 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?

Clearly states 'Lists loan contracts per bank connection' with a specific verb and resource. The description also distinguishes between listing for specific connections and all banks, making the scope explicit and differentiating 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?

Provides clear usage context: pass `items` for specific connections or omit for all linked banks. However, it does not explicitly mention alternative tools or when not to use this tool, so it lacks explicit 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 only declare readOnlyHint/idempotentHint and non-destructive behavior, so the description carries the real burden. It discloses many non-obvious behaviors: auto-pagination, 5000-row ceiling, descending future-dated scheduled rows, per-connector PENDING/POSTED variation, sparse billId hints, error return shape, account echo block, provider_incident block, and detail mode response differences. No contradiction with annotations exists.

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 very organized with clear paragraphs on pending, scheduled, rows, pagination, detail, and account echo. However, it is long and slightly repetitive: the 5000 truncation guidance appears twice, and the billId minimization is repeated in both the credit-card section and the rich-detail section. The length is largely justified by a high-complexity tool, but has room for refinement.

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

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

There is no output schema, so the description must assume an enormous explanatory burden. It covers request filters, pagination and truncation, row-level detail modes, credit card metadata semantics, zero-result diagnostics, multi-bank attribution, provider incidents, and related tool usage. For a tool this complex, the documentation is effectively 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 all parameter meaning must come from the description. It thoroughly explains from/to format, search_queries term and OR-substring semantics, page/page_size manual mode vs auto-pagination behavior, detail enum values, and the controlling requirement to cross-check the account echo. Even account_ids is reasonably covered by the account ownership guidance.

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 statement: 'Returns transactions for a bank account (BANK or CREDIT type)' and explicitly distinguishes this tool as the ONLY way to get itemized credit card transactions. It also names sibling tools like openfinance_list_credit_card_bills and openfinance_list_accounts to clarify scope boundaries.

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 text gives explicit when-to-use vs alternatives guidance: use this for itemized transactions, but openfinance_list_credit_card_bills for standardized open-bill totals; use openfinance_list_accounts for closing/due dates; check openfinance_get_item_status when a CREDIT account returns 0. It also explains when to pass `to=today`, when to use manual pagination, and how to react to `truncated:true`.

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=false), the description discloses critical behavioral traits: the 5000/account scan cap with truncated flag, the provider_incident block and its implications on data completeness, and the difference between compact monthly summary and raw granularity. It also explains the default behavior and enrichment options.

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?

Although long, every sentence earns its place by adding operational detail, defaults, caveats, and usage examples. The text is front-loaded with the main purpose, then logically flows through parameters, granularity, and edge cases. It avoids repetition and is structured for quick scanning.

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

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

With no output schema, the description fully explains return values: total entradas/saídas/saldo_liquido, monthly evolution (`por_mes`), top receipts/expenses, per-account breakdown, optional raw rows, and the `truncated` and `provider_incident` flags. It also covers connection-level behavior and bulk execution, making the tool's full behavior understandable.

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 full burden for parameter meaning. It explains `item` as connector_id/name/item_id, `from`/`to` as ISO dates, `granularity` and `detail` enums with concrete values, `type` filtering, and bulk support via `item_ids`. It also implies `top_n` via 'largest N each' and covers all key 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 states a specific verb and resource: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It clearly distinguishes itself from siblings by noting you do not need to call openfinance_list_accounts first and that it resolves accounts internally, which differentiates it from openfinance_list_transactions and other item-specific tools.

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

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

Explicit guidance is provided: use for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos', and it tells when to use the raw granularity ('only when itemized rows are needed'). It also contrasts with the alternative of calling openfinance_list_accounts first, making the decision clear.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds context about the live public status page and the specific outputs (global indicator, incidents, your_banks_affected), which is useful beyond 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?

Every sentence earns its place: it states the action, distinguishes from a sibling, explains when to use it, and lists output fields. The description is dense but not bloated, and it is front-loaded with the primary purpose.

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

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

With no output schema, the description fully explains what is returned (global indicator, degraded components, incidents, your_banks_affected) and provides enough context for an agent to understand the operational meaning. It is complete for a simple read-only tool.

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

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

The tool has zero parameters, so the description correctly implies a no-input read operation. The schema provides 100% coverage trivially, and the description adds no parameter info because none is needed.

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

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

The description clearly states the tool 'Checks the LIVE operational status of the Open Finance provider' and explicitly differentiates it from the sibling tool `openfinance_get_item_status`, making the resource and scope unmistakable.

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

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

It gives explicit when-to-use guidance ('Use it whenever data looks incomplete or stale even though a connection shows UPDATED') and names the alternative (openfinance_get_item_status), helping the agent choose correctly between provider-side and connection-side diagnostics.

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

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

Annotations already declare readOnly/idempotent, and the description adds substantial behavioral context: caveat warnings for non-Open-Finance connectors, plan-based filtering (PF vs PJ), the requirement for keywords with a hint fallback, and that it never returns the full catalog. These go beyond what annotations provide and are critical for correct use.

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

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

The description is a single dense paragraph but every sentence carries unique information. It is front-loaded with the core purpose and return details, followed by caveats and usage instructions. Slightly long but not wasteful; the structure could be improved with breaks, yet each clause 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?

For a two-parameter tool with no output schema, the description covers all essential aspects: what it returns (id, access, audience, connections, connect_url), edge cases (caveat, plan restrictions, missing keywords), and how to invoke it. It is self-contained and leaves no major gaps for an agent to determine correct 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 coverage is 0%, but the description fully explains both parameters: keywords[] with an example ('nubank','btg') and requiredness, and include_accounts with the effect 'returns accounts when true'. It also clarifies the keyword requirement's behavioral consequence (returns a hint if absent), adding meaning the schema lacks.

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

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

The description clearly states the tool's function: 'Searches the available bank connectors by name' and lists specific return fields (connector id, access, audience, connections, connect_url). It distinguishes from sibling tools like 'connect' by positioning it as a pre-connect search step, and from 'marketplace' by explicitly noting it never dumps the whole catalog.

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 directs when to use the tool: 'Call this BEFORE connecting to hand the user a one-click link to the right bank.' It also provides contextual guidance on caveats and plan behavior. It does not explicitly name alternative tools for other scenarios, but the 'before connecting' instruction and search-filtered nature give strong 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?

Beyond annotations (readOnlyHint=false), the description discloses a non-obvious side effect: recategorizing creates a Category Rule that affects future transactions. It also explains batch error semantics ('per-item errors do not fail the whole batch') and the override of Pluggy's automatic categorization.

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

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

The description is dense but every sentence carries value: endpoint, parameter structure, side effects, return shape. It is front-loaded with the core action. Slightly long, but justified by the multiplicity of important 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?

Given no output schema and sparse annotations, the description covers all necessary context: purpose, parameters, side effects, return shape with nested fields, and error handling. It is fully self-contained for an agent to invoke correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining the `items` array shape, the exact fields ({ transaction_id, category_id }), and where each ID comes from. 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 opens with a specific verb+resource: 'Corrects the category of one or more transactions (PATCH /transactions/:id)', immediately distinguishing it from sibling list/read tools. It states the operation clearly and unambiguously.

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 tells the agent when to use it ('to fix miscategorized transactions and improve categorization accuracy going forward') and references sibling tools for required IDs (openfinance_list_transactions, openfinance_list_categories). It doesn't explicitly mention when not to use it, 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 basic safety hints (idempotent, non-destructive), and the description adds useful behavioral context by instructing to include the conversation array for reproduction. It does not contradict the annotations. The description could disclose what happens after submission (e.g., ticket creation), but with annotations covering the safety profile, this is acceptable.

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 short sentences with no fluff. The most important instruction (include conversation) is front-loaded and easy to parse. Every word 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?

For a simple 3-parameter tool with no output schema, the description adequately covers the tool's purpose and the main usage nuance (including conversation). It does not explain the 'context' parameter, but the overall complexity is low, so the description is reasonably complete. Slightly more detail on the expected response would improve it.

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. It explains the 'conversation' parameter's purpose but does not clarify the 'context' parameter or provide details about the 'message' parameter beyond its role in reporting. This partially compensates for the missing schema descriptions but leaves gaps.

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 uses the verb 'Report' with explicit targets (bug, missing feature, feedback). It distinguishes itself from all sibling tools, which focus on OpenFinance data operations. No ambiguity about what the tool does.

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

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

The description implies when to use this tool (whenever a bug, feature request, or feedback is needed) and gives a specific instruction to include the conversation array. It does not explicitly mention alternatives or exclusions, but no competing sibling tool exists for reporting, so 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond the word 'current', but there are no side effects or complex behaviors to disclose for a zero-parameter read-only version tool.

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

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

The description is a single, concise sentence that directly states the tool's function without any filler or redundancy. It is front-loaded and easily scannable.

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

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

For a zero-parameter, read-only version query tool, this description is fully complete. It clearly communicates what versions are shown ('MCP platform and adapter'), and there is no output schema to elaborate on. No additional context seems necessary given the trivial nature of the tool.

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

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

The tool has zero parameters, so the schema fully covers parameter semantics (vacuously). The description adds no parameter-specific information, but none is needed. Baseline 4 applies per the rubric for 0-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 'Show the current MCP platform and adapter versions' clearly specifies a verb ('Show') and a concrete resource ('current MCP platform and adapter versions'). However, it does not explicitly distinguish this tool from sibling tools like 'toolkit_info', which might also provide version-related information.

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

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

The tool is self-explanatory for checking versions, so usage is implied. However, there is no explicit statement about when to use this versus alternatives, no exclusions, and no mention of prerequisites or context like requiring authentication.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat safety traits. It adds value by enumerating exactly what the returned state includes (installed MCPs, connection status, accounts, catalog tool counts), which is useful beyond the schema.

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 sentence that front-loads the action ('Returns') and packs all key return elements into a tidy list. 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 tool with no parameters and no output schema, this description fully explains what the tool returns and covers the essential aspects of toolkit state. The listed items are comprehensive and leave no major ambiguity.

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

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

The tool has zero parameters, and the schema has no properties. Per the rubric, a zero-parameter tool gets a baseline of 4, and the description correctly avoids inventing parameter details.

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

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

The description clearly states that the tool returns the current toolkit state, listing specific components (installed MCPs, connection status, accounts, catalog tool counts). This is a specific verb-resource pairing that distinguishes it from sibling tools focused on finance operations.

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

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

The description makes it clear this tool is for retrieving toolkit state, which provides clear context for when to use it. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.

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