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 the annotations (readOnlyHint, idempotentHint). It discloses specific error handling: CREDIT accounts return a warning instead of throwing, upstream 5xx or non-Open Finance degrades to last-synced balance with realtime: false and a warning. It also explains the response shape. This provides excellent behavioral 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 sentences long, front-loaded with the core purpose, and each sentence adds unique value: function, parameter constraint, error handling, and response shape. There is zero wasted language and no repetition of schema or annotation 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 has only one parameter and no output schema, the description fully defines the response shape ({ results, errors }) and covers edge cases such as credit account errors and upstream degradation. It provides everything an agent needs to invoke and interpret 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?

The schema only defines account_ids as an array of strings with no description. The description compensates fully by stating 'Pass account_ids as an array (1–50)' and that the value is per account id. This adds critical constraints (size limit, semantic meaning) beyond the schema's bare type definition.

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

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

The description opens with 'Returns real-time balance payload per account id', clearly stating the verb (returns), resource (balance payload), and scope (per account id). It also includes the REST endpoint and distinguishes itself from sibling tools like openfinance_list_accounts or openfinance_get_credit_card_bill. This is 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 clear usage context: it requires an array of account_ids with a 1–50 limit, and explains how credit accounts and upstream failures behave. However, it does not explicitly mention alternative tools or when not to use this tool, though the sibling list provides implicit context. The guidance is strong but 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 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 annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description discloses crucial behavioral nuances: it does not return individual transactions, payments[] reflects the previous bill's payment, Pluggy lacks a status field, batch shape is {results, errors}, and creditCardMetadata.billId is sparse/inconsistent. No contradictions with annotations.

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

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

The description is long but each sentence adds necessary detail for a complex domain. It is front-loaded with the core function, then covers exclusions and caveats. While it could be slightly tightened, it remains efficient for 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?

Despite no output schema, the description covers return fields, batch shape, billing-cycle quirks, and cross-tool references for transactions and paid status. It is complete for its domain, addressing all likely agent confusions.

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 for the single parameter bill_ids, the description compensates fully: 'Pass bill_ids as an array — use openfinance_list_credit_card_bills first to discover ids.' This provides actionable usage context 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 states a specific verb+resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id): financeCharges and payments[]'. It clearly distinguishes from siblings by explicitly noting what it does NOT return ('Does NOT return individual transactions') and pointing to an alternative tool for that 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 given with alternatives: 'use openfinance_list_transactions...' for itemized transactions, 'use openfinance_list_credit_card_bills first to discover ids', and 'prefer openfinance_list_credit_card_bills' for paid status. This clearly states when to use this tool versus alternatives.

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

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

Annotations already 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?

Goes beyond readOnlyHint by detailing response caveats: credit balance meaning varies by connector, provider incidents can render balances unreliable, and identity_notice explains conflicting owner/taxNumber for joint accounts. Provides actionable dedupe guidance. 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?

Long but every sentence serves a purpose — field clarification, usage guidance, data caveats, bulk support. Front-loaded with core return and structured logically.

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 thoroughly covers return fields, response shape for aggregate vs single item, credit billing semantics, edge cases (incidents, identity dedupe), and bulk execution. Leaves little to the imagination.

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 parameter descriptions; the description explains `item` (single vs all) and `item_ids` (bulk), but leaves `type` and `item_id` implicit. The enum values of `type` are inferable from the main text, but not explicitly stated as a filter. Item_id is not mentioned.

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

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

Clearly states it returns accounts for a bank connection, enumerating account types (BANK/CREDIT) and fields. Distinguishes from sibling tools like openfinance_list_credit_card_bills by explaining what this tool does not do for credit 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?

Explicitly instructs when to omit or include `item` for all banks vs single bank, and directs to openfinance_list_credit_card_bills for standardized open-bill/debt amounts. Warns about connector-dependent credit balances and when to avoid presenting unreliable data during provider incidents.

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?

Although annotations already mark readOnlyHint and destructiveHint, the description adds substantial behavioral context: billId is a per-connector hint, CREDIT PENDING/POSTED varies by connector, the tool auto-paginates up to 5000 transactions, upstream errors return a safe fallback object, and provider incidents can cause incomplete or wrong data. This goes far 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 long but well-structured with logical sections (purpose, credit card caveats, pagination, detail modes, error handling, account echo, bulk support). However, the billId warning is repeated twice, and some sentences could be tightened without losing value. Front-loading is excellent; every paragraph earns its place, but minor redundancy prevents a 5.

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 (8 params, two pagination modes, per-connector variability, error fallbacks, bulk support) and the absence of an output schema, the description is remarkably complete. It covers response shape (account echo, total, results, warning, error, truncated, provider_incident), detail modes, and failure diagnosis. Nothing critical is left unexplained.

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 every parameter: from/to ISO dates, search_queries semantics (case/accent-insensitive substring, OR across terms), page/page_size modes (OMIT for auto-pagination, manual otherwise), detail enum values (compact/rich/raw), account_id, and account_ids for bulk. It adds meaning that the raw schema properties lack.

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

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

The description opens with a specific verb and resource: 'Returns transactions for a bank account (BANK or CREDIT type).' It further distinguishes itself from siblings by stating it is 'the ONLY way to get itemized transactions' for CREDIT accounts, and references sibling tools like openfinance_list_credit_card_bills for related but distinct purposes.

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

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

The description gives explicit when-to-use and when-not-to-use guidance, including 'Do NOT reconstruct a bill's total by summing transactions by billId' and directs to alternatives: 'use openfinance_list_credit_card_bills' for standardized totals, 'use openfinance_list_accounts' for closing/due dates, and 'openfinance_get_item_status' for health checks. It also explains when to use manual vs. automatic pagination.

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.