Caixa Econômica Federal MCP

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

The description explains the two behavioral modes (returning a link vs. authenticating with a token) and the permanent vs. session distinction. Annotations already indicate idempotency and non-destructiveness; the description aligns with and adds context to these 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 fairly concise, fitting two sentences, but the second sentence is long and packs multiple use cases. It front-loads the purpose but could be broken into bullet points for clarity without adding length.

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

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

Given no output schema, the description should ideally state what the tool returns (e.g., success message, token, error). It describes the two invocation modes but omits the return value, which is a notable gap for an authentication tool.

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

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

The input schema provides only a bare 'token' parameter with no description. The description compensates fully by explaining that the token is a JWT access token, that omitting it returns a login link, and how to obtain it. This adds significant semantic 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 purpose: to authenticate the user for MCP.AI IDE agents, providing instructions for both permanent and session-based login. It distinguishes itself from sibling tools by being the dedicated authentication mechanism.

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 guidelines on when to use each authentication method (config vs. session) and how to invoke the tool (with or without token). However, it does not explicitly compare to sibling tools like 'connect' or other authentication-related tools, missing an opportunity to clarify when to choose this tool over alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail beyond annotations, specifying the two possible return states (all connected vs missing credentials). 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 clear, front-loaded sentences. Every sentence provides value, no redundancy.

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

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

For a zero-parameter, read-only status tool with no output schema, the description covers the major use cases adequately. It explains what to expect in both connection states.

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 description coverage is 100% (default). Per guidelines, 0 params yields baseline 4. No additional param info 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 connection status and URLs, with specific behaviors for fully connected vs missing credentials. It distinguishes from siblings like authenticate and openfinance tools by focusing on the overall connection state.

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 implicitly guides use by explaining when to expect authenticated:true vs connect URLs. No explicit when-not-to-use or alternatives are given, but the context is clear given sibling tools like authenticate for different purposes.

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

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

The description adds substantial behavioral context not available in annotations: invoke works even when the MCP is not installed, it runs one-off without bloating the tool list, and it returns connect/checkout links that require the user to act before retrying. It also discloses that search/describe flag installation status and that writes require owner/admin. This goes far beyond the readOnlyHint/destructiveHint flags and does not contradict them.

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

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

The description is a single dense paragraph with heavy information load, including many clauses and parentheticals. It has clear internal signposts ('Core flow:', 'KEY:', 'Use install only...') but no line breaks or bullet points, making it hard to scan. Every sentence adds value, but the structure could be improved 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 (14 actions, 23 params, no output schema), the description covers the core flow, key invoke behavior, permission requirements, and the prompt library. It describes specific response scenarios (connect link, checkout link, shareable prompt link). It does not detail return formats per action, but that's acceptable without an output schema. Overall it is quite complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the action enum conceptually (search/describe/install/invoke and prompt actions) and the roles of mcp_id/tool_id in the flow. However, it does not systematically cover the many other parameters (limit, query, immediate, tier_slug, cancel_reason, conversation, prompt_targets, etc.), leaving them to be inferred from names. It adds meaning for core params but is incomplete for 23 params.

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

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

The description clearly identifies the tool as the mcp.ai marketplace: the in-platform catalog of every MCP/tool and the way to run them. It explicitly lists the core flow (search → describe → invoke) and covers capability requests like 'find an MCP that does X'. This distinguishes it from sibling tools like openfinance_* (domain-specific connectors) and authenticate (auth), making its scope unmistakable.

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

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

Provides direct guidance on when to use invoke vs install: 'Use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' Also explains when to use search/describe vs list_tools, and covers billing (subscribe/cancel), feedback (report_bug), and alternatives (request_mcp when nothing fits). It even notes that writes require workspace owner/admin, which is a clear exclusion.

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

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

The description adds context beyond annotations: it specifies that the action revokes consent, deletes connection data, makes data unavailable, and returns a reconnection URL. This aligns with destructiveHint=true and provides valuable behavioral detail.

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, front-loaded with the core action, no unnecessary words. 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?

The description covers the tool's action, effect, and output expectation (reconnection URL). However, it omits parameter description and does not mention any side effects or reversibility, leaving minor gaps for a simple 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 description coverage, the description does not explain the sole parameter 'item', which likely identifies the bank. The description fails to add meaning beyond the schema, leaving the agent uncertain about what value to provide.

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, deletes connection data, makes data unavailable, and returns a reconnection URL. This is specific and distinguishes it from sibling tools like connect or openfinance_force_sync.

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

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

The description implies the tool is used when you want to disconnect a bank, but provides no explicit guidance on when to use versus alternatives, nor any conditions or prerequisites. It is adequate but lacks explicit usage context.

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

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

Discloses the PATCH operation, polling up to 60s, and return fields like status, synced, timed_out. Explains that syncing does not disconnect/reconnect. Annotations only provide basic safety hints, but the description adds rich 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?

The description is long but every sentence is necessary and informative. It is well-structured: core purpose first, then usage guidance, parameter details, and return value explanation. No wasted words.

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

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

Given no output schema, the description thoroughly covers return values and possible states (synced, timed_out, needs_action). It also covers both parameters comprehensively. The tool is complex, and the description is complete enough for correct invocation and interpretation.

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

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

With 0% schema description coverage, the description fully explains both parameters: 'items' is an array of selectors (item_id, etc.) or omitted for all banks; 'wait' is a boolean for synchronous vs fire-and-forget behavior. This adds critical meaning 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 forces a re-sync of connections and waits for completion. It specifies the resource (connections), the action (force sync), and distinguishes from alternatives by noting it pulls fresh data without disconnecting.

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 use: when balance or transaction list looks stale. Provides guidance on results: 'needs_action' leads to reconnect_url, 'timed_out' suggests re-checking with another tool. Also explains the 'wait' parameter for fire-and-forget 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant detail: CREDIT accounts may return a BALANCE_FETCH_ERROR with a structured warning, upstream failures degrade to last-synced balance with realtime: false and a warning, and the response shape includes results and errors array. 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?

Two sentences: first states the purpose and parameter, second details edge cases and response shape. Front-loaded with the main action. Every sentence is essential, 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?

The tool is simple (one parameter, no output schema). The description covers parameter constraints, error handling (warnings vs errors), degradation behavior, and response format. No gaps identified.

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 one parameter account_ids (array of strings) with 0% schema description coverage. The description adds that it expects an array of 1–50 account IDs, and explains behavior for different account types and error scenarios. While it doesn't specify the format of each string (presumably IDs), it provides meaningful context 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?

The description clearly states it returns 'real-time balance payload per account id' and specifies the endpoint. It distinguishes from siblings like openfinance_get_accounts_detail by focusing on balance retrieval. The verb 'Returns' and resource 'balance payload per account id' are specific.

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 to pass account_ids as an array (1–50) and describes behavior for special cases (CREDIT accounts, upstream failures). While it doesn't explicitly say when not to use or name alternatives, the sibling tools are clearly different functions, so usage 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 mark it as safe and idempotent. Description adds context about provider_incident block and unreliable credit limits/balances, which is useful behavioral detail 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 efficient sentences: purpose, input spec, and warning. No redundancy, 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?

Describes output shape (full objects, extended creditData, batch result shape, provider_incident). Lacks output schema but compensates with narrative. For a simple read tool with one param, it's nearly complete.

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

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

Schema has 0% coverage for account_ids; description adds that it expects an array of IDs (1-50) and relates it to the endpoint. Missing explanation of what the IDs represent, but sufficient given tool name and context.

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 full account objects including extended creditData per ID, and references the HTTP endpoint. Differentiates from sibling list tool by focusing on detail 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?

Provides explicit input constraints (array of 1-50 IDs) and a critical warning about when data may be unreliable due to provider incidents. Does not explicitly mention alternatives like list_accounts for less detail.

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=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: the batch response shape ({ results, errors }), Pluggy's missing paid/status field, the payment array reflecting previous bill payments, and the sparse/inconsistent billId hint. This goes well beyond the annotations and helps avoid misinterpretation.

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

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

The description is moderately long but each sentence serves a purpose: main purpose, what is excluded, usage guidance, and caveats. It is front-loaded with key return fields. Minor redundancy exists (e.g., repeating 'bill_ids' in multiple sentences), but overall it is well-structured and efficient.

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

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

For a tool with one parameter, no output schema, and no nested objects, the description is highly complete. It covers the batch shape, lack of paid status, payments meaning, relationship to other tools, and incorrect usage patterns. An AI agent has sufficient context to use the tool correctly without needing additional documentation.

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

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

The input schema has one parameter (bill_ids array of strings) with 0% schema description coverage. The description explains to pass an array and to discover IDs via openfinance_list_credit_card_bills, but does not describe the expected format or constraints of the IDs themselves (e.g., ID structure, required length). While it provides usage context, the semantic meaning of the parameter is somewhat assumed. Given low coverage, a score of 3 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?

The description explicitly states it returns bill-level detail for credit cards by ID, lists the included fields (financeCharges, payments with subfields), and clearly distinguishes what it does NOT return (individual transactions). This provides a specific verb+resource with clear scope and differentiates from sibling tools like openfinance_list_transactions.

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

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

The description provides explicit guidance: use openfinance_list_transactions for itemized transactions, do not reconstruct bill total from transactions, use openfinance_list_credit_card_bills first to discover IDs, and explains the batch shape. It also warns about the paid/status field and the meaning of the payments array. This thoroughly addresses when and how to use the tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: reconnect_url reopens the widget in UPDATE mode for re-authentication without disconnecting or consuming a connection slot, and bulk return structure { count, items }. 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?

Single paragraph, front-loaded with main purpose, every sentence adds necessary detail. No wasted words 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 tool with 3 optional params and no output schema, the description sufficiently covers the return structure (status, reconnect_url, count/items for bulk). Could be more precise about the full output format for a single item, but overall adequate.

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?

Description explains semantics for item and item_ids (omit vs pass, batch support), but does not describe the item_id parameter at all. With 0% schema coverage, the description compensates partially but leaves a gap for item_id.

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 the tool returns status of a bank connection with specific fields (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, connector metadata, and reconnect_url. Distinguishes between single vs all vs bulk modes, differentiating from sibling tools like openfinance_list_connections by focusing on current status and reconnect URL.

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 instructions: omit item for all banks, pass item for a single bank, and batch support with item_ids. However, it does not explicitly compare with sibling tools or state when not to use this tool, leaving some ambiguity for an AI agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety and idempotency are covered. The description adds value by detailing the returned fields and batch response structure, though it doesn't disclose potential errors or rate limits.

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 compact: one sentence for function, one for usage, one for parameters, one for response shape. No extraneous text, well-structured and 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?

Lacks an output schema, but the description compensates with a detailed list of returned fields and the batch shape. Missing details on error handling, but overall sufficient for an agent to understand input/output.

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 provides the array parameter name and a bound (1-50), but doesn't explicitly state that the IDs come from openfinance_list_loans or their format. The context implies it, but direct clarification would be better.

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 details by ID, listing specific fields. It distinguishes itself from sibling openfinance_list_loans by indicating a use case for deep-diving after listing, establishing a clear purpose.

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

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

Explicitly instructs to use after openfinance_list_loans for deep-diving, providing a clear workflow. Also hints at array size (1-50) and batch shape, giving 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?

Annotations already declare readOnlyHint, so the description's behavioral details add significant value: explains the provider_incident block indicating unreliable data, identity_notice for duplicate accounts, and connector-dependent credit card balance meaning. 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 lengthy but organized into functional sections. It front-loads the core purpose but includes extensive edge case details (provider incident, identity notice) that could be condensed. Some redundancy in explaining 'bank' vs 'name'.

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 4 parameters, no output schema, and no required fields, the description covers all necessary context: how to list all vs per-item, field meanings, bulk support, and critical caveats about data reliability and deduplication. It also references related tools for billing details.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'item' and 'type' filtering, and mentions 'item_ids' for bulk support. While not a structured param-by-param explanation, it adds sufficient context. Could be more explicit about each parameter's role.

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

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

Clearly states it returns accounts for a bank connection with types BANK and CREDIT, and distinguishes between listing all accounts across banks vs targeting a single bank via 'item' parameter. This differentiates it from sibling tools like openfinance_list_credit_card_bills.

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

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

Provides explicit guidance on when to omit 'item' to list all accounts, when to use 'item' for a specific bank, and warns not to treat credit card balance as monthly bill. Also advises using other tools for standardized billing amounts and deduplication in case of identity notices.

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 it read-only and idempotent. Description adds that results are cached for the session and the response is a single aggregated batch 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?

Concise at 5 sentences, front-loaded with purpose, and each sentence adds meaningful information 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?

Covers returned fields, caching, and cross-reference to another tool. Could mention error cases or empty state, but adequate for a simple read-only list 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?

No parameters, so schema coverage is 100%. Baseline 3; description adds value by detailing the response fields and their usage, compensating for absence of parameter explanations.

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 Pluggy's transaction category taxonomy, referencing the specific endpoint and caching. Distinguishes itself from siblings by explaining that the `id` field is used by `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?

Implied usage for obtaining category taxonomy and IDs for updating transactions, but no explicit when-to-use or when-not-to-use compared to sibling tools 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?

The description adds significant behavioral details beyond annotations (readOnlyHint, idempotentHint, destructiveHint). It explains that the reconnect_url opens the widget in UPDATE mode for existing connections, does not consume a slot, and does not require disconnecting first. 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 a single paragraph that efficiently conveys all key information. It could be split into shorter sentences, but it is not overly verbose and 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?

With no output schema, the description adequately covers the return fields and the important behavior of reconnect_url. It might lack details on error cases or pagination, but for a parameterless list command, 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 input schema has zero parameters and 100% coverage, so the baseline is 4. The description adds meaning about the output fields but cannot add parameter information since none exist.

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

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

The description clearly states that the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes itself from sibling tools that handle authentication, disconnection, or sync operations.

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

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

The description explains when to use the returned reconnect_url (for re-authentication, MFA connectors, LOGIN_ERROR, stale data) and notes it doesn't consume a connection slot. While it doesn't explicitly compare to alternatives, the context is sufficient for an agent to decide when listing is appropriate.

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

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

Annotations indicate readOnlyHint=true and idempotentHint=true, but the description goes far beyond by detailing the absence of a native 'paid'/'status' field, the derivation of 'payment_status' across bills, the connector asymmetry for open bills, and the warning when CREDIT_CARDS product is not enabled. It also explains bulk support and reliability warnings. 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 long but front-loads the main purpose in the first sentence. Every section provides necessary detail for correct usage in a complex domain (Brazilian Open Finance). While not perfectly concise, the structure follows a logical flow and avoids redundancy. A slight reduction in the payment_status derivation detail could improve conciseness, but it is justified given the risk of misinterpretation.

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 (no output schema, 5 parameters with 0% schema coverage, and intricate domain semantics), the description covers all essential aspects: return fields, derived fields (payment_status, open_bill, future_bills), connector asymmetry, reliability warnings, and proper usage. It also includes echo block identification and cross-bank attribution rules. This ensures an agent can understand and apply the tool correctly without additional 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 input schema has 5 parameters with 0% description coverage. The description compensates by explaining the key parameters: account_id (identifying the card), account_ids (bulk support), and include_open_bill (opt-in, derived data). However, page and page_size are not explained, though they are standard pagination. The description adds significant meaning beyond the schema, especially for include_open_bill.

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 'Returns CLOSED credit card bills for a CREDIT-type account' and lists key fields. It distinguishes itself from the sibling tool 'openfinance_list_transactions' by explicitly directing users to that tool for itemized purchases, and from 'openfinance_get_credit_card_bill' by indicating this is the list variant. The verb 'Returns' and specific resource definition make the purpose unmistakable.

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

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

Provides explicit guidance on when to use this tool vs alternatives: 'To see itemized purchases/charges, use openfinance_list_transactions'. It explains the opt-in parameter 'include_open_bill' and advises using derived fields over account balance due to variance. It also warns against misinterpreting payment_status and gives rules for presenting results, such as never calling a bill 'vencida' categorically. This fully equips the agent to use the tool correctly.

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 is highly transparent about behavior: it details error handling for 403, data integrity checks for mass zeroing, and the structure of returned data. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent and the description adds valuable 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?

The description is verbose, with detailed paragraphs on data integrity. While front-loaded with the main purpose, excessive detail about edge cases could be condensed or structured better. Some sentences are long and overloaded with info.

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 complexity (6 parameters, no output schema, no param descriptions), the description is relatively complete in explaining tool behavior, error handling, and data integrity. However, the lack of parameter documentation reduces completeness, preventing a perfect score.

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 should compensate, but it only mentions that item_ids supports bulk execution. It does not explain the meaning or usage of 'item', 'page', 'type', 'page_size', or the relationship between parameters. This is a significant 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 clearly states the tool returns investment portfolios for a connection, listing specific types such as FIIs, stocks, ETFs, etc. It uses a specific verb ('List Investments') and distinguishes itself from sibling tools like openfinance_list_investment_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?

The description provides context on when to use the tool (to get portfolio data) and how it handles errors (returns { total:0, results:[], warning } instead of throwing). It also gives specific guidance on handling data_integrity_warning. However, it does not explicitly mention when not to use it or contrast with alternative 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=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral details beyond these: it lists specific transaction types and describes the structure of each row (quantity, value, amount, expenses breakdown), which helps agents understand what the tool returns and its safe read-only nature.

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 well-structured sentences. The first sentence provides a clear overview of what the tool returns, and the second adds bulk support guidance. No redundant or unnecessary text; 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 details the return structure including specific fields (quantity, value, netAmount, agreedRate, brokerageNumber, and itemized expenses). This gives agents a good understanding of the output. The tool's complexity is moderate, and the description covers key aspects.

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 the key parameter investment_id (from prior tool) and the bulk alternative investment_ids. However, it does not describe page and page_size parameters, which are common pagination fields and could benefit from clarification (e.g., default values, limits).

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 movement history for a specific investment position, enumerating transaction types (BUY, SELL, TAX, etc.) and key data fields. It distinguishes itself by directing users to use openfinance_list_investments first to obtain the investment_id, differentiating it from sibling tools like openfinance_list_transactions.

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

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

Provides explicit usage context: use after openfinance_list_investments to get investment_id, and mentions bulk support with investment_ids. While it doesn't explicitly state when not to use or list alternatives, the guidance is clear and sufficient for most agents.

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=true, idempotentHint=true, destructiveHint=false. The description adds further value by disclosing that multiple connections are queried sequentially with rate-limit spacing and that the response format is '{ results, errors }' per connection. 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 two sentences long: the first states the purpose and endpoint; the second covers parameter usage and return format. Every sentence is essential, and the key information is front-loaded. There is no redundancy 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?

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers how to use the parameter (including selector types), the behavior difference when items is present vs. absent, and the response structure. It also mentions rate-limit handling, which adds 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?

The parameter 'items' has no schema description (0% coverage), but the description fully compensates by explaining that it is an array of connection selectors (item_id uuid, connector_id, or connector_name). This provides complete semantic meaning 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?

The description clearly states the action ('lists loan contracts'), the resource ('loans'), and the endpoint ('GET /loans'). It also specifies the scope 'per bank connection', which differentiates it from sibling tools like openfinance_get_loan_detail. The verb 'list' and resource 'loans' are precise and unambiguous.

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

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

The description provides explicit guidance on when to use the 'items' parameter (to list loans for specific connections) and when to omit it (to list across all linked banks). However, it does not directly compare with sibling tools or state when not to use this tool, so it lacks explicit exclusions.

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

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

Annotations already indicate readOnly/idempotent, but the description adds extensive behavior: auto-pagination vs manual, error handling (returns empty with warning), detail levels, upstream incident handling, and truncation. 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 lengthy but well-structured with sections (pagination, detail, errors). Some redundancy (e.g., billId warnings repeated) but necessary for clarity given 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?

Given no output schema, 0% schema coverage, and complex behavior, the description is extremely complete: covers return structure, error cases, pagination, detail levels, and cross-tool dependencies. Leaves no critical gaps.

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

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

Schema has 0% parameter descriptions, so the description fully compensates by explaining each parameter (from/to format, pagination parameters, detail enum, search_queries semantics, account_ids for bulk). Adds meaning beyond 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 it returns transactions for bank accounts (BANK or CREDIT), distinguishes from siblings like openfinance_list_credit_card_bills, and specifies its unique role for itemized credit card 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?

Explicitly specifies when to use (e.g., for CREDIT card itemization), when not to (for bill totals), and provides alternatives (openfinance_list_credit_card_bills, openfinance_list_accounts). Also explains pagination modes and detail options.

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

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

Annotations already mark the tool as readOnlyHint, idempotentHint, and not destructive. The description adds valuable behavioral context: truncation at 5000/account with a 'truncated:true' flag, a possible 'provider_incident' block with implications, and that the default granularity returns a compact summary. This extra information justifies a score above 3.

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 verbose but well-structured. It starts with the core purpose, then details parameters and behavioral notes. Every sentence adds value, but some phrases are redundant (e.g., 'consolidated' repeated). The length is justified by the tool's complexity, but could be tightened slightly.

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 9 parameters, no output schema, and a complex tool, the description is remarkably complete. It explains the returned data structure (compact summary fields, raw rows, per-account breakdown), truncation behavior, and provider incident handling. No gaps are apparent for effective tool selection and usage.

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

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

Schema description coverage is 0%, so the description must fully detail parameters. It does: explains 'item' accepts connector_id, connector_name, or item_id; 'from'/'to' are ISO dates; 'granularity' defaults to 'monthly'; 'detail' options ('compact', 'rich', 'raw') with their effects; 'type' filters BANK or CREDIT; and 'top_n' is implied in 'top_despesas/recebimentos'. 'item_ids' for bulk support is also covered.

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: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It distinguishes from sibling tools by noting it resolves accounts internally, eliminating the need for openfinance_list_accounts. It also specifies use cases like 'fluxo de caixa' and lists granularity options.

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 the tool, including specific analysis scenarios ('análise anual/mensal', 'maiores gastos/recebimentos') and how to choose between granularity and detail levels. It also explains when to omit the 'item' parameter for all banks. However, it does not explicitly state when NOT to use this tool in favor of 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 declare readOnlyHint=true and idempotentHint=true; description adds beyond by detailing the return value (global indicator, degraded components, incidents, your_banks_affected) and the live check nature. 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 the core purpose, then usage guidance and output details. No wasted words; 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 parameters and no output schema, the description explains the output fields and usage context thoroughly. It provides enough for an agent to decide when to invoke and what to expect.

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 has zero properties), so baseline is 4. Description adds no parameter info but schema coverage is trivially 100%.

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 checks the LIVE operational status of the Open Finance provider, distinct from connection status. It uses specific verbs ('Checks') and resource ('Open Finance provider') and differentiates from sibling tool openfinance_get_item_status.

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 when to use: 'whenever data looks incomplete or stale even though a connection shows UPDATED'. Also distinguishes from connection status tool and explains it helps differentiate provider-side problems from connection issues.

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 non-destructive. The description adds critical details: empty keywords returns a hint, caveats for credential connectors, and plan-specific filtering. 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 comprehensive but slightly long. However, all sentences are informative and it front-loads the core purpose. Minor improvement could be breaking into paragraphs.

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, yet description details the return values (connector id, access, audience, etc.) and edge cases (empty keywords, plan behavior). It fully equips the 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 has 0% description coverage, so description fully compensates. It explains keywords[] with examples and clarifies include_accounts triggers account details. The required nature of keywords is emphasized.

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 it searches bank connectors by name and returns specific fields like connector id, access type, audience, etc. It clearly distinguishes from sibling tools like openfinance_list_connections which lists existing 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?

Explicitly says 'Call this BEFORE connecting' and provides guidance on preferring Open Finance connectors for automation. Also explains plan behavior (PF vs PJ) and caveats for non-Open-Finance connectors.

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 (which already indicate it is not read-only, not open-world, not idempotent, and not destructive), the description reveals critical behavioral traits: it overrides automatic categorization, it teaches Pluggy by creating a Category Rule for future similar transactions, and it explains batch error handling (per-item errors do not fail the whole batch). This fully informs the agent of the tool's side effects and resilience.

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 long but each sentence adds value: clarifying purpose, showing where to get parameters, explaining side effects, and detailing the return structure. It is front-loaded with the core action. Slight redundancy in explaining the batch shape could be streamlined, but overall it 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 the absence of an output schema, the description includes a full breakdown of the return object: { updated, results, errors }. It also covers edge cases like per-item errors not failing the batch. No additional context is needed for effective usage.

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

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

While the input schema itself has no description coverage (0%), the tool description thoroughly explains the parameters: items as an array of objects with transaction_id and category_id, and provides context for obtaining each. This compensates fully 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 starts with a specific verb-resource pair 'Corrects the category of one or more transactions (PATCH /transactions/:id)', clearly identifying the action and endpoint. It distinguishes itself from siblings like openfinance_list_transactions and openfinance_list_categories by stating it updates rather than lists.

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 how to obtain the required inputs: transaction_id from openfinance_list_transactions and category_id from openfinance_list_categories. It also explains the side effect of creating a Category Rule, which helps the agent understand when to use this tool for fixing miscategorized transactions. However, it does not explicitly state when not to use it, which prevents a score of 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?

Annotations already indicate idempotentHint=true and destructiveHint=false, so the description adds some value by mentioning the need for conversation data but does not disclose what happens after submission (e.g., ticket creation) or the response format.

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 concise sentences with no wasted words. The purpose is stated first, followed by a key instruction. Well-structured for quick reading.

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 3 parameters, no output schema, and annotations, the description is brief but misses details like what the tool returns or that it submits a report. The conversation parameter type mismatch (string vs array) is a potential issue.

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 partially explains the conversation parameter (though schema says string, description implies an array) but does not explain context. The mention of 'message' is implicit but not detailed.

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 for reporting bugs, missing features, or sending feedback. It uses a specific verb and resource, and stands out among sibling tools which are primarily 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?

The description provides a usage instruction: include the conversation array for reproduction. However, it does not explicitly state when not to use this tool or compare it to alternatives, though context makes it the only feedback 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it shows versions, but does not disclose any behavioral traits beyond what annotations already convey. 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?

Single, front-loaded sentence with no extraneous words. Earns its place.

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

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

Given the simplicity of the tool (no parameters, no output schema) and comprehensive annotations, the description is complete enough. It conveys exactly 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?

No parameters defined in the schema, so description need not add parameter details. Baseline for 0 parameters is 4.

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

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

The description explicitly states the tool shows current MCP platform and adapter versions, which is a specific verb+resource combination. It clearly distinguishes from siblings like 'toolkit_info' which might show other system info.

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 guidance on when to use this tool vs alternatives. Usage is implied by the nature of the tool (version checking), but there is no mention of when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is covered. The description adds that it reflects the current toolkit state and specifies the output components, but does not mention potential latency, caching, or failure modes. This is adequate given the annotation coverage.

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

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

The description is a single, front-loaded sentence that states the main verb and result, with every phrase adding meaningful detail about the returned information without any wasted words.

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

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

For a zero-parameter tool with no output schema, the description fully enumerates what will be returned (installed MCPs, connection status, accounts, catalog tool counts). Annotations cover the safety profile, and the tool's simplicity means no further context is required.

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

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

The tool has zero parameters, so the baseline of 4 applies. The description correctly avoids parameter details since none exist.

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

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

Uses the specific verb 'Returns' to state the action and lists exact content: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from sibling tools, which are mostly action-oriented (e.g., connect, 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 a use case (checking toolkit state) but does not explicitly state when to use it vs alternatives or provide exclusions. As a unique meta-info tool, no alternative is named, but the purpose is clear enough to infer usage.

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