Santander MCP

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds context about token storage (permanent config vs. session-only) and the two auth modes, but doesn't disclose potential side effects, failure modes, or return values. With annotations covering the safety profile, the added transparency is adequate but not rich.

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 paragraph of three sentences, covering both modes and configuration in a compact format. It is slightly wordy with parentheticals ('MCP.AI for IDE agents (Cursor, etc.)') but front-loads the login purpose and avoids 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?

For a simple auth tool with one optional param, no output schema, and no nested objects, the description covers the main usage scenarios, the meaning of the token, and the no-arg behavior. It lacks explicit return-value details, but the tool's purpose and invocation are sufficiently described.

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

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

The input schema has 0% description coverage for the sole 'token' parameter. The description compensates by defining it as a 'JWT' pasted from the browser and showing the exact call syntax { token: '<jwt>' }. It does not cover format validation or other constraints, but the core meaning is clear.

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 handles authentication for IDE agents: 'log in in the browser, copy the access token.' It explains the token-based flow and the two usage modes (permanent vs. session), but does not explicitly differentiate it from sibling tools like 'connect'.

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 specific invocation guidance: call with no args to get the login link, or call with { token: '<jwt>' } after the user pastes a token. It also describes the preferred approach (config header) vs. session-only login, though it doesn't mention alternative tools or when not to use this tool.

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

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

Annotations already mark this as read-only and idempotent. The description adds value by detailing the conditional return payload: authenticated:true with empty pending[] when all connected, and connect_url plus per-install URLs when credentials are missing. This explains behavior beyond the annotation flags.

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 every clause adds necessary information about the conditional responses. No waste.

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 tool with no output schema, the description fully covers the possible return states (connected vs missing credentials) and the key fields (authenticated, pending, connect_url). This is sufficient for an agent to understand what the tool returns.

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 100% coverage. Per the baseline for zero-parameter tools, the description is not required to add parameter details, and it doesn't, so it's fully sufficient.

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 identifies the resource as 'connection status and URLs.' It also differentiates from sibling tools like 'authenticate' by focusing on status rather than performing authentication, and from 'openfinance_list_connections' by providing status/URLs rather than a detailed list.

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

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

The description implies this tool is for checking connection state, and contrasts scenarios (all connected vs missing credentials). However, it does not explicitly state when not to use it or name alternative tools, so it lacks explicit exclusions but provides clear context.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: invoke runs a tool one-off without adding it to the toolkit, returns a connect link if a credential is needed, returns a checkout/top-up link if the wallet is empty, and writes require workspace owner/admin. This is far richer than the annotations alone and sets clear expectations for side effects and retry logic.

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 nearly every sentence adds distinct information: core flow, invoke vs. install trade-offs, auth/billing behavior, permissions, and the prompt library. It is long but justified by the tool's complexity. Minor deduction for at least one rambling sentence (the one starting 'KEY: invoke works even...') that could be split for readability.

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 (23 params, no output schema, sparse annotations), the description is remarkably complete. It explains the end-to-end workflow, edge cases (credentials, empty wallet), permission model, and even the prompt library sub-interface. An agent would have enough context to select the right action and parameters for most scenarios, including how to handle connect/checkout links and retries.

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 23 parameters and 0% schema description coverage, the description must compensate. It adds semantic meaning to the most important parameters via the core flow (e.g., action, tool_id, arguments) and names the prompt-related actions (search_prompts, get_prompt, publish_prompt). However, many parameters like prompt_body, cancel_reason, and request_details are not individually explained, so the description only partially covers the parameter space.

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 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' clearly defining the tool's function and scope. It distinguishes this from sibling tools (e.g., openfinance_*) by focusing on the marketplace and MCP execution rather than a specific domain.

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 an explicit core flow ('action=search ... → describe ... → invoke RUNS that tool'), explains when to prefer invoke over install ('prefer invoke for a single/occasional use'), and notes additional use cases like 'search_prompts finds one, get_prompt returns its full text'. It also mentions permission requirements for writes, giving clear when-to and when-not-to 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 destructiveHint=true, but the description adds specific details: it deletes connection data and makes data unavailable. It also discloses the return of an add_connection_url, which is not in annotations. This provides valuable behavioral context beyond the structured 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 three sentences, each providing essential info: action, consequence, and return value. No unnecessary words.

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

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

The description covers the core purpose and effects, but lacks clarity on the 'item' parameter, which is the only input. For a destructive tool, an agent needs to know how to specify the bank, and this is not addressed. The return URL is mentioned but no error conditions are described.

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 provides only 'item' as a string with no description (0% coverage). The description mentions 'for a specific bank' but does not explicitly define the 'item' parameter as the bank identifier or explain its format or source. The tool description fails to compensate for the lack of schema 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 revokes Open Finance consent for a specific bank and deletes connection data, distinguishing it from sibling tools that list or sync connections. The effect is explicitly stated: 'The bank's data will no longer be available.'

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

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

The description implies usage for disconnecting a bank but does not provide explicit guidance on when to use versus alternatives like listing connections or other openfinance tools. It mentions re-connection via returned URL, giving some context, but lacks explicit exclusions or alternative tool references.

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

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

The description reveals critical behavior beyond the safety annotations: it blocks and waits up to ~60s, polls until the item stops updating, returns results/errors structure, and handles needs_action with reconnect_urls. It clearly explains what happens with wait:false and the meaning of timed_out, offering far more operational detail than the 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?

Although lengthy, the description is front-loaded with the essential action and wait behavior, then flows logically from usage context to parameters to return values and error states. Every sentence carries substantive information; no filler or repetition. The structure enhances readability for an agent rapidly parsing the description.

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 compensates thoroughly by explaining the full return shape ({ results, errors }), per-result fields (status, executionStatus, lastUpdatedAt, synced, needs_action, reconnect_url, timed_out), and follow-up steps. It covers synchronous and asynchronous modes and different item selection scenarios, making it complete 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?

The schema only declares types (boolean, array of strings), but the description adds rich semantics: items accepts selectors like item_id, connector_id, connector_name, or custom_label nickname, and omitting items syncs all linked banks. It also explains the wait parameter's fire-and-forget effect, making the parameters fully understandable.

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 starts with a specific verb and resource: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish.' It clearly distinguishes itself from sibling tools by contrasting with openfinance_get_item_status and explaining it syncs without disconnecting/reconnecting, which is unique among the listed 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 usage guidance is provided: 'Use this when a balance or transaction list looks stale' with a rationale for why this tool is appropriate ('pulls fresh data WITHOUT disconnecting/reconnecting'). It also directs the user to openfinance_get_item_status for timed_out cases and explains the fire-and-forget option with wait:false, effectively covering alternatives and edge cases.

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

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

Beyond annotations (readOnly, idempotent), the description discloses substantial behavior: credit accounts may return a Pluggy BALANCE_FETCH_ERROR with a structured warning instead of throwing; upstream 5xx or non-Open Finance connectors cause degradation to last-synced balance with `realtime: false` and a warning. It also outlines the response shape with results and errors, adding significant context not available 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 somewhat dense but every sentence earns its place: purpose, parameter constraint, special error handling, degradation condition, and response shape. It could be slightly more structured (e.g., bullet-like), but it's appropriately sized and front-loaded with the core 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?

Given the tool has no output schema, the description fully compensates by specifying the response shape (`{ results: [...], errors: [...] }`). It also covers edge cases (credit accounts, upstream failures, non-Open Finance connectors) and the exact behavior of the returned rows, making it complete for an agent 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 schema only defines account_ids as an array of strings with no description. The tool description compensates by specifying the array length (1–50), what values to pass (account IDs), and how errors are returned per ID. This is essential semantic information beyond the raw schema.

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

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

The description clearly states the tool returns a real-time balance payload per account ID, with a specific verb ('Returns') and resource ('balance payload per account id'). It also provides the endpoint. This distinguishes it from sibling tools like openfinance_get_accounts_detail or openfinance_list_accounts, which focus on other 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 gives clear context on how to use the tool: pass `account_ids` as an array (1–50), and explains error handling behavior. It does not explicitly compare to alternatives or state when not to use it, but the constraints and degradation rules provide sufficient practical guidance.

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

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

Beyond readOnlyHint=true, the description warns about provider_incident blocks with unreliable credit limits/balances and instructs not to present those values as real. It also discloses the `{ results, errors }` batch shape, adding significant behavioral context not available from annotations.

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

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

Three sentences: first gives the core purpose, second covers batch/array constraints, third provides an important edge-case warning. No redundancy; information 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 read-only batch retrieval with no output schema, the description covers the essential: full objects, batch shape, size limits, and the rare but critical provider incident behavior. It is sufficient for an agent to invoke it correctly and interpret results cautiously.

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 compensates by specifying that `account_ids` must be an array of 1–50 items and that the response has a batch shape. It also implies each string is an account ID. This adds meaningful parameter semantics beyond the schema.

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

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

Clear verb 'Returns' with specific resource 'full account objects including extended creditData' and scope 'per id'. The endpoint GET /accounts/:id reinforces the action. This distinguishes it from listing tools like openfinance_list_accounts.

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

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

The description implies usage for retrieving detailed account objects by specific IDs via the `account_ids` array (1–50). It does not explicitly name alternatives or conditions when not to use, but the context is clear from the batch shape and extended creditData mention.

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 rich context: the batch shape '{ results, errors }', the meaning of payments[] (typically paying the PREVIOUS bill), absence of a paid/status field, and the unreliability of creditCardMetadata.billId. This goes well beyond the structured 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 front-loaded with its primary purpose, then systematically covers exclusions, alternatives, caveats, and parameter guidance. Every sentence contributes domain-critical information, though some density could be improved without losing value.

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

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

Since there is no output schema, the description fully covers the return shape (financeCharges, payments[], batch results/errors) and subtle payment semantics. It also directs users to sibling tools for status and itemized transactions, making it complete for selecting and invoking this 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 schema description coverage at 0%, the description compensates by explaining that 'bill_ids' should be passed as an array and instructs to use openfinance_list_credit_card_bills first to discover valid ids. It does not specify constraints like non-empty or array uniqueness, but this is sufficient for a single-parameter 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 starts with a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id): financeCharges and payments[]'. It explicitly distinguishes from siblings by stating it does NOT return individual transactions and points to openfinance_list_transactions as the alternative.

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_transactions for itemized transactions, use openfinance_list_credit_card_bills first to discover ids, and prefer that tool for paid status. It also warns against reconstructing bill totals by summing transactions, clarifying what the tool is not for.

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 context: the reconnect_url reopens the widget in UPDATE mode without disconnecting or consuming a connection slot, and bulk returns a structured object. This enriches the agent's understanding of side effects and return 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 concise, using two sentences to cover the primary behavior, single vs. all modes, and bulk support. The second sentence is dense but not wasteful. No unnecessary words, though the parenthetical in the first sentence is lengthy.

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 use cases and return behavior, but lacks clarification for `item_id` and doesn't specify the response format for single-item queries or potential error cases. Given the absence of an output schema and low parameter schema coverage, these omissions leave room for 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?

With 0% schema description coverage, the description carries the full burden for parameter meaning. It explains `item` and `item_ids`, but completely omits `item_id` from the schema, leaving ambiguity between `item` and `item_id`. This is a significant gap that could cause incorrect 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 tool returns the current status of a bank connection, including specific status values, executionStatus, connector metadata, and a reconnect_url. It distinguishes itself from siblings by focusing on status and the reconnect functionality, and explicitly differentiates between single-item and all-items modes.

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

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

The description provides clear guidance on when to omit vs. pass `item` for single vs. all connections, and mentions batch support via item_ids. It does not explicitly mention when not to use this tool or list alternative tools, but the usage modes are well explained.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the batch shape `{ results, errors }` and the 1-50 array limit, which are useful for understanding invocation behavior. No contradictions.

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

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

The description is tightly structured: it opens with the core function and endpoint, lists returned fields, provides sequential usage guidance, and closes with parameter and response shape. Each sentence earns its place; there is no fluff 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 no output schema, the description carries the burden of explaining return values, and it does so thoroughly by enumerating the returned fields and noting the batch response shape. It also gives usage context and parameter limits. Minor gaps include explicit error-handling behavior, but for tool selection and invocation, it is sufficiently complete.

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

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

The schema only defines loan_ids as an array of strings with 0% description coverage. The description compensates by instructing 'Pass `loan_ids` as an array (1-50)', clarifying the parameter's purpose and adding the batch limit. It could go further by explaining ID format or error behavior, but it meaningfully enhances 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's function: 'Returns full loan contract detail by id' and enumerates the specific fields returned. It distinguishes itself from sibling tools like openfinance_list_loans by explicitly positioning this as the deep-dive follow-up for 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?

The description gives explicit workflow guidance: 'Use after openfinance_list_loans to deep-dive on a specific contract.' This clearly indicates when to use the tool and implies the alternative for broad listing. However, it does not explicitly state exclusions or when not to use it, so it falls 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.

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

Goes far beyond annotations by explaining connector-dependent CREDIT balance meaning, the `name` vs `bank` distinction, and potential `provider_incident` and `identity_notice` blocks with deduplication guidance. These are important behavioral traits not captured 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 long but every sentence adds critical value (edge cases, alternatives, behavior). It is front-loaded with the core function and then details caveats. Slightly verbose but justified by 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?

For a tool with no output schema, the description covers return fields, edge cases (incident, identity_notice), cross-tool recommendations, and bulk behavior. It is complete enough for an agent to use correctly without additional info.

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

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

With 0% schema coverage, the description compensates by explaining `item` and `item_ids` (bulk support), and implies `type` through the mention of BANK/CREDIT. However, `item_id` is not explicitly explained as an input (only appears in response context), leaving a minor gap.

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 action ('Returns accounts') and resource ('bank connection'), with types (BANK/CREDIT) and data fields. It also distinguishes itself from the sibling tool openfinance_list_credit_card_bills by noting where to get standardized bill data, making the purpose clear and differentiated.

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

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

Explicitly states when to omit `item` (list all banks) vs pass `item` (target a single bank), and directs users to openfinance_list_credit_card_bills for standardized open-bill amounts. This provides clear when-to-use and alternative guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds 'cached for the adapter session' and 'Single aggregated response — no batch ids', which are useful behavioral details 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?

Two sentences, front-loaded with main purpose, detailed yet concise. Every word 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, the description thoroughly explains each response field, including parent relationships and language variants. It also covers caching and aggregation behavior. For a zero-parameter tool, this is fully 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?

Tool has zero parameters, so baseline is 4. The description focuses on output fields instead, which is appropriate and adds value for the result structure.

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

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

Description clearly states it returns Pluggy's transaction category taxonomy with the specific endpoint GET /categories. It distinguishes itself from sibling tools by focusing on categories and explicitly linking the categoryId to openfinance_update_transaction_category.

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

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

Usage is implied through the field explanations: descriptionTranslated is preferred for pt-BR users, and id is used by another tool. It lacks an explicit when/when-not alternative, but the context makes it clear that this tool is for retrieving category taxonomy before updates.

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 readOnly and idempotent, and the description adds rich behavioral detail: what the returned URLs do, UPDATE mode behavior, and explicit non-destructive traits. No contradictions with annotations.

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

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

Two focused sentences: first states purpose and output fields, second explains reconnect_url usage and key caveats. No fluff, well 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?

With no parameters and no output schema, the description covers the essential return fields and provides actionable guidance on the URLs. It is fully sufficient for an agent to know what to expect and how to 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?

Tool has zero parameters, so schema coverage is vacuous. The description adds meaning by explaining output fields, which is helpful given no output schema. Baseline 4 applies for zero-param 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?

Description clearly states the tool's purpose: 'Returns the saved bank connections for this install' with specific fields (connector_id, item_id, bank name, URLs). This distinguishes it from sibling tools that list accounts, transactions, or statuses.

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

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

Provides explicit guidance for using the reconnect_url ('use it when a connection needs re-authentication'), and notes caveats about not consuming a connection slot or requiring disconnect. It doesn't formally list when to use this tool over alternatives, but the sibling context makes the scope 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?

Despite readOnlyHint and idempotentHint annotations, the description goes far beyond by revealing Open Finance payment semantics, derived payment_status logic, connector asymmetries, confidence levels for projections, and the fact that it returns a warning instead of failing when the product is not enabled. 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 very long but densely packed with critical domain knowledge. It is structured in labeled paragraphs (e.g., 'CONNECTOR ASYMMETRY', 'Bulk support') and front-loads the core return fields before diving into caveats. While somewhat verbose, the complexity justifies the length, though it could be tightened.

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

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

No output schema exists, so the description must cover return values, and it does: account echo, results, payments[], open_bill, future_bills, payment_status_legend, and warnings. It also explains derived fields and their confidence levels, making the tool's behavior predictable without additional 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 the description carries the burden. It thoroughly explains include_open_bill (behavior, default, derived fields), account_ids (bulk support), and account_id (echo context). Page/page_size are not explicitly described but are conventional pagination parameters, so the partial compensation earns a score above baseline.

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 CLOSED credit card bills for a CREDIT-type account' and enumerates the exact fields. It distinguishes itself from sibling tools by contrasting with openfinance_list_transactions and noting this tool provides bill-level summaries, not individual transactions.

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

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

Explicit guidance is given on when to use this tool over alternatives: 'To see itemized purchases/charges, use openfinance_list_transactions' and warnings against summing transactions by billId. It also explains when the open_bill option should be used (instead of the account balance) and when connector asymmetry prevents retrieval.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds significant behavioral context: graceful handling of 403 by returning a warning structure, data integrity cross-checking for mass zeroing, and explicit instruction to treat suspect_zeroed balances as unavailable rather than real R$0. This goes well 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 front-loaded with the core purpose, then provides a detailed data integrity warning and bulk support note. It is somewhat long but information-dense; each sentence adds value, though the data integrity section could be condensed without losing essential guidance.

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 structure, error handling, data integrity, and bulk execution. However, it lacks parameter semantics and explicit alternative-tool guidance, leaving some usage 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 description coverage is 0%, so the description must compensate, but it only mentions item_ids for bulk execution. Parameters like item, page, type, item_id, and page_size are left unexplained, with no details on filtering or 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 uses the specific verb 'Returns' and identifies the resource as 'investment portfolio for a connection', enumerating asset types (FIIs, stocks, ETFs, fixed income, mutual funds, retirement, COE). This clearly distinguishes it from sibling tools like openfinance_list_investment_transactions, which focus on transactions rather than the portfolio.

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 by specifying that it targets connections with the INVESTMENTS product enabled and notes bulk execution via item_ids. However, it does not explicitly mention alternatives or when to use list_investment_transactions instead, 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 readOnlyHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds behavioral detail beyond annotations: the transaction type taxonomy, row-level fields (netAmount, agreedRate, brokerageNumber), itemized expenses, and bulk execution via investment_ids. It does not mention pagination behavior or auth requirements, but the added detail is meaningful.

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 tightly written in three sentences, front-loaded with the core purpose, then actionable usage guidance, then bulk support. 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?

With no output schema, the description compensates by listing key return fields and transaction types. It covers the required workflow (after list_investments) and bulk variant. Minor omissions include pagination details and explicit fallback/alternative tools, but overall the description is sufficient for a list-type tool with strong 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 description coverage is 0%, so the description carries the burden for parameter meaning. It explains investment_id (obtain from openfinance_list_investments) and investment_ids (bulk support), which are the most important parameters. However, it does not clarify page/page_size semantics or the relationship between investment_id and investment_ids beyond the bulk mention, which would have been valuable.

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 movement history for a specific investment position, enumerates supported transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER), and explicitly distinguishes it from related list tools by pointing to openfinance_list_investments. This is a specific verb+resource combination with clear 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 explicitly says to use it after openfinance_list_investments to obtain investment_id, providing clear sequencing context. It does not explicitly state when not to use it or name alternative non-investment list tools, but the investment-specific scope makes the intended usage evident.

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 (readOnly, idempotent, non-destructive), the description discloses that multiple connections are queried sequentially with rate-limit spacing and that the return shape is `{ results, errors }` per connection. This gives the user useful behavioral expectations 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?

Three sentences, front-loaded with the core purpose, followed by parameter usage and return shape. No redundant or filler content; every sentence adds value.

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

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

Given no output schema, the description still tells the user what to expect (`{ results, errors }` per connection). It covers the key aspects needed to invoke the tool correctly: selector types, optional vs mandatory usage, and rate-limit behavior. Sufficient for a read-only list operation.

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

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

The input schema provides no description for `items` (0% coverage), but the description fully explains that it is an array of connection selectors (item_id, connector_id, or connector_name) with one entry per connection. This completely compensates for the schema's lack of detail.

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

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

The description opens with a specific verb and resource: 'Lists loan contracts per bank connection (GET /loans)'. This clearly identifies the action and scope, and distinguishes it from sibling tools like openfinance_get_loan_detail, which is for individual loan details.

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 instructions: pass `items` for specific connections, omit to list all linked banks. It explains the selector types and sequential rate-limit behavior. However, it does not explicitly name an alternative tool for detail-level queries, so it misses a direct 'when not to use' comparison.

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?

While annotations already declare readOnlyHint/idempotentHint/destructiveHint, the description goes far beyond them, disclosing pagination auto vs manual behavior, truncation at 5000, error return shape, per-connector inconsistencies, pending/posted coverage variations, provider_incident blocks, and detail-level trade-offs. 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 very long, but it is structured into logical sections (purpose, credit caveats, pagination, detail levels, errors, bulk) and every sentence adds meaningful operational context. It earns a 4 rather than 5 because the billId caveat is restated in a couple of places and the density could be trimmed slightly without losing value.

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

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

Given there is no output schema, 8 parameters, and 0% schema description coverage, this description is exceptionally complete. It covers return shape (account echo, truncated, warning, error), pagination semantics, per-connector behavior, detail-level output differences, cross-tool references, incident handling, and bulk operation — leaving almost no operational 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?

Schema description coverage is 0%, so the description carries full parameter burden — and it delivers. It explains ISO date formats, search_queries substring semantics (case/accent-insensitive, OR across terms), page/page_size default and manual modes, detail enum values (compact/rich/raw) with trade-offs, account_ids bulk usage, and the account echo block.

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 transactions for a bank account (BANK or CREDIT type).' It immediately differentiates the tool by stating it is the ONLY way to get itemized credit card transactions, and distinguishes it from openfinance_list_credit_card_bills and openfinance_list_transactions_by_item.

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?

Extremely explicit usage guidance: it says when to use this tool versus openfinance_list_credit_card_bills for standardized totals, openfinance_list_accounts for closing/due dates, and openfinance_get_item_status for health checks. It also advises narrowing from/to if truncated:true and warns against summing billId for bill totals.

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

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

Adds rich behavioral context beyond the read-only and idempotent annotations: internal account resolution, 5000/account scan cap with truncated flag, provider_incident block with data integrity caveats, and details on compact vs raw output. 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 information-dense; every sentence adds value. Uses backticks and examples effectively. Slightly verbose with repeated terms, but well-structured and front-loaded with the main 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?

Comprehensive for a complex tool with no output schema: describes return structure (compact summary, por_mes, top_despesas, by_account), raw behavior, incident caveats, and bulk execution. Fully equips 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?

Despite 0% schema coverage, the description explains most parameters: item, from/to, granularity, detail, type, and item_ids for bulk. However, top_n and item_id are only implied (top_despesas, bulk support), and some enum values (compact vs monthly) are not fully mapped. Still, it compensates well.

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 performs consolidated cash-flow analysis across a whole connection, resolving accounts internally and fanning out transactions. It explicitly distinguishes itself from openfinance_list_accounts and explains the item targeting, making its purpose unambiguous and differentiated from sibling tools.

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

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

Provides explicit guidance on when to use it (e.g., 'análise anual/mensal', fluxo de caixa, maiores gastos), when to use raw granularity, and how to combine with detail settings. It also notes bulk support and omitting item for all banks, offering clear context for selection.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant value by disclosing the return payload (global indicator, degraded components, open incidents, your_banks_affected) and the edge case for connected banks. It does not contradict 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 long and pack meaningful content: definition, usage guidance, and return details. It is front-loaded with the main action, though slightly verbose with parentheticals. Each sentence earns its place, but could be tightened.

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

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

For a read-only, no-parameter tool with no output schema, the description fully covers purpose, usage, and return shape, including an edge case for connected banks. It also distinguishes from related siblings, making it complete 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 and an empty input schema, so parameter detail is not needed. The description instead focuses on what the tool returns and when to use it, which is the appropriate compensation for a zero-parameter tool. Baseline 4 is justified.

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 ('Checks') and resource ('LIVE operational status of the Open Finance provider (its public status page)'), and explicitly distinguishes it from the sibling tool `openfinance_get_item_status` by stating 'separate from your own connection's ...'. This makes the tool's purpose unmistakable and clearly differentiated.

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: 'Use it whenever data looks incomplete or stale even though a connection shows UPDATED'. It also contrasts with reconnecting and clarifies that this tool reveals upstream outages, giving clear context and a named alternative (`openfinance_get_item_status`).

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

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

Beyond the read-only and idempotent annotations, the description discloses the caveat about non-Open-Finance connectors requiring manual reconnection, the plan-based visibility of PF/PJ banks, and the behavior of returning a hint instead of the whole catalog when keywords are omitted. These are valuable behavioral insights 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 but every sentence earns its place: it covers purpose, return values, caveats, plan behavior, and usage timing, all in a compact, front-loaded structure. 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 enumerates the return fields and includes critical context about caveats and plan restrictions. It is complete for a search tool with clear input requirements and behavioral nuances.

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

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

The input schema has zero description coverage, so the description carries the full burden. It explains that keywords[] is required, gives an example (['nubank','btg']), and clarifies that include_accounts=true adds accounts to the response. This fully compensates for the schema's silence.

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 'Searches the available bank connectors by name', clearly stating the verb and resource. It then enumerates the returned fields (connector id, access, audience, connections, connect_url), distinguishing it from sibling tools focused on listing connections or 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?

It explicitly says 'Call this BEFORE connecting to hand the user a one-click link to the right bank', providing clear timing/context. It also explains plan-based behavior, but does not explicitly name alternative tools or when not to use it, falling just 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.

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

The description goes far beyond annotations by disclosing a critical side effect: recategorization automatically creates a Category Rule that affects future transactions. It also explains batch error behavior (per-item errors do not fail the whole batch) and the exact response shape. This is rich behavioral context that annotations (readOnlyHint=false, etc.) do not capture.

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 thorough but every sentence delivers value: it states the endpoint, input format, ID provenance, side effect, batch behavior, and error handling. It front-loads the core purpose ('Corrects the category...') and structures subsequent details logically. No fluff or repetition exists.

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 mutation tool with no output schema and no schema descriptions, the description fully compensates. It covers operation, input construction, side effects, response shape, and error handling. Given the complexity (batch processing, teaching behavior, per-item errors), the description is complete and leaves no critical 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?

Even though the schema only defines an `items` array with two string fields, the description explains the semantic role of each field: `transaction_id` comes from openfinance_list_transactions and `category_id` from openfinance_list_categories. It also details the expected shape (array of objects with required keys) and the batch response format, adding meaning that is entirely absent from 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's purpose: correcting the category of one or more transactions via PATCH /transactions/:id. It distinguishes itself from sibling list/read tools by naming the specific action and the resource it modifies, and it provides enough detail (array of transaction_id and category_id) to avoid confusion.

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 when to use this tool ('use this to fix miscategorized transactions') and how it improves future categorization. It also references sibling tools (openfinance_list_transactions and openfinance_list_categories) as sources for the required IDs, giving clear guidance on how to construct input and where the data comes from.

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

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

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the behavioral requirement to include recent messages for reproduction, but it does not explain what happens after submission (e.g., ticket creation, confirmation), persistence, or any side effects. It meets the minimum baseline but lacks extra behavioral context.

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 long, front-loaded with the purpose, and every sentence adds value. It is concise and free of unnecessary 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?

The tool is simple with three parameters and no output schema. The description covers the core purpose and the most important parameter (conversation), but it omits any mention of return values, error behavior, or the 'context' field. For a low-complexity tool, this is adequate but with clear gaps that could confuse an agent.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains the 'conversation' parameter ('recent messages for reproduction') and implicitly suggests 'message' holds the report content. The 'context' parameter is entirely undocumented, and there is no parameter-level detail in the schema. The description provides insufficient semantics for all 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's purpose with specific verbs and resources: 'Report a bug, missing feature, or send feedback.' This distinguishes it from sibling tools, which are mostly focused on financial data access and authentication. The action 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?

The description gives clear context for when to use the tool (reporting bugs, missing features, or feedback) and includes a specific instruction to include the conversation array for reproduction. It does not explicitly mention alternatives or exclusions, but given the tool's unique purpose among siblings, this is not a significant gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety and side-effect expectations. The description adds that it provides current versions, which is consistent with annotations but adds no further behavioral context such as output format or data source. This is acceptable given the simple nature and existing 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, front-loaded sentence with no filler. Every word contributes to meaning, making it highly 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 simplicity—no parameters, no output schema, and strong annotations—the description sufficiently covers what the tool does. It is complete for an agent to understand the tool's purpose and invoke it correctly.

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

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

There are zero parameters, and the schema confirms this. With no parameters, the baseline is 4, and the description does not need to add parameter-level details. The schema already provides full 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 uses a specific verb ('Show') and resource ('MCP platform and adapter versions'), making the purpose clear. It does not explicitly distinguish itself from the sibling 'toolkit_info' tool, which could overlap in function, so it misses the full 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 implies usage when one needs to check platform or adapter versions, but it provides no explicit guidance on when to use this tool versus alternatives like toolkit_info. There are no exclusions or comparison, so the guidance is implied rather than stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is established. The description adds context about the exact return contents, giving the agent a clear picture of the tool's output. No contradictions; it's a pure read operation with no side effects to disclose.

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 main action ('Returns') and then lists four specific aspects in a clear, scannable format. Every word adds value; 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?

For a parameterless, read-only info tool, the description is fully complete: it explains what the toolkit state includes and covers the key return fields, which is sufficient given there is no output schema. It also clearly differentiates from the many sibling tools.

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, which is the baseline for a score of 4. The description doesn't need to explain parameters, and it doesn't, keeping the focus on the return value.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('current toolkit state'), enumerating exactly what is covered: installed MCPs, connection status, accounts, and catalog tool counts. This distinguishes it from sibling tools like show_version or the openfinance_* data 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?

The description implies when to use this tool (to inspect toolkit state) but does not explicitly mention alternatives or exclusions. With many sibling tools, some explicit guidance or a pointer to related tools would be helpful, but its role is fairly self-evident.

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