Unicred MCP

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

Annotations indicate idempotentHint=true and destructiveHint=false, but the description adds behavioral context: it returns a login link when called without token, and performs authentication when called with token. This goes 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 two sentences, front-loaded with purpose, and covers both usage scenarios efficiently. While slightly informal with phrases like 'best:' and 'Or paste it here', it is not wasteful.

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 one-parameter tool with no output schema, the description provides complete context: how to use it, what the token is, and the two authentication workflows. All necessary information is present.

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 one optional parameter 'token' with 0% description coverage. The description compensates by explaining the token is a JWT from browser login, and that omitting it returns a link. This clearly defines the 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?

The description clearly states the tool handles authentication for MCP.AI IDE agents, distinguishing it from sibling tools that deal with connections, marketplace, and other functions. It specifies two authentication methods: permanent config or session token.

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

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

The description explicitly explains when to use the tool (for login) and provides two alternatives: adding token to config for permanent access, or pasting a JWT for session-only login. It also states calling with no arguments yields a login link.

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, idempotentHint=true, destructiveHint=false. The description adds behavioral details: it returns authenticated:true and empty pending[] when connected, and connect_url when credentials are missing. This context goes beyond annotations 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?

Two sentences that are front-loaded with the main purpose. Every sentence adds value, 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 parameters, rich annotations, and simple output structure, the description fully explains the tool's behavior for the two main states. It mentions return fields (authenticated, pending, connect_url) without needing an output schema.

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

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

The tool has zero parameters, so baseline is 4. The description does not need to explain parameters, and it correctly refrains from adding irrelevant info.

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 connection status and URLs, and distinguishes between two scenarios: when all providers are connected and when credentials are missing. It uses specific terms like 'authenticated:true' and 'pending[]', making the purpose precise and distinct from sibling tools like 'authenticate'.

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 checking connection status but does not explicitly state when to use this tool versus alternatives like 'authenticate'. There is no guidance on exclusions or prerequisites.

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

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

The description richly discloses behaviors beyond annotations: invoke runs one-off without installing, returns connect/checkout links for auth/payment, and writes require workspace owner/admin. It also notes that search/describe flag install states. These details add significant transparency beyond the bare annotations.

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

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

The description is long but front-loaded with the core purpose and flow, then layers in key behavioral nuances and the prompt library. Each section adds necessary information for a complex 14-action tool, though it could be tightened with bullet points or shorter 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?

Given the tool's breadth (14 actions, 23 params, no output schema), the description covers the main flows, auth/payment behaviors, install vs invoke, and prompt library. It does not detail return structures for actions like search or list_tools, and some params/edge cases remain unexplained, leaving residual 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?

With 0% schema coverage, the description partially compensates by explaining the roles of key parameters (action, tool_id, prompt_slug/vars via the prompt flow). However, it leaves many of the 23 parameters undefined (e.g., limit, query, immediate, tier_slug, report_context, request_details), so the agent still lacks explicit semantics for the full parameter set.

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 identifies the tool as the mcp.ai marketplace — the in-platform catalog and runner for MCPs/tools, with a clear core flow (search → describe → invoke). It distinguishes itself from sibling tools by detailing its all-encompassing role and the prompt library, making its purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'prefer invoke for a single/occasional use' vs 'Use install only to make an MCP PERMANENT', and explains the purpose of each action (search/describe/invoke, subscribe/cancel, report_bug, request_mcp, prompt library). It also states the permission requirement for writes and specifies when invoke returns connect/checkout links, giving clear decision criteria.

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

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

Annotations already indicate destructiveHint=true. The description adds context: the consent is revoked, data is deleted, and a re-connection URL is returned. This goes beyond the annotation by explaining the consequence and the possibility to reconnect.

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 redundancy. Every phrase adds value: the action, the consequence, and the return value. 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?

The description covers purpose, effect, and output. However, it lacks input parameter clarification and prerequisites for use. Given the tool's destructive nature, more detail on what 'item' represents would improve 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 coverage is 0%, so the description must compensate. It mentions 'for a specific bank' but does not clarify the parameter 'item'—whether it's a bank ID or connection ID. This leaves ambiguity.

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

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

The description clearly states the action: revokes consent and deletes connection data. It specifies the effect (data no longer available) and the output (add_connection_url). While it doesn't explicitly differentiate from sibling tools, the purpose is unambiguous.

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

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

The description implies when to use (to disconnect a bank), but provides no guidance on alternatives or prerequisites. Sibling tools like openfinance_force_sync or openfinance_list_connections exist, but no exclusions or when-not-to-use 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?

Discloses key behaviors: waits up to ~60s, polls until done, returns final statuses, handles errors like MFA_REINTERACTION with reconnect_url, and timed_out fallback. Annotations (false for destructive/readOnly) are consistent—no contradiction. 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?

Packed with information but well-structured: action first, then usage, parameters, returns, error handling. Slightly long at ~150 words but every sentence earns its place. Could trim a few phrases for brevity 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?

Covers all necessary aspects for agent use: what it does, when to use, parameter details, return format, error states, and fallback advice. Despite no output schema, the description explains the response structure adequately for the tool's complexity.

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; the description fully explains both parameters: 'items' accepts various selectors and omission syncs all, 'wait' toggles fire-and-forget. This adds critical meaning beyond the bare schema types.

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

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

The description states a specific verb ('forces the bank to re-sync') and resource ('one or more connections NOW and WAITS'), clearly distinguishing it from sibling tools like 'openfinance_get_item_status' (re-check) and 'openfinance_disconnect_bank' (disconnect). It conveys exactly what the tool does.

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

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

Provides explicit usage context: 'Use this when a balance or transaction list looks stale' and explains the benefit over disconnecting. It also describes when to omit 'items' to sync all, and when to set 'wait: false'. However, it does not explicitly contrast with other sync/refresh alternatives among siblings, missing a small opportunity for clarity.

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?

Even though annotations already flag the tool as read-only and idempotent, the description adds essential behavioral context: the balance is a snapshot tied to the last upstream sync, not a live read. It also discloses failure/degradation modes, structured warnings, and the exact response envelope. This goes well beyond what annotations provide.

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

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

The description is long, but nearly every sentence carries distinct operational value: snapshot semantics, sync caveat, force-sync fallback, credit-account errors, degradation behavior, and response shape. It front-loads the core purpose and then details edge cases. The length is justified by the behavioral complexity it documents.

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

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

With no output schema present, the description supplies the response envelope: `{ results: [...], errors: [{ id, status, message }] }`. It also covers error and degradation behavior, the sync-based staleness caveat, and the recovery path. For a single-parameter read-only tool, an agent has everything it needs to invoke it correctly and interpret the result.

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

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

Schema coverage is 0%, but the description compensates by explicitly specifying 'Pass `account_ids` as an array (1–50).' This adds the cardinality and multiplicity constraint that the raw schema does not convey. It does not explain the format of each account ID string, but the parameter name and tool context make that reasonably clear.

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

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

The description opens with a specific verb and resource: 'Returns the latest available balance per account id (GET /accounts/:id/balance).' It clearly identifies the operation, the entity (account balance), and the per-account granularity, which separates it from transaction or account-listing tools. The purpose is unambiguous and actionable.

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 practical guidance on when to use this tool versus openfinance_force_sync: if the balance is stale or disagrees with openfinance_list_transactions, run force_sync and then re-read. It also explains error scenarios for CREDIT accounts and when degradation occurs. It does not explicitly list exclusions or alternative balance sources, but the context is clear and actionable.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavioral context: the provider_incident block that may cause unreliable credit data, with a clear directive not to present those values as real. Also mentions the batch response shape { 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?

The description is three sentences, front-loading the purpose, then usage, then a critical warning. Every sentence adds value with no redundancy.

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

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

The description covers the return shape, parameter constraints, and a notable edge case (provider incident). While there is no output schema, the description provides sufficient hints about the response. Could include more detail on the structure of account objects.

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 account_ids has 0% schema description coverage, but the tool description compensates by explaining it must be an array of 1-50 items. This adds meaningful constraint information 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 it returns full account objects with extended creditData per ID, and includes the HTTP endpoint. This distinguishes it from sibling tools like openfinance_list_accounts and openfinance_get_account_balance.

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

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

The description specifies that account_ids must be an array of 1-50 items, but does not explicitly state when to use this tool over siblings or when not to use it. Usage context is implied rather than explicit.

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 (readOnlyHint, idempotentHint, destructiveHint=false) establish the safety profile, and the description adds far more: the fact that Pluggy does NOT return a paid/status field, the trap that payments[] typically reflects the PREVIOUS billing cycle, and the absolute rule 'the bill's own totalAmount is authoritative — do NOT rebuild it by summing transactions'. It also exposes the opt-in cost ('extra full transaction scan of the account') and the transactions_basis classification with confidence levels — all valuable behavior not present in any structured field.

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 (~350 words) but contains no filler; every sentence carries critical semantics — the payments trap, the basis classification, the opt-in cost, the two alternative-tool routes. It opens with purpose and high-value field list, which helps, but the long mid-section (transactions_basis) and the NOTEs at the end require an agent to parse a large block to get the full picture, skating in the 5 frame with the other two-sentence examples.

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

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

Given no output schema and a complex, high-risk financial domain, the description explains the batch shape ('{ results, errors }'), the transactions_hint exists, the full semantics of transactions_basis (exact vs date-window vs unavailable), how to use the opt-in path, and the 'no paid-status' caveat. For routine bill retrieval and for the optional purchase enrichment, an agent has everything to call correctly, with only the transactions_details enum truly unpubdefined.

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_parameter description coverage is 0%, so the description carries the full burden. It compensates for three of the four params: bill_ids (pass as array, discover first), account_id (required when including transactions because the bill carries no account reference), and include_transactions (fully elaborated: behavior, cost, extra fields returned). The one clear gap is its transactions_details enum (compact/rich/raw), which receives zero explanation in either the schema or 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 first sentence states the exact operation and resource — 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)' — and enumerates the returned fields (dueDate, billClosingDate, totalAmount, financeCharges, payments[]). This is clearly differentiated from the sibling list_credit_card_bills (discovery) and list_transactions (transaction-level view).

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 routing: 'use openfinance_list_credit_card_bills first to discover ids', 'you can also fetch them yourself via openfinance_list_transactions...' for the non opt-in path, and 'to check paid status, prefer openfinance_list_credit_card_bills'. It also gives the conditional for include-transactions (open/closed bill basis) and even names the kind-of alternative goal where a sibling is to be used instead.

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 behavioral context beyond annotations, such as the reconnect_url behavior and bulk support. Annotations already indicate readOnly and idempotent, but description elaborates on executionStatus and connector metadata.

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?

Four sentences, front-loaded with main purpose, no redundant information. 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 sufficiently explains the output: status, executionStatus, connector metadata, reconnect_url, and for bulk, { count, items }. Covers all essential 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?

With 0% schema description coverage, the description compensates by explaining 'item' and 'item_ids' parameters. However, 'item_id' is not explained, leaving a gap for one of the three parameters.

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

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

The description clearly states the tool returns the current status of a bank connection with specific statuses. It distinguishes from siblings by focusing on status retrieval, not listing or 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?

Provides clear usage guidance: omit 'item' for all banks, pass 'item' for a single bank, and use item_ids for bulk. Does not explicitly mention when not to use or alternatives among siblings.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds batch behavior, error format, and field details. No contradictions, but could mention rate limits or auth needs.

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 dense sentences plus succinct field list and endpoint. Every part earns its place with 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 but complex return, description lists many fields. Adequate for agent to understand what's returned, though might benefit from noting pagination if applicable.

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

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

Schema coverage is 0%, but description adds critical semantics: loan_ids as array of 1-50 IDs, and output shape with results/errors. For a single required param, this adds substantial meaning.

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

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

Description clearly states it returns full loan contract detail by ID, lists many fields, and explicitly distinguishes from sibling openfinance_list_loans by saying 'Use after...to deep-dive'.

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 use after openfinance_list_loans for deep-dive, specifies passing loan_ids as array (1-50), and describes batch shape with results/errors.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds extensive behavioral nuance: connector-dependent credit `balance` meaning, `balance_notice` semantics, lagging `bankData` fields after connection creation, `provider_incident` unreliability, and `identity_notice` consent-holder ambiguity. These are exactly the non-obvious behaviors an agent needs and go 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 long but front-loaded with the core return shape and usage decision before diving into caveats. Every major paragraph addresses a real failure mode. It is not tightly concise, and some explanations could be condensed, but for a tool with this many connector-specific edge cases, the length is largely justified.

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?

There is no output schema, so the description carries the full burden of explaining response fields and edge cases. It covers response structure, per-field meanings, incident/notice handling, bulk behavior, and when to defer to sibling tools. An agent has enough context to invoke this tool correctly and interpret results safely in nearly all realistic situations.

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 clearly explains `item` omission vs. passing, and `item_ids` for bulk execution. However, it does not explicitly clarify the difference between `item` and the singular `item_id` parameter, and `type` is only indirectly covered through the BANK/CREDIT output explanation. Strong compensation overall, but with a small semantic 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 exactly what the tool returns: accounts for bank connections, split into BANK and CREDIT, with balance, number, type, subtype, bankData, and creditData. It also clarifies the `bank` connector-name field and distinguishes account issuer name from brand, making the tool's purpose and output unambiguous.

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

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

The description gives explicit when-to-use guidance: omit `item` to list across all linked banks, pass `item` to target a single bank, and use `openfinance_list_credit_card_bills` when a standardized open-bill amount is needed. It also names `openfinance_force_sync` as the reconciliation action for stale derived fields, clearly routing an agent away from misusing 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, destructiveHint=false, and idempotentHint=true. The description adds that the data is cached for the adapter session and that the response is a single aggregated object (no batch ids), which provides 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 that efficiently convey the tool's purpose, return structure, and caching behavior. 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 parameters, comprehensive annotations, and a clear description of the return data and caching, the description is fully sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema has zero parameters, so schema description coverage is 100%. The description does not need to explain parameters. With 0 params, the baseline 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 clearly states it returns Pluggy's transaction category taxonomy cached per session, and specifies the fields in each entry (id, description, descriptionTranslated, parentId, parentDescription). This distinguishes it from sibling tools like openfinance_list_transactions and 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?

The description indicates that the `id` field is used by openfinance_update_transaction_category, providing context for when to use this tool (before updating categories). It also notes preference for descriptionTranslated for pt-BR users. However, it does not explicitly state when not to use it or 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, idempotentHint=true. The description adds significant context: reconnect_url opens widget in UPDATE mode, does not consume a connection slot, and does not require disconnecting first. 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 two sentences that are front-loaded with the primary purpose and list of returned fields. The second sentence adds essential detail about reconnect_url without unnecessary elaboration.

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

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

For a tool with no parameters and no output schema, the description fully covers the return fields and the behavior of reconnect_url, making it complete for agent understanding.

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, so the description does not need to add parameter semantics. Per guidelines, 0 parameters earns a baseline of 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 clearly states 'Returns the saved bank connections for this install' with specific fields listed (connector_id, item_id, etc.), distinguishing it from sibling list tools like openfinance_list_accounts or 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 explains the purpose of the reconnect_url and when to use it (re-authentication, LOGIN_ERROR, stale data), providing contextual guidance. However, it does not explicitly contrast with tools like openfinance_disconnect_bank or openfinance_force_sync.

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, but the description adds extensive behavioral context: payment timing quirks (pre-payment vs post-payment assignment), derived payment_status logic, open bill derivation, connector asymmetry, and bill grouping reliability. No contradiction with annotations.

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

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

The description is very long and dense, making it less concise. While front-loaded with core purpose, it contains extensive details on payment logic and edge cases that could be condensed or structured better. Every sentence adds value but could be more streamlined for agent 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?

Without an output schema, the description fully explains the response structure: payments[], counts, totals, finance charges, payment_status, open_bill (with subfields and confidence), future_bills, warnings. It covers edge cases (connector asymmetry, unreliability warnings) and provides complete context for inferring correct usage.

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

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

Schema description coverage is 0%, so description must compensate. It thoroughly explains include_open_bill (its boolean, effects, derived data) and account_ids (bulk support). However, it does not explain page and page_size parameters, which are common but should be clarified for completeness. Overall adds significant 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 closed credit card bills for a CREDIT-type account, specifying the verb 'list' and resource 'credit card bills'. It distinguishes from sibling tools like openfinance_get_credit_card_bill (single bill) and openfinance_list_transactions (transactions) by focusing on closed bills and summarizing field details.

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

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

Explicitly provides when to use (for closed bills, with CREDIT account), when to avoid (do not sum transactions by billId, use openfinance_list_transactions for itemized charges), and opt-in alternative (include_open_bill:true for open bill). It also warns about connector-specific limitations, giving clear guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral details: data integrity checks when multiple positions become zero, cross-referencing transaction history, and flagging suspect_zeroed rows. It also mentions bulk support via item_ids. This 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 detailed but somewhat verbose. It front-loads the main purpose, then dives into data integrity details. While each sentence adds value, the length could be trimmed for better conciseness. The structure is logical but could be more compact.

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 (multiple investment types, data integrity handling) and lack of output schema, the description provides a comprehensive overview of the response structure and error handling. It does not explain pagination behavior or how to filter by type, but the input schema covers those. Overall, it is fairly complete for an read-only portfolio listing tool.

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

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

Schema coverage is 0%, so the description must compensate. It explains the purpose of item_ids (bulk support) and enumerates investment types that map to the 'type' enum. However, it does not explain 'item', 'page', or 'page_size' — leaving their semantics unclear. The output field descriptions are detailed, but input parameters are only partially 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 it returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, etc.). It uses strong verbs like 'returns' and specifies the scope, distinguishing it from siblings like 'openfinance_list_investment_transactions' which focus on 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?

The description indicates it is for connections with the INVESTMENTS product enabled, and mentions graceful error handling when the feature is not available. However, it does not explicitly guide when to use this tool versus alternatives like 'openfinance_list_investment_transactions', nor does it state when not to use it.

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

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

Annotations already declare read-only and idempotent. Description adds value by detailing transaction types (BUY, SELL, etc.) and output fields (quantity, value, expenses). Lacks pagination behavior but overall good added 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?

Two paragraphs, no fluff, front-loaded with purpose. Every sentence adds value: purpose, output fields, usage hint, bulk support. 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?

Explains output fields in detail and prerequisite usage. Lacks description of pagination parameters (page, page_size) and their behavior, but overall gives a solid understanding of the tool's function.

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 investment_id in context (prerequisite) and investment_ids (bulk). However, page and page_size are not described. Partial coverage but insufficient for full parameter understanding.

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 movement history for specific investment positions, listing transaction types and fields. It distinguishes itself from siblings like openfinance_list_transactions by being investment-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?

States prerequisite: use after openfinance_list_investments to get investment_id. Also mentions bulk support. Does not explicitly exclude alternatives or provide when-not-to-use, 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?

Beyond annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds important behavioral details: sequential querying with rate-limit spacing when multiple connections are specified, and the return structure `{ results, errors }` per connection. No contradiction with annotations.

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

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

The description is very concise, consisting of two sentences that cover purpose, parameter usage, behavioral nuance, and return format. No unnecessary words, and the critical information is front-loaded.

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

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

Given the simple schema (one optional parameter, no output schema), the description provides complete guidance: how to use the parameter, what the tool does, and the return structure. Annotations cover safety and idempotency. No additional details are necessary for an agent to use this tool correctly.

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

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

The input schema has a single undocumented array parameter `items`. The description fully compensates by explaining that each element is a connection selector (item_id uuid, connector_id, or connector_name), how to use it (pass as array for specific connections, omit for all), and the sequential behavior. With 0% schema coverage, this is excellent coverage.

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

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

The description clearly states the tool lists loan contracts per bank connection and provides the API endpoint (GET /loans). It distinguishes the two modes: with specific connections or across all linked banks. This differentiates it from sibling tools like openfinance_get_loan_detail and 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 explains when to include or omit the `items` parameter (specific connections vs. all banks). It also notes that multiple connections are queried sequentially with rate-limit spacing. However, it does not explicitly mention alternative tools for more granular operations, such as using openfinance_get_loan_detail for a single loan's details.

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

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

The description goes far beyond the readOnly/idempotent annotations, disclosing: automatic vs. manual pagination modes with a 5000-transaction ceiling and 'truncated:true' warning, deterministic descending date ordering where future-dated scheduled installments appear at the TOP ('NEVER read the first row...'), per-connector variance in PENDING capitalization, error return shape {total:0, results:[], warning, error} instead of throwing, an optional provider_incident block, and the account echo block that must be cross-checked against multi-bank connections. No contradiction exists with the annotations (readOnlyHint=true, destructiveHint=false are consistent with a read-only listing).

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: the first sentences state the purpose, the credit-card uniqueness, and the two most dangerous caveats (billId is sparse/inconsistent and not authoritative; future-dated rows are at the top). However, it is very long and contains real redundancy — the billId warning and 'do NOT sum by it' caution appear twice (once up top and once in the detail:'rich' section), and the detail:'rich' explanation re-describes several fields already covered. Dense and valuable, but it could be tightened 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, the description must carry the full burden of return-value explanation — and it does: the account echo block, scheduled_count/notice fields, truncated:true with a 5000 ceiling, the provider_incident block, and the error contract. It covers the standard listings, the rich/raw variants, on the failure, multi-bank attribution, and the cross-tool escalation for stale credit sync. For a complex 8-parameter tool with per-connector variance, nothing an agent needs to invoke it correctly or interpret its outputs is ambiguous.

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 compensate — and it does. It specifies the exact date format (ISO YYYY-MM-DD), defines the search_queries semantics (case- and accent-insensitive substring match, OR across terms, aggregation up to 5000 before filtering), explains the two pagination contracts for page/page_size (omit both vs. pass either), contrasts detail 'compact' vs 'rich' vs 'raw' and the rich metadata fields, and covers bulk via account_ids. Every parameter's operational meaning is explained 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 opening sentence states a specific verb and resource: 'Returns transactions for a bank account (BANK or CREDIT type)'. It also differentiates itself from sibling tools by asserting it is 'the ONLY way to get itemized transactions' for CREDIT accounts, and explicitly routes bill-related work to openfinance_list_credit_card_bills. An agent can distinguish this tool from openfinance_list_transactions_by_item, openfinance_list_credit_card_bills, and openfinance_get_credit_card_bill without opening their schemas.

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

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

The description provides explicit when-and-when-not guidance with named alternatives: use openfinance_list_credit_card_bills for standardized open-bill totals ('open_bill' / 'total_pending_debt'), use openfinance_list_accounts for closing/due dates ('creditData.balanceCloseDate'), and check openfinance_get_item_status / openfinance_force_sync if a credit account returns zero transactions. It also warns when NOT to reconstruct totals (summing transactions by billId is explicitly called non-authoritative). This is thorough, source-aware routing.

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 context beyond annotations: scanning caps at 5000/account with truncated flag, provider_incident block indicating possible incomplete data, and note that reconnecting does not fix provider issues. These details are not in annotations (which only declare readonly and idempotent) and provide critical user guidance.

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

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

The description is verbose and could be more structured (e.g., bullet points). It includes mixed-language terms (entradas, saídas) that may reduce clarity for some users. While information-dense, it does not earn every sentence efficiently; the bulk support note at the end feels tacked on.

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 (9 optional parameters, no output schema, and nuanced behavior like caps and incidents), the description is fairly complete. It explains the return structure (totals, monthly evolution, top items, by-account breakdown) and provides example use cases. The missing output schema is partially compensated, but explicit field details would improve 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?

With 0% schema description coverage, the description carries full burden and largely succeeds: it explains item (connector_id, connector_name, or item_id), from/to as ISO dates, granularity options, detail modes, type filter, and top_n (via top_despesas). However, it conflates item and item_id parameters without distinguishing them clearly, causing slight ambiguity.

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 siblings by noting that it resolves accounts internally, eliminating the need for separate calls to openfinance_list_accounts. The verb 'analyze' and resource 'connection transactions' are specific and unique among siblings.

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

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

The description gives explicit usage context: 'you do NOT need to call openfinance_list_accounts first nor carry account_id uuids between calls.' It includes example use cases like fluxo de caixa and explains when to use granularity/raw and detail optionally. However, it lacks explicit exclusion cues (e.g., when NOT to use this tool, like needing non-consolidated transaction lists).

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, and non-destructive. Description adds valuable context: it checks a public status page, returns global indicator, degraded components, open incidents, and flags incidents affecting the user's banks. 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?

Description is well-structured and front-loaded with the core purpose. Slightly verbose but every sentence adds value; could be trimmed slightly without losing 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?

Despite no output schema, description thoroughly explains what the tool returns: global indicator, degraded components, open incidents, and a list of affected connected banks. Covers all essential 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?

Input schema has zero parameters, so description need not add param details. Schema coverage is 100%, and description succinctly states the no-param nature.

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, distinguishing it from the sibling tool openfinance_get_item_status which checks the user's own connection.

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: when data looks incomplete or stale despite a connection showing UPDATED. Also explains how 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 readOnly, idempotent, nondestructive; description adds valuable context: caveat warnings for non-Open-Finance connectors, connect_url generation, and plan-dependent filtering. 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 longer than average but every sentence carries useful information. Minor opportunity for tighter organization, but no redundancy. Effective front-loading of key verbs and outcomes.

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 provides complete guidance on return values, caveats, plan behavior, and prerequisite usage. For a search tool with moderate complexity, everything needed for correct invocation is present.

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% (no parameter descriptions in schema), but the description thoroughly explains both parameters: keywords (array of strings, required, with examples) and include_accounts (boolean for including accounts). This fully compensates for the schema 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 uses a specific verb (Searches) and resource (bank connectors by name), clearly distinguishing from siblings like 'openfinance_list_connections'. It enumerates exact return fields and caveats, making the tool's purpose 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?

Explicitly states when to call (BEFORE connecting), what happens without keywords (returns a hint), plan behavior (PF hides PJ, PJ covers both), and advises preferring Open Finance connectors. This provides clear context for agent decision-making.

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 that recategorizing automatically creates a Category Rule for the client, a behavioral side effect beyond what annotations provide. It also explains the batch behavior with per-item error handling and the response structure. Annotations only indicate non-read-only and non-destructive, so the description adds significant value.

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 not overly verbose. It front-loads the purpose, then covers parameter structure, side effect, and response format. Minor improvement could be clearer section breaks, but it is appropriately sized for the 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 the complexity of a batch update with side effects and the lack of an output schema, the description is highly complete. It explains the response shape, the side effect of creating a Category Rule, and where to get parameter values. This fully equips 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?

Schema coverage is 0%, but the description provides critical context: it explains that items must be an array of objects with transaction_id and category_id, and tells the agent where to get these IDs (openfinance_list_transactions and openfinance_list_categories). This is valuable beyond the raw schema.

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

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

The description clearly states the verb 'Corrects the category of one or more transactions' and specifies the resource (transactions) and HTTP method (PATCH). It also distinguishes from siblings by explaining how to obtain the required IDs from openfinance_list_transactions and openfinance_list_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 explains when to use the tool: 'to fix miscategorized transactions and improve categorization accuracy going forward'. It also implicitly warns about the side effect of creating a Category Rule. However, it could be more explicit about when not to use it (e.g., if the user wants to avoid creating rules).

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 idempotentHint=true, destructiveHint=false, which align with the description. The description adds that conversation should be included, but does not disclose other traits like asynchronous behavior, rate limits, or response format. With annotations present, the description adds moderate value.

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 with no wasted words. The first sentence states the purpose, and the second provides a key usage hint. 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?

For a simple feedback tool with no output schema, the description covers purpose and a key hint about conversation. However, it lacks explanation of the 'context' parameter, what happens after reporting, and any success/failure indicators. Adequate but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains 'message' (implicitly the bug/feedback text) and 'conversation' (for reproduction), but does not mention 'context'. Thus, it partially adds meaning but leaves one parameter 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?

Description clearly states the tool's purpose: report a bug, missing feature, or send feedback. It is the only tool among siblings that serves this general feedback function, distinguishing it from the finance-specific and system tools.

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

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

Description suggests including the conversation array for reproduction, but does not specify when to use or not use this tool, nor mention any alternatives. It provides implied usage context but no explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it shows 'current' versions, implying a live query, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

The description is a single sentence with no unnecessary words, making it highly concise and front-loaded with the essential purpose.

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

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

Given the tool's simplicity (no parameters, no output schema, and comprehensive annotations), the description is fully adequate and leaves no gaps for an agent to understand its function.

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

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

The tool has zero parameters, and the schema coverage is 100% (empty). With no parameters, the description does not need to add parameter information, earning a baseline of 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 clearly states it shows 'MCP platform and adapter versions', with a specific verb ('show') and resource ('version'). It is distinct from all sibling tools, which cover authentication, financial data, and other 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 implies usage for checking current versions, and no sibling tool competes for this purpose. However, it does not explicitly state when to use it vs alternatives or provide exclusions, but the context makes it clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds useful behavioral context by detailing the nature of the returned state (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond what annotations state.

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 efficiently enumerates the four key components of the toolkit state. There is no filler or redundant phrasing, making it highly concise and structured.

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

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

For a zero-parameter read-only info tool with no output schema, the description fully covers the tool's return content. It specifies exactly what the agent can learn from this tool, which is complete given the simple scope.

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

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

The input schema has zero parameters, and the baseline for 0 params is 4. The description correctly omits parameter details since there are none, so nothing is lost.

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

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

The description clearly states the tool's purpose with a specific verb ('Returns') and resource ('current toolkit state'), then enumerates exact content: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools that focus on openfinance data operations, connect, or authenticate.

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

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

The description provides clear context by specifying exactly what the tool reports, implying it is the place to go for a snapshot of toolkit state. It does not explicitly name alternatives or exclusions, but none of the sibling tools offer this meta-level view, so the guidance is sufficient.

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