Stone Pagamentos MCP

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

The description adds behavioral context beyond annotations by explaining session vs. permanent modes and that calling with no args returns a link. It does not contradict the idempotentHint; it adds meaningful detail about the two invocation styles.

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 but somewhat long sentence with a colon, delivering purpose and usage in a compact form. It is front-loaded with the main action and avoids unnecessary fluff, though it could be split more cleanly.

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 one optional parameter and no output schema, the description covers the main usage modes and expected result (link). It lacks error handling details or response format, but for this simple auth tool it 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?

The schema only provides a bare 'token' string with no description. The description fills this gap by explaining the token is a JWT and that it can be omitted to get a link. This meaningfully 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 a user by logging in via browser and using an access token. It distinguishes itself from siblings by being the only authentication tool, and it describes the specific flow (get link, paste token) rather than being vague.

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 explicit usage guidance: the best approach (add to config for permanent connection) and an alternative (paste token for session-only login). It also explains when to call with no args to get the link, giving clear context on how to use the tool.

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

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

Annotations already declare this as read-only and non-destructive, so the description adds valuable extra context by specifying the exact conditional output: 'authenticated:true' with empty pending[] when connected, and connect_url plus per-install URLs when credentials are missing. This goes beyond the annotations without contradicting them.

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

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

The description is extremely concise: two sentences that cover the core function and the two relevant conditional outcomes. Every sentence earns its place, with no fluff or repetition of the schema or annotations.

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 status tool, the description is complete. It explains the primary output and both possible states (all connected vs. missing credentials), including what URLs are returned. No output schema exists, but the description provides the necessary return-value semantics.

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 no parameter documentation is needed. The description correctly focuses on the output and conditions, which is the only meaningful semantic content for a parameterless tool.

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 connection status and URLs.' It uses a specific verb-resource pairing and distinguishes itself from sibling tools like authenticate by focusing on status rather than initiating authentication. The conditional behavior further clarifies its scope.

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

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

The description provides clear context for when the tool is useful: to check whether providers are connected and to obtain connect URLs when credentials are missing. It does not explicitly exclude or compare against sibling tools like openfinance_list_connections, but the conditions imply when this status check is appropriate.

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 critical non-obvious behaviors beyond annotations: invoke works even when the MCP is not installed, runs one-off without bloating the tool list, returns connect/checkout links for auth/payment, and writes require owner/admin. It also clarifies installed_in_toolkit vs installed_in_workspace flags and prompt links opening without login, providing rich behavioral context not present in the annotations.

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

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

The description is information-dense and front-loaded with core purpose and flow, earning each sentence's place given the many sub-actions. However, it is a single dense wall of text that could benefit from bullet points or section breaks for easier scanning. Still, it is appropriately sized for a 23-parameter mega-tool and contains 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 dispatcher with no output schema and minimal annotations, the description is remarkably complete: it explains the end-to-end workflow, auth/paywall handling, permission requirements, one-off invocation semantics, install-vs-invoke tradeoffs, and the prompt library sub-feature. This fully addresses the tool's scope, external dependencies, and user retry flows.

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 well by explaining the main parameter roles: action's enum values (search, describe, install, invoke, etc.), mcp_id, tool_id, arguments, and prompt_* fields. However, not all 23 parameters are covered (e.g., limit, immediate, tier_slug, cancel_reason, prompt_targets, conversation), though many have intuitive defaults defined in the schema. This is a strong compensation given the tool's complexity, but leaves some 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 identifies the tool as the official mcp.ai marketplace catalog and runner, covering both MCP discovery and execution (search/describe/invoke/install) plus a prompt library. It is specific about the resource (MCPs and prompts) and the actions performed, and it distinguishes itself from sibling tools like openfinance tools by focusing on the marketplace catalog and running capability, not on bank data.

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

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

The description provides explicit usage flow: search → describe → invoke, with clear directives to prefer invoke for one-off use and install only to make an MCP permanent. It also explains when to use list_tools, subscribe/cancel, report_bug, and request_mcp, and differentiates prompt library functions. This gives strong when-to-use guidance with exclusions and 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?

The description adds behavioral context beyond the destructiveHint annotation by specifying that the connection data is deleted and data becomes unavailable. It also discloses the return of an add_connection_url, which is not indicated in annotations.

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

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

The description is two sentences with no fluff. It front-loads the core action and then provides the consequence and return value efficiently.

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 gives a good overview of the operation but is incomplete because it fails to explain the required 'item' parameter. Without parameter semantics, even with clear purpose, the model cannot reliably invoke 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 description does not mention the 'item' parameter at all. With 0% schema coverage, there is no guidance on what value to provide (e.g., bank identifier, connection ID). This is a critical omission.

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 specific action verbs ('revokes', 'deletes') and identifies the resource ('Open Finance consent for a specific bank'). It clearly distinguishes this tool from sibling tools like openfinance_list_connections by focusing on disconnection. The effect ('data will no longer be available') is also stated.

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 the usage context clear: it is used to disconnect a bank and remove its data. However, it does not explicitly mention when not to use it or point to alternative tools, so it lacks explicit exclusion 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?

The description thoroughly discloses behavior beyond annotations: it waits up to ~60s, polls until the item stops updating, returns error details, handles authentication failures via reconnect_url, and supports fire-and-forget via wait=false. It explains what statuses like needs_action and timed_out mean, providing rich context not present in the annotations.

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

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

The description is dense but well-organized, front-loading the core action and then covering usage, parameters, return values, and edge cases in a logical flow. Every sentence provides necessary information without filler, making it appropriately sized 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?

The description is fully self-contained for a complex asynchronous mutation tool. It covers return structure (results/errors), field semantics (status, executionStatus, synced), authentication failure handling, timeout behavior, and provides next-step guidance (reconnect_url, openfinance_get_item_status). No output schema exists, so the description's thorough coverage is essential 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?

Even though the schema properties lack descriptions, the tool description fully explains both parameters: items accepts various selectors (item_id, connector_id, connector_name, custom_label) and can be omitted to sync all, while wait controls whether the call blocks or returns immediately. This adds semantic meaning far beyond the bare boolean/array types in the schema.

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

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

The description clearly states the tool forces a re-sync of bank connections and waits for completion. It distinguishes itself from siblings by explicitly noting 'WITHOUT disconnecting/reconnecting' and by naming openfinance_get_item_status for follow-up status checks.

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

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

The description provides explicit when-to-use context: 'Use this when a balance or transaction list looks stale'. It also gives usage variations (sync specific items vs. all, wait vs. fire-and-forget) and references the alternative openfinance_get_item_status for timeout handling.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds extensive behavioral context: CREDIT account error behavior with structured warnings, degradation to stale balances with realtime:false when upstream fails, and the exact response envelope. This far exceeds annotation coverage.

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: it states the purpose immediately, then packs constraints, edge cases, and response shape without redundancy. Every sentence carries useful 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?

With one parameter and no output schema, the description nonetheless covers input constraints, error/degradation modes, and the response structure. It is complete for an agent to invoke the tool 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?

Schema coverage is 0%, but the description fully explains the only parameter: account_ids as an array of 1–50 strings. It adds bounds, format, and meaning, fully compensating for the schema's lack of description.

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 real-time balance payload per account id' and the HTTP endpoint. This clearly distinguishes it from sibling tools like openfinance_list_accounts or openfinance_get_accounts_detail.

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

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

The description gives explicit usage context: pass account_ids as an array (1–50). It does not explicitly name alternative tools, but the purpose is so distinct that usage intent is clear. Slight deduction for not mentioning when not to use it.

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

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

Beyond the readOnly and idempotent hints, the description discloses important behavioral details: the {results, errors} batch shape, the possible provider_incident block with unreliable data, and guidance not to present those values as real. This adds significant context about data quality and failure modes.

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 with high information density. The first sentence states the purpose, the second gives parameter guidance, and the third warns about provider incidents. No wasted words, and the most important info is front-loaded.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the return shape, potential anomaly, and parameter constraints. It is complete enough for an agent to correctly invoke the tool and interpret results, even without an output schema.

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

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

The schema has no description for the parameter, so the description fully compensates by explaining the array format and the 1–50 item constraint. It also clarifies that each ID refers to an account, making the parameter's purpose unambiguous.

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

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

The description clearly states the tool returns full account objects with extended creditData per ID, using the verb 'Returns' and specifying the resource. It distinguishes itself from siblings like openfinance_get_account_balance and openfinance_list_accounts by focusing on detailed account objects.

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

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

The description provides clear context for usage: it specifies to pass account_ids as an array (1–50) and describes the batch response shape. However, it does not explicitly mention when to prefer this over alternatives like openfinance_list_accounts, leaving the differentiation to the purpose statement.

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?

Despite annotations already indicating read-only and idempotent behavior, the description adds rich behavioral context: batch shape {results, errors}, the missing paid/status field on Pluggy, and the critical caveat that payments[] typically refers to the previous bill's payment. It also warns about unreliable billId hints across connectors, going far beyond the annotations.

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

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

Although long, every sentence adds essential information. The structure front-loads the core purpose, then covers exclusions, usage guidance, parameter handling, and caveats in logical order. No redundant or filler content—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 complex financial data tool with no output schema, the description is remarkably complete. It covers return values, batch shape, non-returned data, alternate tool usage, connector-specific inconsistencies, and how to determine paid status. Given the complexity, nothing significant is left undocumented.

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

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

Schema has zero description coverage, but the description explains the only parameter (bill_ids) thoroughly: it must be an array, should be discovered via openfinance_list_credit_card_bills, and the batch behavior. This fully compensates for the schema's lack of 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 begins with a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)'. It explicitly lists returned fields and clearly distinguishes from sibling tools by stating what it does NOT return and pointing to the correct alternative (openfinance_list_transactions).

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

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

Provides explicit when-to-use guidance: 'use openfinance_list_credit_card_bills first to discover ids' and explicit when-not-to-use: 'Does NOT return individual transactions — to get itemized credit card transactions... use openfinance_list_transactions'. Also gives contextual prerequisites like date ranges and billing cycle alignment.

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 cover readOnly, idempotent, and non-destructive hints. The description adds valuable behavioral details beyond these, such as the reconnect_url's effect of reopening the widget in UPDATE mode without disconnecting or consuming a connection slot, and the bulk execution behavior. No contradiction with annotations.

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

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

The description is front-loaded with the primary return value, then covers all-bank vs. single-bank usage and bulk support in just three sentences. Every sentence adds unique value with no filler 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 no output schema, the description outlines the return fields and explains key behaviors (reconnect, bulk, all vs. single). The missing `item_id` parameter and lack of error-handling notes are minor gaps, but the overall context is strong for a read-only tool with good annotations.

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

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

Schema coverage is 0%, so the description must compensate. It explains `item` and `item_ids` well, but completely omits `item_id`, leaving its purpose ambiguous. This is a clear gap, though the description does provide meaningful semantics for the main 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 the current status of a bank connection, listing specific fields (status, executionStatus, connector metadata, reconnect_url). It distinguishes this from sibling list tools by emphasizing status and re-authentication details, and it explicitly differentiates single vs. all-bank behavior.

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: omit `item` for all banks, pass `item` for a single bank, and use `item_ids` for bulk. It does not explicitly name alternatives or exclusion conditions, but the parameter-based usage guidance is strong enough to guide an agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond these: the batch execution model with a `{ results, errors }` shape, which implies partial failures and error handling. It also clarifies the input is an array, aligning with the batch behavior. This enriches the transparency without contradicting 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 with information: purpose, endpoint, detailed return fields, usage guidance, and batch shape. It is front-loaded with the main verb and resource, then details output. While the field list is long, it serves to clarify the complex return payload in the absence of an output schema. It is structured and not bloated.

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

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

Given the absence of an output schema, the description appropriately enumerates the key fields (interestRates, contractedFinanceCharges, balloonPayments, warranties, installments schedule, etc.). It also covers usage context and batch behavior. The sole missing element is the explicit type of each a element in `loan_ids`, but overall this is complete for a single-parameter tool with a rich response.

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

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

Schema description coverage is 0%, so the description must compensate. It explicitly names the parameter `loan_ids`, specifies its type (array), and adds a size limit (1-50). However, it does not explicitly state that each element should be a loan identifier string, though this is strongly implied by the tool name and context. This is good compensation but could be slightly more precise.

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 full loan contract detail by id.' It clearly differentiates from siblings like openfinance_list_loans (which lists all) and openfinance_get_accounts_detail by focusing on loan-specific contract detail. The mention of the REST endpoint (GET /loans/:loanId) further anchors 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?

Explicitly states 'Use after openfinance_list_loans to deep-dive on a specific contract,' providing a direct usage sequence with an alternative tool. It also specifies a batch constraint ('Pass loan_ids as an array (1-50)') and describes the response shape, giving 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 declare readOnly/idempotent/non-destructive, and the description adds substantial behavioral context: credit balance is connector-dependent, provider_incident blocks may make balances unreliable, identity_notice requires dedup by account number, and bulk execution via item_ids is supported. This far exceeds annotation coverage and prevents data misinterpretation.

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

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

The description is long but every paragraph carries a distinct, operationally relevant caveat (credit balance meaning, provider incidents, identity dedup, bulk behavior). It front-loads the core return value and then layers critical edge cases without redundancy.

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

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

Given no output schema, the description fully contextualizes the response: return fields, conditional aggregation when `item` is omitted, bank/connector naming differences, credit billing semantics, incident/notice handling, and a pointer to the alternative bills tool. This is complete for a list operation with these complexities.

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

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

Schema description coverage is 0%, so the description must compensate. It explains `item` (omit for all, pass for single) and `item_ids` (bulk), but does not explicitly describe `type` (BANK/CREDIT) or `item_id`. The `type` enum and the first sentence imply type filtering, but `item_id` is left undocumented; partial compensation only.

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

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

The description explicitly states it returns bank/credit accounts with balance, number, type, subtype, bankData, and creditData, and distinguishes itself from siblings like openfinance_list_connections and openfinance_list_transactions. It also clarifies the difference between `bank` (brand) and `name` (legal entity), adding purpose precision.

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 direct conditional guidance: omit `item` to list all linked banks when the user asks for 'my accounts/cards', pass `item` to target a single bank. It also explicitly recommends openfinance_list_credit_card_bills for standardized bill amounts, clearly separating when to use this tool vs 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 readOnlyHint=true and idempotentHint=true. The description adds that the result is cached for the adapter session and presents a single aggregated response (no batch IDs), providing useful behavioral nuance beyond the annotations.

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

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

Two tight sentences: the first states the core function and endpoint, the second lists fields and usage notes. Every sentence earns its place with no redundancy.

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

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

The tool has no parameters and no output schema, so the description carries the full burden. It covers the data shape, localization preference, caching behavior, and relationship to another tool, making it complete for its simple scope.

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

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

With zero parameters, the baseline is 4. The description doesn't need to explain parameters, but it adds value by detailing the output fields (id, description, descriptionTranslated, parentId, parentDescription), which helps the agent interpret the response.

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 Pluggy's transaction category taxonomy with the specific endpoint, distinguishing it from sibling tools like openfinance_list_transactions. It also explicitly links the returned id field to openfinance_update_transaction_category, reinforcing the 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?

The description provides usage context by stating the id is used for category updates and advises preferring descriptionTranslated for pt-BR users. It doesn't explicitly mention when not to use or alternatives, but the context is clear enough.

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

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

Annotations already set readOnlyHint=true and destructiveHint=false, so the agent knows this is safe. The description adds valuable behavioral context by explaining that reconnect_url reopens the widget in UPDATE mode, refreshes data in place, and does not consume a connection slot. This goes beyond the annotations and provides operational details without contradicting them.

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, with the first sentence front-loading the primary purpose. The second sentence is dense but delivers necessary details about reconnect_url and its constraints. It is efficient, though the second sentence could be slightly overwhelming; overall, every phrase earns its place.

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

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

Given the tool has no parameters and no output schema, the description compensates by listing returned fields and explaining the behavior of both URLs. It covers the main use case and constraints, making it sufficiently complete for an agent to understand and invoke the tool correctly. It could mention if the response is a list, but 'connections' plural implies that.

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

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

There are zero parameters, so the schema is trivially 100% covered. The baseline for no parameters is 4, and the description appropriately focuses on the output fields rather than inputs. It does not need to clarify parameters because none exist.

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 with 'Returns the saved bank connections for this install' and enumerates the specific fields returned (connector_id, item_id, bank name, reconnect_url, add_connection_url). This distinguishes it from sibling tools like openfinance_disconnect_bank or openfinance_force_sync, which have different 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 provides explicit when-to-use guidance for the reconnect_url: 'use it when a connection needs re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data).' It also clarifies that reconnecting 'does NOT consume a connection slot and does NOT require disconnecting first,' which prevents misuse. However, it does not explicitly name alternative tools for other scenarios, so it's not a full 5.

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?

Despite readOnlyHint and idempotentHint annotations, the description adds significant behavioral context: derived payment_status semantics, cycle-based payment attribution, connector asymmetry, confidence levels for fallback estimates, and warning behavior. It does not contradict annotations and enriches them substantially.

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

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

The description is extremely long but information-dense, with every sentence contributing critical caveats. It is front-loaded with the core purpose, then elaborates. However, the wall-of-text format could benefit from bullet points or section headers for easier agent parsing, so it loses one point.

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

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

Given the tool's high complexity and lack of output schema, the description covers response shape, derived fields, error handling (warning instead of failing), connector variance, payment attribution pitfalls, and practical usage. It is extraordinarily complete for an AI 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?

Schema coverage is 0%, so description carries full burden. It thoroughly explains include_open_bill with opt-in/default, derived values, fallback confidence, and connector asymmetry. It also explains account_ids for bulk support. Only page/page_size are not explicitly described, but those are standard and less critical.

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: 'Returns CLOSED credit card bills for a CREDIT-type account' and lists key fields. It explicitly distinguishes itself from sibling tools by stating results are bill-level summaries NOT individual transactions and directing to openfinance_list_transactions for itemized purchases.

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 alternatives: 'To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id' and advises using derived total_pending_debt instead of the CREDIT account balance. It also warns never to attribute one bank's bills to another, giving clear usage 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 readOnlyHint/idempotent/destructive-false, but the description adds substantial non-obvious behavior: returning {total:0, results:[], warning} on 403/upstream errors, mass-zeroing detection, transaction-history cross-checking, integrity flags, and the instruction not to treat suspect zeroed balances as real R$0. This far exceeds what annotations convey.

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

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

The description is long but structured with a front-loaded purpose, a field list, an error-behavior note, a clearly labeled DATA INTEGRITY section, and a bulk-support note. Every section adds meaningful operational context, though the length is above the minimum necessary.

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 compensates by detailing return row fields, error fallback, and data-integrity flags. However, pagination and filter parameters (page, page_size, type) are never mentioned, and the connection parameter mapping to 'item' is left implicit, leaving some gaps for a complex listing tool.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It only explains item_ids for bulk support; item, page, page_size, type, and item_id are left entirely to naming inference.

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 the investment portfolio for a connection' and enumerates the asset classes and per-row fields, giving a specific verb, resource, and scope. This clearly distinguishes it from the sibling openfinance_list_investment_transactions, which covers transaction history rather than positions.

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 states the tool is for 'a connection (broker or bank with INVESTMENTS product enabled)' and describes the intended fallback when INVESTMENTS is not enabled. It does not explicitly name alternatives like list_investment_transactions, but the 'portfolio' versus 'transactions' distinction is clear from context.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds valuable behavioral context: the exact fields returned (quantity, value, amount, netAmount, agreedRate, brokerageNumber, expenses) and the bulk execution behavior. This goes beyond the annotations without contradicting them.

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 compact sentences: the first states the purpose and output fields, the second gives a usage prerequisite, and the third covers bulk support. It is front-loaded and every sentence earns its place without unnecessary fluff.

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

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

Given the tool has 4 parameters and no output schema, the description covers the main functional aspects: return type, fields, prerequisite, and bulk mode. Pagination via page/page_size is not explicitly described, but the parameter names are self-explanatory. Overall, it provides sufficient context for an agent 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?

With 0% schema description coverage, the description must compensate. It clearly explains investment_id (via the prerequisite) and investment_ids (via bulk support), but page and page_size are not described. The description partially compensates for the schema gap but omits pagination semantics.

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

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

The description clearly states it 'Returns the movement history for a specific investment position' with a specific list of transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER). It distinguishes from siblings like openfinance_list_transactions by focusing on investment positions and explicitly referencing openfinance_list_investments.

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

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

It provides an explicit prerequisite: 'Use after openfinance_list_investments to get the investment_id.' This clearly indicates when to use the tool. Bulk support is also mentioned, giving context for investment_ids. It doesn't explicitly say when not to use alternatives, but the focus on investment transactions makes the usage context clear.

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

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

The description adds valuable behavioral details beyond the annotations: sequential querying with rate-limit spacing, per-connection return shape `{ results, errors }`, and the semantics of the `items` parameter. These are not disclosed in the annotations or schema, so they provide essential context for the agent to predict the tool's runtime behavior. No contradictions with the read-only/idempotent hints.

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

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

The description is two sentences, front-loaded with the core purpose and endpoint. It packs essential parameter semantics, behavioral notes, and return format without redundancy. Every clause adds value, making it an example of concise, well-structured documentation.

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 and one optional parameter, the description is remarkably complete: it covers parameter meaning, global vs. scoped modes, rate-limit behavior, and return structure. The complexity is low, but the description leaves no significant gap for an agent deciding to invoke this tool.

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

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

The input schema is minimal (only `items` as an array of strings, 0% description coverage), so the description carries the full burden. It thoroughly explains the parameter: what each string can be (item_id uuid, connector_id, or connector_name), one entry per connection, and the special case of omitting the parameter to fetch all. This far exceeds typical compensation.

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

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

The description clearly states the action ('Lists loan contracts per bank connection') and the resource (loans via GET /loans). It also distinguishes the tool's behavior by explaining the optional `items` parameter and the 'OMIT items' mode for all banks. However, it does not explicitly name sibling tools or provide direct differentiation, so it falls slightly 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 gives clear usage context for the `items` parameter: passing connection selectors queries specific connections, while omitting it lists all linked banks. It also warns about sequential queries with rate-limit spacing, which helps the agent plan. It does not explicitly discuss alternatives or when-not-to-use, but the guidance is sufficiently clear for a listing tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context: auto-pagination up to 5000 with truncation, manual pagination semantics, upstream error response format, provider_incident implications, credit card pending/posted variability, and per-connector billId unreliability. No contradictions with annotations exist.

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 and front-loaded with the core purpose, and it does use structured sections (pagination, detail) and clear warnings. However, it repeats the billId sparsity caution twice and could be trimmed by about 20% without losing meaning. For a tool with 8 parameters and many connector caveats, the length is mostly justified, but it is not as concise as it could be.

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 and no parameter descriptions, this description fills every gap: it explains the account echo block, result shape (total, results, truncated, warning, error), pagination totals, detail levels, and provider incidents. It also covers edge cases like zero results on a CREDIT account and how to diagnose sync failures. The tool can be invoked correctly without any external documentation.

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

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

Schema has 0% description coverage across 8 parameters, so the description must carry full burden—and it does. It explains from/to as ISO YYYY-MM-DD filters, search_queries as case/accent-insensitive substring matching with OR semantics, detail values (compact/rich/raw) with cost/benefit trade-offs, pagination parameters (omit both for auto-pagination, page_size max 500), and account_ids for bulk execution. Every parameter is meaningfully explained.

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 identifies the tool as returning transactions for BANK or CREDIT accounts, with an explicit contrast to credit card bills. It distinguishes itself from siblings like openfinance_list_credit_card_bills and openfinance_list_accounts by stating it is the ONLY way to get itemized credit card transactions. The verb 'Returns' plus resource scope is 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?

Provides explicit when-to-use guidance (itemized credit card transactions) and when-to-prefer-alternatives guidance (use openfinance_list_credit_card_bills for standardized open-bill totals and openfinance_list_accounts for statement dates). It also gives exclusions (do not sum by billId to reconstruct bill totals) and fallback actions (check openfinance_get_item_status if credit card sync fails). This is far beyond the minimum 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 declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavior: internal account resolution (no need to pass account_id), a scan cap of 5000/account with truncated flag, and a provider_incident block that can cause incomplete/wrong data. It also explains the difference between granularity:'monthly' returning a compact summary vs raw returning all rows. This goes well beyond annotations.

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

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

The description is long but well-structured: purpose, parameter details, use cases, then edge cases/limitations. It is front-loaded with the core functionality. While dense, each sentence earns its place; however, the length could be slightly trimmed without losing meaning, so it falls just short of a perfect conciseness score.

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 9 parameters with zero schema coverage, the description is exceptionally complete. It explains return fields (total entradas, saídas, por_mes, top_despesas, by_account), truncation behavior, provider incidents, and bulk support. No significant behavioral gap remains for the 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?

Schema coverage is 0%, so the description compensates fully. It explains item (connector_id, connector_name, or item_id), from/to as ISO dates, granularity (monthly/raw), detail (compact/rich/raw) with concrete enrichment details (merchantInfo, creditCardMetadata), type filter (BANK/CREDIT), top_n (largest N), and item_ids for bulk. Every parameter is semantically defined.

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

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

The description explicitly states the tool's function: consolidated cash-flow analysis for a whole bank connection, resolving accounts internally and fanning out transactions. It differentiates from siblings like openfinance_list_transactions and openfinance_list_accounts by noting that it avoids the need to call those first. The verb 'analyze' is clear and the resource scope (connection over a period) 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?

Provides explicit use cases: 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'. It also gives guidance on when to use raw granularity ('only when itemized rows are needed') and when to use detail levels (rich vs raw). It mentions that using bulk item_ids supports batched execution, indicating appropriate contexts for that feature.

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 what the tool returns: global indicator, degraded components, open incidents, and your_banks_affected. It adds context not in annotations, such as the live nature and the separation from connection status. Annotations already declare readOnly and idempotent, so the description goes beyond them, though it omits potential rate limits or external dependencies.

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 moderately detailed but each sentence adds value: purpose, usage trigger, and return details. It is front-loaded with the core function and structured logically. It could be slightly trimmed without losing meaning, but it is not unnecessarily verbose.

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

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

Given no parameters, no output schema, and rich annotations, the description fully covers what the tool does, when to use it, and what it returns. It also distinguishes from a sibling tool and explains the 'your_banks_affected' field, making it highly complete for the context.

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 schema coverage is 100% by default. The description clarifies the tool's scope and output without needing parameter explanations, which aligns with the baseline of 4 for no-parameter tools.

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

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

The description clearly states the tool 'Checks the LIVE operational status of the Open Finance provider', using a specific verb and resource. It explicitly distinguishes this from openfinance_get_item_status by contrasting provider health with connection status, which differentiates it from a directly relevant sibling.

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 it whenever data looks incomplete or stale even though a connection shows UPDATED'. It also provides an alternative by mentioning openfinance_get_item_status and explains how to differentiate provider-side problems from connection issues, offering a clear decision framework.

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 and idempotentHint annotations, the description discloses key behaviors: what happens without keywords (returns a hint), the caveat about manual reconnection, and plan-dependent visibility. This adds meaningful context not available from annotations alone.

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

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

The description is longer than a one-liner but every sentence serves a purpose (purpose, return fields, caveat, plan handling, usage timing). It's front-loaded with the main action and wraps up with a required-parameter note. Slightly dense but not redundant.

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 adequately explains the return values (connector id, access, audience, connections, connect_url). It also covers edge cases (hint when no keywords, caveat warning, plan behavior), making it self-sufficient 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?

Schema has no property descriptions, so the description carries full weight. It explains 'keywords[]' with examples and states it's required, and clarifies 'include_accounts' by noting accounts are included when true. This fully compensates for the 0% schema coverage.

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

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

The description clearly states the tool searches bank connectors by name and returns key details like id, access type, audience, and connect_url. It is distinct from siblings like 'connect' or 'list_connections' by focusing on the pre-connection search step.

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: 'Call this BEFORE connecting to hand the user a one-click link to the right bank.' It also explains plan-based filtering and the caveat about non-Open-Finance connectors, helping the agent decide when and how to use it.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses critical behavioral nuances: it overrides Pluggy's automatic categorization, creates a persistent Category Rule affecting future transactions, and explains batch error handling ('per-item errors do not fail the whole batch'). This adds substantial context that annotations alone do not provide.

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

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

The description is concise yet information-dense: three sentences covering the action, the side effect, and the batch response shape. Every sentence adds value without redundancy, and the structure flows logically from what to how to what to expect.

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

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

The tool has a single parameter and no output schema, but the description includes the full return shape ('returns { updated, results: [...], errors: [...] }'), explains input semantics, and warns about the learning side effect. This makes it self-sufficient for an agent to use correctly, covering all necessary context.

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 fully explaining the `items` parameter structure and the provenance of its fields: 'transaction_id comes from openfinance_list_transactions, category_id from openfinance_list_categories'. This gives the agent critical knowledge to invoke the tool correctly, far beyond the raw schema.

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

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

The description clearly states the tool's function: 'Corrects the category of one or more transactions' with the specific HTTP method (PATCH /transactions/:id). It identifies the resource (transactions) and the action (correcting category), distinguishing it from sibling tools like openfinance_list_transactions or openfinance_force_sync.

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

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

The description explicitly says 'use this to fix miscategorized transactions and improve categorization accuracy going forward', providing clear when-to-use context. It also explains the side effect of creating a Category Rule, which is important for deciding when to invoke. However, it does not mention alternatives or explicitly state when not to use it, so it misses the full 'when-not/alternatives' criterion.

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=false, destructiveHint=false, and idempotentHint=true. The description adds the context that recent messages should be included for reproduction, which is helpful but not a behavioral disclosure beyond annotations. It does not contradict any annotation, nor does it explain side effects or auth requirements.

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

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

The description is two sentences, front-loaded with the main action, and contains no filler. Every word earns its place, making it easy to scan and understand.

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 reporting tool, the description is adequate but incomplete. It explains the core use and the important conversation parameter, yet it omits the purpose of the 'context' parameter and does not clarify how to pass the conversation (e.g., as a JSON string). No output schema exists, so the description should have mentioned expected results or side effects, which it does not.

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

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

With 0% schema description coverage, the description must compensate for parameter meaning. It only addresses the 'conversation' parameter by asking for recent messages, but leaves 'context' and 'message' semantically underexplained. The description even calls conversation an 'array' while the schema declares it as a string, creating potential ambiguity. Message is self-explanatory, but context remains vague.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' This uses a specific verb and resource, and unmistakably distinguishes it from the financial sibling tools. It is immediately obvious when this tool should be used.

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

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

The description provides explicit context for use: reporting bugs, missing features, or sending feedback. It also instructs to include the conversation array for reproduction, which is a practical usage guideline. No alternatives or exclusions are mentioned, but none are needed given the unique role among siblings.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing a safe read-only behavior. The description adds the nuance of 'current' versions, indicating the output may change over time, which is useful beyond the annotations.

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

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

The description is a single, concise sentence that directly states the tool's function. It contains no unnecessary words or repetition, earning a perfect score for conciseness.

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

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

For a simple, parameterless version-information tool with comprehensive annotations, the description is fully adequate. It clearly conveys what information will be presented, and the lack of output schema is not a gap given the trivial nature of the response.

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 description appropriately does not attempt to describe nonexistent parameters. Per the rubric, a baseline of 4 is applied when there are no 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 uses a specific verb 'show' and resource 'MCP platform and adapter versions', clearly stating what the tool does. It distinguishes itself from siblings like toolkit_info by focusing specifically on version display.

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

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

The description implies usage when version information is needed for debugging or compatibility checks. It provides clear context without explicit exclusions, and there are no conflicting sibling tools that also fetch versions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful detail about what the returned state includes (installed MCPs, connection status, associated accounts, catalog tool counts), going beyond a generic 'returns state' statement. It does not reveal any side effects or limitations, but for a read-only info tool this is sufficient.

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 core purpose ('Returns the current toolkit state') and then lists the specific data elements. Every word contributes meaning; there is no repetition or filler.

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 no-parameter, read-only informational tool with strong annotations, the description fully conveys what the tool returns. The enumerated list of state components (installed MCPs, connection status, accounts, catalog tool counts) gives the agent a complete picture without needing an output schema.

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

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

The tool has zero parameters, and the schema is empty. The description therefore doesn't need to explain any inputs, and the baseline of 4 is appropriate because there is nothing to document.

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

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

The description uses a specific verb ('Returns') and clearly defines the resource ('current toolkit state'), enumerating its contents: installed MCPs, connection status, accounts, and catalog tool counts. This unambiguously distinguishes it from sibling tools that focus on specific financial operations or authentication.

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

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

The description provides clear context that this tool is for retrieving an overview of integrated MCPs and their status. It does not explicitly name alternatives or state when-not-to-use it, but the purpose is so distinct from the sibling tools that the appropriate usage is easily inferred.

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