Carrefour MCP

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

Discloses that token establishes a session and config provides permanent auth. Annotations indicate idempotent and non-destructive, which aligns. 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?

Somewhat conversational and longer than needed; multiple sentences contain repeated info. Could be more concise, but front-loaded with key points.

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

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

Covers both usage scenarios, parameter meaning, and desired outcome. No output schema needed. Complete for a simple auth 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?

With 0% schema coverage, description compensates by explaining the 'token' parameter is a JWT from browser login. Could add format details, but 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?

Description clearly defines the tool's purpose: authenticate by either providing a JWT token for session login or calling with no args to get a login link. It's specific and distinct from sibling tools like connect or marketplace.

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

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

Explains two usage modes (permanent config vs session token) and when to use each (no args for link). Could be clearer about when not to use, but context is sufficient.

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

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

Annotations already declare readOnlyHint true and idempotentHint true, confirming safe read operation. Description adds behavioral context about response in two states (all connected vs missing credentials), which is helpful but not extensive.

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

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

Two short sentences, front-loaded with core purpose, no redundancy. Every sentence adds value and the structure is 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 zero parameters, no output schema, and simple behavior, the description sufficiently covers the tool's behavior in the two main scenarios. No significant gaps remain.

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

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

No parameters exist; schema coverage is 100% (vacuously). Description provides no parameter info, but none is needed. Baseline score of 4 is appropriate.

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

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

Description clearly states tool returns connection status and URLs, with specific scenarios for when all providers are connected versus when credentials are missing. It differentiates from sibling authenticate tool by focusing on status rather than performing 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?

Description implies use for checking connection status but does not explicitly state when to use versus siblings like authenticate or openfinance_list_connections. No exclusions or alternatives are mentioned.

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

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

It reveals critical behaviors beyond annotations: invoke works even when the MCP is not installed (one-off), returns a connect link if credentials are needed, returns a checkout/top-up link if paid and wallet is empty (and to retry), and that write operations require workspace owner/admin. The annotation readOnlyHint=false is consistent, and no contradiction exists.

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

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

The description is a single dense paragraph that is front-loaded with purpose and covers many critical details without filler. It is long but each sentence contributes unique information; however, breaking it into sections/bullets would improve readability and scanability.

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?

It covers the core marketplace flows, admin requirements, auth/payment link behavior, and the separate prompt library. Yet it omits explanation of some actions like 'resume' and parameters like 'immediate' or 'tier_slug', which leaves gaps for an agent trying to invoke all possible actions 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 compensates by explaining the central 'action' parameter and its values (search, describe, invoke, install, etc.), and mentions tool_id and arguments. However, many parameters like limit, immediate, tier_slug, cancel_reason, and prompt_targets are not explicitly defined, leaving some ambiguity for a 23-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 clearly states the tool is the 'official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them', and outlines the core flow (search → describe → invoke). It differentiates from sibling tools like openfinance_* and report_bug by being the central catalog/execution hub.

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 guidance on when to use each action: 'prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT', 'list_tools lists what is callable right now', and 'request_mcp asks us to build a NEW MCP when nothing fits'. This gives clear alternatives and contexts, far beyond a basic 'use this for X'.

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 destructiveness. The description adds that data is no longer available and returns a reconnection URL, providing useful context about the irreversible nature and recovery option. However, it does not mention prerequisites or side effects.

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 concise sentences, each adding value: revoke/delete, data unavailability, and reconnection URL. No redundant 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?

For a simple destructive tool with one parameter and no output schema, the description covers the action and return value. However, it lacks parameter clarification and usage guidance relative to siblings, leaving some gaps for an agent.

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

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

The single parameter 'item' has no description in the schema (0% coverage), and the description does not clarify what 'item' represents (e.g., bank ID, connection ID). The agent must infer from context, making it ambiguous.

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

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

Description clearly states the action: revokes Open Finance consent and deletes connection data for a specific bank. The verb and resource are specific, and it distinguishes from siblings like openfinance_list_connections.

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

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

The description gives the purpose but does not explicitly state when to use this tool over alternatives like openfinance_list_connections or openfinance_force_sync. No 'when-not-to-use' guidance is provided.

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

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

Goes far beyond annotations (which only indicate not read-only, not destructive). Describes polling behavior (waits up to ~60s), return fields (status, executionStatus, lastUpdatedAt, synced, needs_action with reconnect_url), error states (MFA_REINTERACTION, LOGIN_ERROR, timed_out). No contradictions with annotations.

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

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

The description is longer than average but every sentence adds value. It is front-loaded with the main action and then provides detailed guidance. Could be slightly more concise but remains clear and well-structured.

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

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

Given no output schema, the description thoroughly explains the return format (results/errors) with field meanings and error handling (reconnect_url, timed_out). It covers all essential behavioral aspects for an agent to use 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?

Despite 0% schema coverage, the description fully explains both parameters: 'items' as an array of selectors (item_id, connector_id, etc.) and that omitting it syncs all; 'wait' as a boolean for synchronous vs fire-and-forget. This fully compensates for the missing schema descriptions.

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

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

The description uses specific verbs ('forces', 're-sync') and resource ('connections') and clearly states it waits for completion. It distinguishes itself from sibling tools like openfinance_get_item_status (re-check if timed out) and read-only tools by emphasizing its write/sync nature.

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 tells when to use (stale balance/transactions) and when not to (without disconnecting). Mentions alternatives (openfinance_get_item_status for timed out results) and provides guidance on wait parameter behavior (fire-and-forget vs wait).

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 annotations already mark this as read-only and idempotent, but the description adds essential behavioral context: the balance is a snapshot tied to the last upstream sync, not a live read, and errors can be returned as structured warnings rather than thrown exceptions. It also names specific error types and degradation conditions, which goes well 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 front-loaded with the core purpose and endpoint, then systematically covers limitations, corrective actions, parameter usage, and error handling. Every sentence adds useful information; there is no filler or redundancy.

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

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

Despite having no output schema, the description adequately explains the return context: rows contain updateDateTime/updatedAt, balance is per account id, and error rows include a structured warning. It also covers the relevant upstream/connector failure modes, making the tool safe and predictable for an agent to invoke and interpret.

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 does add key meaning: 'Pass `account_ids` as an array (1–50)' provides a required constraint not in the schema. However, it does not explicitly define where account_ids come from or how they are structured beyond being an array, leaving a small 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 verb and resource: 'Returns the latest available balance per account id' and cites the exact endpoint 'GET /accounts/:id/balance'. It clearly differentiates this from sibling tools like openfinance_list_accounts or openfinance_list_transactions by focusing on balance retrieval.

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 tells the agent when to use it, when the result may be stale, and what to do instead: if the balance is stale or disagrees with openfinance_list_transactions, run openfinance_force_sync and re-read. It also covers the reconnect remedy for BALANCE_CONSENT_ERROR, giving clear actionable 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 annotations (readOnly, idempotent, non-destructive), the description adds critical behavioral context: it may include a `provider_incident` block indicating that credit limits and balances could be unreliable. This alerts the agent to potential data quality issues, which is highly valuable for correct tool usage.

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 at four sentences, with key information front-loaded. The first sentence states the core purpose, the second explains the output shape, the third addresses the special `provider_incident` case, and the fourth provides a specific usage warning. No extraneous content.

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 that there is no output schema, the description adequately explains the return structure (full account objects with creditData, batch `results/errors`, and potential `provider_incident`). It covers the most important behavioral nuance. However, it does not detail the fields within an account object, which might be assumed from 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 schema coverage is 0%, but the description compensates by explaining `account_ids` as an array (1–50 elements). This adds meaning beyond the raw schema, specifying both the data type (array of strings) and the length constraint. However, it does not describe individual string format beyond being IDs.

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

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

The description clearly states it returns full account objects including extended creditData per ID. It specifies the endpoint pattern and the required parameter `account_ids`, making the purpose unambiguous. While it doesn't explicitly distinguish from `openfinance_list_accounts`, the focus on extended data and batch retrieval by IDs implies a distinct use case.

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 important usage context: it notes the batch shape `{ results, errors }` and warns about the `provider_incident` block causing unreliable data when the provider has an OPEN incident. This helps the agent decide when to trust the data. However, it does not explicitly state when to use this tool over siblings like `list_accounts`.

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 it read-only/idempotent/non-destructive, and the description adds substantial behavioral context on top: the transactions_basis tri-state (exact vs estimate with confidence:'low' vs unavailable), the extra-cost warning of the opt-in scan, and the critical caveat that payments[] belongs to the PREVIOUS bill and must not be read as paid confirmation. It also warns not to rebuild totalAmount by summing transactions. No contradiction with 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 dense with valuable information and front-loads the core return shape before caveats. Minor structure issues: it is one uninterrupted text block with distinct topics (return shape, opt-in behavior, basis semantics, no-paid-status warning) that would benefit from paragraphs or bullets, and some ideas (transactions, account_id) recur across sentences.

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

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

With no output schema and no helper annotations, this description compensates comprehensively: it documents the return fields, batch shape, the transactions opt-in mechanics, the account_id dependency, the estimation basis, the authoritative-total rule, and the payment-cycle semantics. Only transaction_detail's enum values and the precise transactions_hint structure are left unspecified, which are minor 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 carries the full burden. It compensates well for bill_ids (array plus discovery workflow), include_transactions, and account_id (explaining the account reference requirement). However, transactions_detail (compact/rich/raw) is never mentioned in the description, leaving one of the four parameters entirely unexplained.

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?

Opens with a specific verb-resource pair ('Returns bill-level detail for one or more credit card bills by id') and names the exact endpoint (GET /bills/:id). It enumerates the key fields returned, and by contrasting with openfinance_list_credit_card_bills and openfinance_list_transactions, it makes clear what this tool uniquely does versus its siblings.

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

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

Explicitly routes the agent: 'use openfinance_list_credit_card_bills first to discover ids', points to openfinance_list_transactions for fetching transactions manually, and prescribes that 'To check paid status, prefer openfinance_list_credit_card_bills'. This gives concrete when-to-use and when-not-to-use guidance tied to named sibling tools.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that the reconnect_url allows re-authentication without disconnecting and without consuming a connection slot, which is useful behavioral context. 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 concise (4 sentences) and well-structured, front-loading the core purpose and then providing parameter guidance. Every sentence adds value 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 the moderate complexity and lack of an output schema, the description explains the key return fields and behavior. It could be more complete by detailing the full return structure, but it sufficiently covers the essential information for an agent to use 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 explain parameters. It clarifies that omitting 'item' returns all banks and passing 'item' targets a single bank, and mentions 'item_ids' for bulk. However, it does not differentiate between 'item' and 'item_id' (both strings in the schema), leaving ambiguity about their distinct use. This gap lowers the score.

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 fields like status, executionStatus, connector metadata, and reconnect_url. It distinguishes between retrieving status for all linked banks vs a single bank, and mentions bulk support. This is specific and differentiates it from siblings that list connections or perform other actions.

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 guidance on when to omit or pass the 'item' parameter to get all vs single bank status, and mentions batch execution via 'item_ids'. It lacks explicit exclusions or when-not-to-use scenarios, but the context is sufficient for an agent to decide when to invoke 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds batch shape '{ results, errors }' and the array size limit, but does not cover error behavior or authentication needs. This adds moderate value beyond annotations.

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

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

Three sentences: first lists fields, second gives usage guidance, third specifies parameter and return shape. No wasted words, front-loaded with 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 no output schema, the description lists many fields and mentions batch response shape, covering core functionality. Missing explicit structure of the response object (nested fields, types) but sufficient for a simple retrieval 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 description must compensate. It explains loan_ids as an array of 1-50 items and notes the batch return shape, but does not clarify that items are loan ID strings or the format of each item. Provides some meaning beyond schema but not comprehensive.

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 loan contract detail by ID (GET /loans/:loanId) and lists specific fields returned, which distinguishes it from sibling tools like openfinance_list_loans (which likely provides summaries).

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

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

Explicitly states 'Use after openfinance_list_loans to deep-dive on a specific contract,' providing clear context for when to use this tool. Also specifies the parameter format (array of 1-50 loan_ids) but does not mention when to avoid using 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?

Annotations already mark the call read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: connector-dependent credit balances, `balance_notice` semantics, lagging `bankData` fields after initial connection, provider-incident unreliability, and consent-holder/identity notices. These caveats go far beyond the structured annotations and materially change how an agent should interpret results.

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 purpose is front-loaded and the remaining content is organized into clear operational caveats, each of which earns its place. Though long, the length is justified by the number of genuine behavioral gotchas an agent must know to use the tool correctly.

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, field semantics, edge cases, cross-tool routing, and bulk execution exceptionally well. The only notable gap is explicit documentation of the `item_id` parameter and the `type` filter, which are left mostly to inference.

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 carry the parameter burden. It documents `item` (single bank vs omitted for all banks) and `item_ids` (bulk), but it does not explicitly document `item_id` and only implies `type` filtering by naming BANK/CREDIT, leaving two of four parameters under-specified.

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 opening sentence names the exact action and resource ('Returns accounts for a bank connection') and lists the account kinds and returned fields. It also distinguishes the account name from the bank brand, preventing a common misinterpretation, and points to a sibling tool for standardized bill amounts.

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 selection rules: omit `item` for an all-banks account list, pass `item` to target one bank, and use `openfinance_list_credit_card_bills` for standardized open-bill/debt values. It also provides a concrete user-intent trigger ('my accounts/cards' without naming a bank) and warns when not to rely on CREDIT `balance`.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. The description adds that the response is cached and is a single aggregated response with no batch ids, providing useful behavioral context 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?

Two sentences, no unnecessary words. All information is front-loaded and essential. Efficient and clear.

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

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

Despite lacking an output schema, the description fully explains the return structure (fields like id, description, parentId) and mentions caching and single response. Complete for the tool's simplicity.

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

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

The tool has no parameters (0 params, schema coverage 100%). The description adds value by explaining the meaning and structure of the output fields, which is not covered by the schema, making it highly helpful.

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

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

The description clearly states it returns Pluggy's transaction category taxonomy, cached for the session, and explains the fields in each entry. It is distinct from sibling tools as no other tool lists categories.

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 obtaining category IDs to use with openfinance_update_transaction_category, but does not explicitly state when to avoid using it or alternatives. However, given it is the only category listing tool, the guidance is adequate.

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, destructiveHint=false, idempotentHint=true. The description adds valuable behavioral context: explains that reconnect_url opens in UPDATE mode, does not consume a connection slot, and does not require disconnecting. This goes beyond annotations with 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?

The description is two sentences, conveying all necessary information without fluff. The second sentence is somewhat lengthy but remains focused. Could be slightly restructured but is reasonably concise.

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

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

Given no output schema, the description adequately explains the returned fields (connector_id, item_id, bank name, URLs) and their semantics. It covers the purpose and behavior of the URLs sufficiently for a simple list tool with full annotation coverage.

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

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

No parameters exist (baseline 4 per rules). Schema coverage is 100% and description adds no parameter info since there are none. Score reflects 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 clearly states it returns saved bank connections and lists specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes from sibling list tools like openfinance_list_accounts and openfinance_list_transactions which focus on different resources.

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 guidance for the reconnect_url (for re-authentication, MFA, LOGIN_ERROR, stale data) which indirectly helps when to use the list tool to obtain those URLs. However, it lacks explicit context on when to call the list tool itself versus other connection-related tools like 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?

Discloses critical behavioral traits beyond annotations: payment timing rules (cycle vs. due date), connector asymmetry (open bill availability), bill grouping reliability warnings, and derived payment_status logic. Annotations indicate readOnlyHint and destructiveHint false, which are consistent; description adds value without 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?

The description is long but well-organized: front-loaded with primary fields, then payment semantics, open bill, connector asymmetry. Every section serves a purpose, but minor redundancy could be trimmed. Structure with clear sectioning aids 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 (5 params, no output schema), the description covers all necessary aspects: precise field definitions, payment derivation algorithm, open bill availability, error handling, cross-bank identification, and warnings about transaction-level consistency.

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 description coverage, the description fully explains each parameter: account_id required, include_open_bill opt-in with trade-off (extra scan), account_ids for batched execution, page and page_size for pagination. Adds meaning beyond the schema's mere type definitions.

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 CLOSED credit card bills for a CREDIT-type account, listing key fields (dueDate, totalAmount, payments[], etc.) and distinguishes from sibling tools like openfinance_list_transactions by 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?

Provides extensive when-to-use guidance: explains when not to rely on payments[] for payment status, specifies when to use openfinance_list_transactions for itemized purchases, and advises against using the CREDIT account's balance variable due to connector differences.

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, idempotentHint, and destructiveHint. The description adds critical behavioral details: error handling returns empty structure instead of throwing, data integrity checks for zeroing, and flagging suspect rows. 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 detailed but front-loaded with the main purpose. It includes multiple paragraphs, but each sentence provides value (error handling, data integrity, bulk support). Could be slightly more concise, but structure is clear.

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

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

Given no output schema, the description covers output fields, error handling, and data integrity well. However, it does not explain pagination parameters (page, page_size) or all input parameters, leaving some gaps for a complex 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?

Input schema has 6 parameters with 0% description coverage. The description only mentions 'Bulk support: accepts item_ids' and does not describe item, page, page_size, type, or item_id. With low schema coverage, more parameter descriptions are needed.

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

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

The description clearly states the tool returns the investment portfolio for a connection, listing specific investment types (FIIs, stocks, etc.), and distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on portfolio listing.

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 mentions bulk support with item_ids but does not explicitly state when to use this tool versus alternatives (e.g., openfinance_list_investment_transactions) or when not to use it. It implies usage for portfolio listings but lacks direct 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, idempotentHint=true, destructiveHint=false. Description adds batched execution support and itemized field details (e.g., expenses breakdown). No contradictions.

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

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

Two sentences plus a short paragraph; no unnecessary words. Front-loaded with key info. Could be more structured, but efficient overall.

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

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

For a tool with 4 parameters and no output schema, the description covers main functionality and prerequisites but lacks details on pagination parameters, reducing completeness.

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 description must compensate. It explains investment_id and investment_ids (bulk), but does not describe page or page_size parameters, leaving a 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?

Clearly states it returns movement history for investment positions, lists movement types (BUY/SELL/TAX/etc.) and fields. Distinguishes from siblings like openfinance_list_transactions by specifying it's for investment positions and should be used after 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?

Provides explicit prerequisite: 'Use after openfinance_list_investments to get the investment_id.' Also mentions bulk support. Does not explicitly state when not to use, but the context is clear.

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

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

Annotations already indicate safe read operation; description adds GET endpoint, sequential execution with rate limiting, and response structure `{results, errors}`.

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-load purpose, then parameter usage, then behavior; no redundancy or unnecessary detail.

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

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

No output schema but description states return format. Covers parameter, behavior, and result structure. Siblings differentiate single vs list. Adequate for a simple 1-param tool.

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

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

Schema has 0% description coverage; description fully explains `items` as array of connection selectors (uuid, connector_id, connector_name) and the semantic difference between providing and omitting.

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 lists loan contracts per bank connection, referencing the endpoint and distinguishing from sibling `openfinance_get_loan_detail` by scope and 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?

Explicit guidance on using `items` parameter for specific connections or omitting for all, with sequential querying and rate-limit spacing. Alternative not mentioned but context is clear.

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

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

Discloses substantial behavior beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false): non-throwing error shape, per-connector variability (Nubank sparse billId, PENDING vs POSTED differences, per-connector billForecastDate offset), future-dated scheduled rows at the top of the list, auto-pagination with a 5000-row ceiling, and per-detail token costs. No statement contradicts 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?

Well ordered and front-loaded, making the most dangerous trap visible first, so the length is mostly justified given the complexity. However, the billId warning is stated twice nearly verbatim with the Nubank example, the `detail:'rich'` section repeats material from the opening; this redundancy adds length without adding information. An editor could cut roughly a quarter of the text without loss.

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 in the schema, the description supplied everything an agent needs: the account echo block, page/next, 5000-limit with truncated warning, error response shape, provider_incident block, scheduling semantics, enrichment fields, and guidance on how to verify a zero total (credit item status). For a highly irregular tool this is effectively complete.

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

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

Schema coverage is 0%, and the description fully bears the meaning of every parameter: from/to are 'ISO YYYY-MM-DD' date filters; search_queries is defined as case- and accent-insensitive truth subscription against description and merchant name with OR semantics; page/page_size carry their default/max (50/500) and switching behavior; detail's right result is fully expanded with concrete fields (businessName, cnpj, cnae, category). Conditional semantics — 'When search_queries is set the tool aggregates up to 5000 transactions' — are spelled.

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

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

States a specific verb and resource — 'Returns transactions for a bank account (BANK or CREDIT type)' — and immediately differentiates from siblings: for credit accounts 'this is the ONLY way to get itemized transactions'. An agent can distinguish this from openfinance_list_credit_card_bills and openfinance_list_transactions_by_item without opening any schema.

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/when-not guidance with named alternatives: use openfinance_list_credit_card_bills for 'a standardized open-bill total / total debt', openfinance_list_accounts for closing/due dates, and openfinance_get_item_status when a credit total is 0. It also states hard negative rules ('Do NOT reconstruct a bill's total by summing transactions by billId') and context-specific instructions like passing `to` = today to list only completed activity.

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

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

Adds significant behavioral context beyond annotations: internal account resolution, 5k-per-account cap with truncation flag, provider incident warnings, and granularity/detail 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?

Dense but well-structured with front-loaded purpose. Some redundancy (e.g., repeating 'entradas/saídas' definitions) could be trimmed, but overall 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?

Comprehensive for a complex tool with 9 params and no output schema: covers return format, edge cases (truncation, incident), and bulk mode.

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 all major parameters (item, from/to, granularity, detail, type, top_n) with concrete examples and semantics, fully compensating.

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 provides consolidated cash-flow analysis for a whole bank connection in one call, distinguishing it from sibling tools that require separate account listing calls.

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

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

Explicitly describes when to use (for cash-flow analysis, specific Portuguese queries) and when to use different granularity/detail options; contrasts with alternatives like openfinance_list_transactions.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, but the description adds significant behavioral context: it is LIVE (real-time), checks an external status page, and returns incident details filtered to connected banks. 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 efficiently structured: first sentence states core purpose, second explains use case, third lists return values. No redundant sentences, all information is valuable.

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 sufficiently explains return values (global indicator, degraded components, open incidents, your_banks_affected). The use case is fully covered, and the tool's role among siblings is well-defined.

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 parameters, and the description concisely explains what the tool does without needing any input. Schema coverage is 100%, and the description adds no unnecessary param details.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider's public status page, distinct from the own connection status via openfinance_get_item_status. It specifies what is returned: global indicator, degraded components, open incidents, and affected banks.

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 tells when to use it (when data looks incomplete/stale despite UPDATED connection) and contrasts with the sibling openfinance_get_item_status, providing clear diagnostic 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 readOnly, non-destructive, and idempotent behavior. The description adds valuable context beyond annotations: it explains the caveat about non-Open-Finance connectors needing periodic reconnection, how the user's plan affects visibility of PF/PJ banks, and that the tool never dumps the whole catalog. No contradictions with annotations.

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

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

The description is a single paragraph that covers all necessary aspects without being verbose. It front-loads the main purpose and then adds details. While it could be more structured (e.g., bullet points), it remains efficient and readable.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns: connector id, access, audience, linked connections, optional accounts, connect_url, and caveats. It also covers plan behavior and edge cases, making it complete for an agent to use correctly.

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

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

Schema has 0% description coverage, so the description must explain parameters. It does: keywords[] is described as required and illustrated with examples, and include_accounts is explained to return accounts when true. This adds meaning beyond the bare schema.

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

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

The description clearly states that the tool searches bank connectors by name and returns specific fields like connector id, access type, audience, linked connections, and a ready connect_url. It distinguishes itself from sibling tools like 'openfinance_list_connections' by focusing on search with keywords and providing a one-click link.

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

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

Explicitly instructs to call this tool before connecting to hand the user a one-click link. It mentions that keywords[] is required and that without it a hint is returned. While it doesn't explicitly name alternatives, the context makes it clear when this tool should be used relative to other connection-related tools.

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

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

The description discloses important behavioral traits beyond annotations: it overrides automatic categorization and teaches Pluggy by creating a Category Rule for future similar transactions. It also notes that per-item errors do not fail the whole batch. Annotations (readOnlyHint=false, destructiveHint=false) are consistent and the description adds significant 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 moderately concise, front-loading the core purpose and then detailing side effects and return shape. Each sentence contributes value, though it could be slightly shorter without losing clarity.

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 (batch update with side effects) and no output schema, the description thoroughly covers the return shape, error handling, and learning behavior. It provides sufficient context for an AI agent to understand the tool's complete behavior.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains that items is an array of { transaction_id, category_id }, with transaction_id from openfinance_list_transactions and category_id from openfinance_list_categories. This adds meaning beyond the raw schema, though it doesn't elaborate on parameter formats.

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: 'Corrects the category of one or more transactions (PATCH /transactions/:id).' It specifies the verb 'corrects' and resource 'transactions', and distinguishes from sibling list/get tools by indicating it is an update operation.

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

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

The description explains that transaction_id comes from openfinance_list_transactions and category_id from openfinance_list_categories, and recommends using this tool to 'fix miscategorized transactions and improve categorization accuracy going forward.' While it doesn't explicitly state when not to use, it provides clear context for appropriate usage.

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

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

Description adds behavioral context beyond annotations: conversation array needed for reproduction. Annotations note idempotentHint=true (no contradiction). No destructive behavior mentioned, which aligns with destructiveHint=false.

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, no fluff. Could be more structured but efficient for the 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?

Simple reporting tool with no output schema. Description covers main usage but lacks parameter details. Adequate for basic invocation.

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

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

Schema coverage is 0%, so description must explain parameters. It only describes the 'conversation' parameter, leaving 'context' and 'message' unexplained. Message is required but no semantics provided.

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 reports bugs, missing features, or feedback, using specific verb and resource. It distinguishes from siblings which are all finance-related.

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

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

Explicitly says to include the conversation array for reproduction, guiding when to use. Does not mention exclusions or alternatives, but context signals indicate this is the only bug-reporting 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, idempotentHint, and destructiveHint. The description adds that it shows 'MCP platform and adapter versions', which provides context beyond the annotations but does not disclose additional behavioral traits.

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, clear sentence with no redundant words. It is front-loaded and efficient.

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

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

Given the tool's simplicity (0 parameters, read-only), the description fully explains the purpose and result. No output schema exists, but the version information is clearly stated.

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

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

No parameters exist (schema coverage 100%), so baseline is 4. The description adds no parameter info, but none is needed.

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

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

The description clearly states it shows current MCP platform and adapter versions, which is specific and distinct from sibling tools that handle authentication, finance operations, or connection management.

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

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

No explicit when-to-use or alternatives are given. The unique purpose implies usage when version information is needed, but there is no guidance on when not to use it or how it compares to other tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety profile. The description adds valuable context about the exact data returned (installed MCPs, connection status, accounts, catalog tool counts), going beyond the basic read-only guarantee. There are 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 a single, front-loaded sentence that directly states the purpose and the full scope of the return value. Every word earns its place with no filler or redundancy.

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

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

For a simple, zero-parameter, read-only tool, the description is fully sufficient. It enumerates all key aspects of the returned state, and no output schema exists to clarify further. There are no notable 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?

The tool has zero parameters, so the input schema is trivially complete. Per the rubric, a baseline of 4 is appropriate; no parameter explanation is needed in the 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 'Returns the current toolkit state' and enumerates the exact contents (installed MCPs, connection status, accounts, catalog tool counts). It uses a specific verb 'Returns' tied to a clear resource, and it is distinct from siblings like show_version or openfinance_list_connections.

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

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

The description clearly implies when to use this tool: whenever you need a snapshot of the toolkit state. It does not explicitly name alternatives or exclusions, but the context is unambiguous given the tool's role and zero-parameter signature.

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