Banco Digio MCP

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

Annotations include idempotentHint=true and destructiveHint=false. The description adds flow details (token handling, link generation) but does not elaborate on side effects like setting authentication state or error behavior.

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

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

The description is three sentences, front-loaded with the key purpose, and each sentence adds essential information without redundancy. 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?

While the description covers the authentication flow well, it lacks details on return values (e.g., what the tool returns beyond 'the link') and error handling. Given no output schema, this is a notable gap.

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 compensates by explaining the 'token' parameter: it is a JWT, optional, and its presence determines behavior (session login) or absence (return link).

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 for MCP.AI IDE agents, with specific steps for login and token handling. It distinguishes from siblings like 'connect' by detailing the token-based authentication flow.

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 when to use the tool (for IDE agents) and provides two methods (permanent config or session token). However, it does not explicitly mention when not to use it or compare with alternatives like 'connect'.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond annotations by detailing the response structure for both connected and missing credentials scenarios. 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 two sentences with no fluff. It front-loads the core purpose and then elaborates with specific examples. Every sentence serves a clear function.

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 fully covers what the tool does, including both success and failure cases. It is complete enough for an agent to understand the tool's behavior 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?

There are zero parameters, so the baseline is 4. The description does not need to add parameter information; it correctly focuses on the function and output. Schema coverage is 100% with no parameters to document.

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

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

The description clearly states it returns connection status and URLs, and distinguishes two distinct states: all providers connected vs credentials missing. It uses specific language like 'returns', 'authenticated:true', and 'connect_url'. No confusion about what this 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?

The description implies usage for checking overall connection status, but does not explicitly state when to use this tool versus sibling tools like 'authenticate' or 'openfinance_list_connections'. No when-not-to-use or alternative guidance is provided.

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

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

The description goes well beyond the annotations by disclosing that invoke runs tools without installing, returns connect links for credentials and checkout links for payment, that interactive writes require owner/admin, and that search/describe flag installed status. It also details the prompt library's independent behavior. There is 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 lengthy but well-structured, front-loading the core purpose and then using labeled sections like 'Core flow:', 'KEY:', and 'If...' to organize guidance. Each sentence adds substantive value, though it could be slightly more concise without losing critical details.

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 parameters, no output schema), the description covers the essential flows, permission requirements, and prompt library behavior. It explains key return artifacts like connect links, checkout links, and shareable prompt slugs. Some missing details remain, such as what 'resume' does and the exact return format of search results, but overall it is substantially 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?

With 0% schema description coverage, the description compensates by explaining the purpose of core parameters: action values (search, describe, install, invoke, list_tools, etc.), tool_id for selecting a tool, and mcp_id within the flow. It also implies prompt-related parameters such as prompt_body and prompt_vars. However, not all 23 parameters are explained (e.g., limit, immediate, tier_slug, cancel_reason), leaving some semantic gaps.

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

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

The description clearly states this tool is the official mcp.ai marketplace and catalog of MCPs/tools, also serving as the way to run them. It distinguishes itself from siblings by being a meta-tool for discovering, installing, and invoking MCPs, whereas siblings are domain-specific (e.g., OpenFinance).

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

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

The description provides explicit guidance on when to use each action: search for discovery, describe for profiles, invoke for one-off execution, install for permanent addition, and list_tools for currently callable tools. It also explicitly recommends 'prefer invoke for a single/occasional use' over install, and explains the auth/payment fallback flow.

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 provides behavioral context beyond annotations: it revokes consent, deletes data, makes data unavailable, and returns a reconnection URL. This complements the destructiveHint without contradicting it.

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: action, consequence, return value. No wasted words; information is front-loaded and well-structured.

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

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

For a simple tool with one parameter, the description covers the action, side effects, and return value. The only gap is the lack of explicit parameter documentation, which is minor given the tool's low 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?

The input schema has a single required parameter 'item' with zero description coverage. The description mentions 'for a specific bank' but does not map this to the parameter explicitly, leaving 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 revokes Open Finance consent and deletes connection data for a specific bank, using specific verbs and a clear resource. It distinguishes from sibling tools like connect or force_sync by focusing on disconnection.

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) and notes a reconnection URL is returned, but does not explicitly contrast with alternatives or provide when-not-to-use guidance.

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

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

Beyond annotations (readOnlyHint=false, etc.), description details the PATCH-then-poll behavior up to ~60s, return structure including status, executionStatus, lastUpdatedAt, synced, needs_action with reconnect_url, and timed_out behavior. Also explains wait parameter effect. 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?

Well-structured and front-loaded with core action. Every sentence adds value: use case, parameter details, error handling, alternative modes. Efficient use of text 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?

Comprehensive for a tool with no output schema: explains return format, fields, error conditions (needs_action, timed_out), and references sibling tool for follow-up. Covers edge cases and provides complete context for correct invocation.

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

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

Despite 0% schema description coverage, description fully explains both parameters: items as array of selectors (item_id, connector_id, etc.) or omit for all; wait: false for fire-and-forget. Adds meaning beyond 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?

Clearly states the tool forces a re-sync of bank connections and waits for completion. Specific verb 'force_sync' and resource 'connections'. Distinguishes from siblings like openfinance_get_item_status by explaining it triggers a sync rather than just checking 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: 'when a balance or transaction list looks stale'. Contrasts with alternatives: no need to disconnect/reconnect, and if timed_out, re-check with openfinance_get_item_status. Also explains fire-and-forget mode with wait:false.

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

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

Discloses substantial behavior beyond the readOnlyHint/idempotentHint annotations: the result is a SNAPSHOT anchored to the last upstream sync rather than a live read, updateDateTime/updatedAt is the sync instant, and it enumerates the full error taxonomy (BALANCE_FETCH_ERROR, BALANCE_CONSENT_ERROR, upstream 5xx, non-Open-Finance connector) all degrading to structured warnings instead of throwing. This is rich context annotations cannot express.

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?

Longer than typical, but every sentence earns its place: first sentence states the core purpose, then the freshness caveat, the force_sync alternative, the parameter constraint, and the error modes. It is front-loaded and dense with actionable information rather than filler, with no redundant restatement of the title.

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?

In the absence of an output schema, the description covers the critical response semantics (per-row updateDateTime/updatedAt, structured warning rows), all known error modes, and the follow-up action path. The only gap is a field-level contract for the returned balance rows (e.g., amount, currency), which an agent would otherwise need to infer.

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 — and it does: 'Pass `account_ids` as an array (1–50)' adds the cardinality constraint and plural per-account semantics that the bare schema (array of strings) does not convey. It stops short of explaining ID format or behavior for invalid/empty entries, a minor gap for a single-parameter tool.

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

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

Opens with a specific verb+resource statement: 'Returns the latest available balance per account id (GET /accounts/:id/balance).' The resource is unambiguous and distinct from balance-adjacent siblings like openfinance_list_accounts or openfinance_list_transactions. Even without the title, an agent knows exactly what this tool does and what it does not do.

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 an explicit when-to-use-alternative rule: 'If a movement that just happened is not reflected yet, or the balance disagrees with the sum of openfinance_list_transactions, run openfinance_force_sync to pull fresh data and then re-read.' It also gives remediation for consent errors ('reconnecting the bank restores it'). The conditional routing is concrete and actionable, leaving nothing to inference.

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

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

Adds significant behavioral context beyond annotations: batch response shape `{ results, errors }`, provider_incident block with reliability warnings. Annotations already indicate readOnly, destructive=false, idempotent, and description aligns with 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?

Efficiently structured: purpose first, then parameter details, then warning. No redundant information.

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

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

Covers the primary use case, parameter constraints, and unexpected behavior (provider_incident). Could benefit from mentioning what fields are in the full account objects beyond creditData.

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?

Only parameter account_ids is described with range (1-50) and batch shape, adding meaning beyond the schema which only defines type array of strings.

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 'Returns full account objects including extended creditData', specifies the endpoint pattern, and distinguishes from sibling tools like openfinance_list_accounts which likely return summaries.

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

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

Describes when to use (to get full details with creditData), parameter constraints (array of 1-50 ids), and warns about provider_incident conditions. Lacks explicit when-not-to-use 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 and idempotentHint=true, but the description adds critical behavior beyond annotations: the opt-in transaction scan requirement, that transactions live on the account not the bill, that there is no paid/status field returned, that payments[] typically refer to the previous bill, and that transaction matching may be a low-confidence estimate. This directly prevents the agent from drawing incorrect conclusions from the response. No contradiction with annotations exists.

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

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

The description is dense, but well-structured with clear labels such as 'ITEMIZED PURCHASES (OPT-IN)', 'Always check transactions_basis', and 'NOTE'. Key information is front-loaded: the primary purpose is in the first sentence, then the most important behavioral caveats follow. Although long, every section carries practical information an agent needs to call the tool correctly.

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

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

There is no output schema, yet the description covers the response shape, batch structure { results, errors }, the reconciliation field, authoritative total behavior, and status limitations. It even gives a fallback path for fetching transactions directly and a sibling to use for paid status. For a moderately complex bill-detail function, the description supplies nearly everything an agent needs without being cluttered.

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

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

With schema description coverage at 0%, the description carries full responsibility for parameter meaning. It explains bill_ids (array, discover via list), account_id (needed for include_transactions because the bill has no account reference), and include_transactions (opts into extra transaction scan). However, the transactions_detail enumeration (compact/rich/raw) is never explained, leaving a meaningful gap for an agent choosing a detail level for this tool.

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

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

The description states a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)'. It clearly lists the returned fields and distinguishes the tool from the sibling list tool by pointing to openfinance_list_credit_card_bills for discovery and payment status. An agent can easily tell what this tool does and how it differs from related tools.

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

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

The description gives explicit usage direction: use openfinance_list_credit_card_bills first to discover IDs, prefer that sibling for paid status, pass include_transactions with account_id for itemized purchases, and avoid summing transactions since totalAmount is authoritative. It also explains when transactions_basis should be trusted as exact versus estimated, giving the agent 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 declare read-only and idempotent hints. Description adds detailed behavioral traits: returns reconnect_url that reopens widget in UPDATE mode without disconnecting, and describes return structure. 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 concise paragraphs with no fluff. First paragraph explains core functionality and return values; second adds bulk support. Could be more structured but 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?

Describes return fields well but covers only one of two result shapes (all returns {count, items}, single not specified). No output schema, so missing detail on single-mode response. Annotations cover safety, but behavioral context is good.

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

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

With 0% schema description coverage, the description must compensate. It explains 'item' (omit for all, pass for single) and 'item_ids' (bulk support), but 'item_id' is not mentioned, leaving ambiguity. Meaning is added for two out of 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?

Clearly states it returns the current status of a bank connection with specific fields (status, executionStatus, metadata, reconnect_url). Distinguishes between single and all banks, and is distinct from sibling tools like openfinance_list_connections which list connections without 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?

Explains how to use for single vs. all banks (omit item for all, pass item for single) and mentions bulk support with item_ids. Provides clear context but does not explicitly exclude alternatives or state when not to use.

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, so the tool is safe and idempotent. The description adds the batch size limit (1-50) and the error handling shape, which goes beyond annotations. No contradictions.

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

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

The description is a single, focused paragraph. It lists key returned fields without excessive detail, and every sentence adds value. Slightly longer due to field enumeration but still 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?

No output schema exists, so the description lists contract detail fields, batch shape, and parameter constraints. For a simple one-parameter tool, this covers the essential information needed for correct invocation.

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

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

Schema has 100% required parameters but 0% description coverage. The description compensates by specifying 'Pass `loan_ids` as an array (1-50)' and mentions batch behavior, adding meaning beyond what the schema provides.

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

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

The description clearly states the tool returns full loan contract detail by ID, lists specific fields returned (interestRates, charges, etc.), and explicitly distinguishes its use from sibling openfinance_list_loans via '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?

Provides explicit when-to-use: 'Use after openfinance_list_loans to deep-dive on a specific contract.' Also specifies parameter constraints (array of 1-50 IDs) and result shape ({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?

The annotations only declare readOnly/idempotent/non-destructive behavior, so the description carries the burden of disclosing caveats. It does this extensively: connector-dependent credit balance semantics, balance_notice meaning, provider_incident unreliability, identity_notice deduplication rules, and bankData lag. It even warns against telling the user the card has nothing to pay when balance_notice is present. No contradiction with annotations exists.

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

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

The description is long but front-loaded with the core return values and scoping behavior before diving into caveats. Each major block—brand naming, credit balance caveats, incident notices, identity notices, bulk support—earns its place for safe usage. It is dense rather than padded, though a slightly tighter structure would improve 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 no output schema and a domain with many edge cases, the description is remarkably complete: it names the output fields, explains how to aggregate across connections, warns about unreliable values, and routes users to the right sibling for standardized card bills. An agent can invoke this tool safely and interpret results 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?

With 0% schema description coverage, the description compensates well by explaining item, the omission-of-item behavior, and item_ids for bulk execution. The type enum is partially covered through the account type explanation. However, it does not explicitly document the singular item_id parameter or formally state that type filters the returned accounts, leaving 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 opens with a specific verb and resource: "Returns accounts for a bank connection" and enumerates exactly which fields and account types are returned. It also distinguishes this tool from the sibling openfinance_list_credit_card_bills by explaining that standardized bill amounts come from that tool, making the 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?

The description gives explicit when-to-use guidance: "OMIT item to list accounts across ALL linked banks" versus "Pass item to target a single bank." It also tells the agent to use openfinance_list_credit_card_bills for reliable bill amounts and openfinance_force_sync to reconcile stale values, which fully supports correct tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds behavioral details: caching for the adapter session, single aggregated response with no batch ids, which goes 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 concise and well-structured, front-loading the purpose and listing key fields. It could be slightly more terse but remains effective.

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

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

Given no output schema, the description adequately explains the return value (fields and their meanings) and important behavior (caching, aggregation). It is complete for a zero-parameter, read-only 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?

There are no parameters, so the baseline of 4 applies. The description does not need to add parameter semantics.

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

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

The description clearly states it returns Pluggy's transaction category taxonomy, specifying the endpoint and caching behavior. It differentiates from siblings by being the only tool returning category taxonomy, with explicit mention of fields like 'id', 'description', and 'parentId'.

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 usage by noting that the 'id' field is used by 'openfinance_update_transaction_category', indicating a common workflow. However, it does not explicitly contrast with siblings or 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds behavioral context about the reconnect_url behavior and that it does not consume connection slots. This adds value beyond annotations, though no inherent 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 three sentences, efficiently packed with relevant information. It front-loads the primary purpose and includes details on the special URLs. Slightly verbose in the reconnect_url explanation but overall concise.

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

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

Given no output schema, the description adequately covers the return structure and key nuances (reconnect_url behavior). It lacks pagination or ordering details, but for a listing tool with readOnlyHint, this is acceptable 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 input schema has no parameters, so schema coverage is 100%. The description does not need to explain parameters but instead adds value by describing the output fields in detail, compensating for the lack of an output 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 saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). The verb 'Returns' and the resource 'saved bank connections' are well-defined. It distinguishes from sibling tools by detailing the unique output and URLs.

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 using the reconnect_url for re-authentication scenarios (MFA connectors, LOGIN_ERROR, stale data). It clarifies what the tool does NOT do (consume a connection slot or require disconnecting). However, it does not explicitly state when to use this tool over siblings like 'openfinance_get_item_status'.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: payment status derivation logic, cross-bill payment matching, open bill availability asymmetry, and warning about not assuming payment from non-empty payments array. 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 long but well-packed with necessary details and front-loaded with main functionality. Could be more structured, but every sentence adds value given 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?

With no output schema, the description compensates by listing all returned fields, the derived payment_status, and the optional open_bill structure. It covers edge cases, warnings, and connector asymmetry. Very complete.

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

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

Schema coverage is 0%, so description must compensate. It explains include_open_bill in detail and mentions account_ids for bulk. It does not explicitly explain page and page_size, but they are standard pagination parameters. Overall, adds meaningful parameter 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?

The description clearly states it returns closed credit card bills for a CREDIT-type account and lists specific fields (dueDate, totalAmount, etc.). It distinguishes from sibling tools like openfinance_list_transactions which returns 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?

Extensive when-to-use and when-not-to-use guidance: explains that it's for closed bills, that individual transactions are in another tool, that open bill is opt-in, and includes warnings about payment status interpretation and bill grouping reliability.

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, non-destructive. The description adds critical behavioral details: graceful error handling for disabled products (403), and a sophisticated data integrity warning mechanism for mass zeroing, including how to treat suspect balances. 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 relatively long but well-organized, with a clear front-loading of purpose and a separate paragraph for data integrity. Every part adds value, though it could be slightly more concise.

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

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

Given the tool's complexity (portfolio with many fields, error handling, data integrity) and the absence of an output schema, the description provides comprehensive context. It explains return structure, error behavior, and a detailed edge case handling, leaving few unanswered questions.

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 6 parameters and 0% schema coverage, the description only partially compensates by explaining item_ids for batched execution. It does not describe item, page, type, or page_size, leaving the agent without sufficient guidance on how to use these fields.

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 portfolio data for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on the full portfolio.

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

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

The description implies usage for portfolio retrieval and mentions error handling (returns empty instead of throwing). It does not explicitly state when to use alternatives like openfinance_list_investment_transactions, but the purpose is clear enough for an agent to infer.

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, so safety profile is clear. The description adds moderate context about what transactions are returned and bulk support, but does not disclose pagination behavior or rate limits. 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 short paragraphs, front-loaded with purpose, then return field details, then usage note. Every sentence adds value without redundancy or verbosity.

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 return fields well despite no output schema, provides prerequisite and bulk note. However, missing description for pagination parameters (page, page_size) and lack of error/limit information make it incomplete for full practical use.

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 implicitly explains investment_id (required, obtained from prior call) and investment_ids (for bulk). However, page and page_size are not described at all, leaving a significant gap for a list tool that likely supports pagination.

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 a specific investment position with explicit transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER) and lists many returned fields. It effectively distinguishes from sibling tools like openfinance_list_investments (which lists investments) and openfinance_list_transactions (general 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 clear prerequisite: 'Use after openfinance_list_investments to get the investment_id.' Also mentions bulk support with investment_ids. However, does not explicitly state when not to use or mention alternatives, but the context with sibling tools provides indirect 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 provide readOnlyHint, idempotentHint, and destructiveHint, but the description adds important behavioral details: sequential querying with rate-limit spacing and the return format of {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 concise with two sentences, front-loading the main purpose and then providing essential details. No redundant or extraneous content.

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

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

Despite no output schema, the description explains the return format and rate-limit behavior. For a list tool with a single optional parameter, the description covers all necessary context for an agent to invoke it correctly.

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

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

The input schema has only one parameter 'items' with no description and 0% coverage. The description compensates fully by explaining that each array entry is a connection selector (item_id uuid, connector_id, or connector_name) and that one entry corresponds to one connection to fetch. This adds significant 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 that the tool lists loan contracts per bank connection, specifies the HTTP endpoint (GET /loans), and distinguishes two modes (with or without the 'items' parameter). This makes the purpose specific and differentiates it from siblings like openfinance_get_loan_detail.

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

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

The description explicitly explains when to use the 'items' parameter (for specific connections) and when to omit it (for all linked banks), and mentions sequential querying with rate-limit spacing. It does not explicitly mention when not to use the tool or suggest alternatives, but the context is clear enough.

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

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

Beyond the annotations readOnlyHint/idempotentHint/destructiveHint, the description discloses auto-pagination vs manual pagination, the 5000-row truncation ceiling, descending date ordering, scheduled rows, the account echo block, the error return shape, and provider-incident behavior. It also calls out connector-specific quirks like sparse billId data and varying PENDING vs POSTED 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 dense and front-loaded with the core purpose, and nearly every sentence adds essential operational context. It loses a point for redundancy: the billId sparse/inconsistent warning and the instruction not to sum by billId appear twice, once in the main body and again under detail:'rich'. Otherwise, structure is effective 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?

There is no output schema, so the description carries the full responsibility for return expectations. It covers the response shape, pagination metadata, scheduled_count, truncation, account echo, provider incidents, and per-detail variation. For a tool with this many nuanced behaviors and no output schema, the description is remarkably 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?

With 0% schema description coverage, the description carries full parameter documentation. It explains from/to as ISO YYYY-MM-DD filters, page/page_size auto vs manual pagination semantics, search_queries substring/OR behavior, detail compact/rich/raw differences, and account_ids as bulk support. This compensates completely for the schema's lack of per-parameter descriptions.

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

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

The description says exactly what the tool returns and for which account types: 'Returns transactions for a bank account (BANK or CREDIT type)'. It also differentiates from nearby tools by stating this is 'the ONLY way to get itemized transactions' for credit accounts and by routing bill totals to openfinance_list_credit_card_bills rather than reconstructing them here.

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

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

The description gives explicit when-to-use guidance: use openfinance_list_credit_card_bills for standardized bill totals, openfinance_list_accounts for closing/due dates, and openfinance_get_item_status when a credit account returns zero results. It also explains when to use detail levels, when to pass to=today, and when to omit pagination parameters.

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), description adds critical behaviors: 5000-transaction cap per account with truncation flag, provider_incident block for incomplete data, bulk support via item_ids, and detailed response structure. This is comprehensive for a read-only tool.

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: main purpose, alternative uses, parameter details, edge cases. Though somewhat verbose, each sentence adds necessary detail. Some repetition (e.g., compact summary mentioned twice) but not excessive.

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 9 parameters, no output schema, and moderate complexity, the description covers key aspects: input parameters, default behaviors, truncation, provider incidents, and response structure for both granularities. Missing minor details like pagination for raw mode but the caps and truncation flag mitigate this.

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

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

With 0% schema coverage, description compensates by explaining most parameters: item, from/to, granularity, detail, type, and item_ids. However, the 'top_n' parameter is only implied in 'largest N each' and the interplay between granularity and detail could be clearer (e.g., compact as a detail value vs. output 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?

Clearly states 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' Distinguishes from siblings like openfinance_list_transactions by highlighting that it internally resolves accounts, eliminating the need for separate calls, and allows analysis of all connected banks in one go.

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

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

Explicitly tells when to use this tool: 'Use this for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'.' Also advises against using openfinance_list_accounts first, and explains scenarios for different granularities and detail levels.

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

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

Beyond annotations (readOnly, idempotent), the description adds rich behavioral details: live check, returns global indicator, degraded components, incidents, and flags affected banks. 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 well-structured and front-loaded, but slightly verbose. Every sentence adds value, though minor trimming could improve conciseness.

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

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

Despite no output schema, the description thoroughly explains return values (global indicator, components, incidents, affected banks) and usage context, making it complete for a zero-parameter live health check 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 are defined, so schema coverage is 100%. The description adds context about what the tool queries and returns, satisfying the baseline of 4 for zero-parameter tools.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, distinguishing it from the related sibling openfinance_get_item_status by emphasizing provider health vs. connection health.

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: when data appears incomplete or stale despite an updated connection, to differentiate upstream outages from connection issues. Provides actionable scenario.

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 the annotations: it never dumps full catalog without keywords, returns a hint when keywords empty, honors user's plan (PF hides PJ banks, PJ covers both), and surfaces caveat warnings for non-Open-Finance connectors. This complements the readOnlyHint and idempotentHint 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?

The description is a single dense paragraph containing all necessary information. It front-loads the main purpose and key returned fields. While slightly long, every sentence adds value, and the density is justified by the tool's complexity. Could be broken into bullet points for easier scanning.

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

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

Given the tool has only 2 parameters and no output schema, the description covers everything needed: purpose, when to call, required parameters, return content, plan behavior, and caveat handling. It enables an AI agent to use the tool correctly without relying on external documentation.

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

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

Schema coverage is 0%, but the description fully explains both parameters: keywords[] is required (returns hint if empty), and include_accounts controls whether linked accounts are returned. It adds real-world meaning (pass bank names as keywords) that goes beyond the type definitions, fully compensating for the lack of schema descriptions.

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

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

The description clearly states the tool searches bank connectors by name, lists the returned fields (id, access, audience, linked connections, connect_url), and distinguishes itself from siblings by specifying its role in the connection workflow. It uses a specific verb ('searches') and resource ('bank connectors'), making the 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?

The description explicitly says to call this BEFORE connecting, and provides context on plan behavior and caveat handling. While it doesn't name alternative tools for when not to use it, the sibling list and the focus on pre-connection search make the usage clear. The instruction that keywords[] is REQUIRED also guides proper invocation.

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 key side effect of creating a Category Rule that affects future transactions, which goes beyond annotations. Also explains error handling for batch operations, providing essential behavioral context.

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

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

Description is comprehensive but slightly verbose. It front-loads the main action and follows with important details, but could be tightened without losing meaning.

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?

Completely addresses complexity: no output schema, yet describes return shape; covers prerequisites, side effects, and batch behavior. Leaves no gaps for effective tool invocation.

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

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

With 0% schema description coverage, the description fully compensates by explaining the structure of the 'items' parameter, required fields, and how to obtain the IDs from other tools.

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

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

Clearly states the tool corrects transaction categories, specifies HTTP method and endpoint, and distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_categories by referencing them as sources for IDs.

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

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

Provides clear context on when to use (fix miscategorized transactions, improve future accuracy) and prerequisites (IDs from specific sibling tools). Lacks explicit exclusion criteria but offers sufficient guidance.

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

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

The description lacks behavioral disclosure beyond the obvious write operation. Annotations set idempotentHint=true, which contradicts the implied non-idempotent nature of reporting a bug (multiple reports create multiple entries). No discussion of side effects, permissions, or response behavior.

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

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

The description is concise, consisting of two sentences. It front-loads the purpose and then gives specific guidance. No unnecessary words.

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

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

Given the low complexity (3 parameters, no output schema), the description is minimally adequate. However, it does not cover potential contradictions (idempotentHint) or provide enough detail for the agent to confidently invoke the tool (e.g., format of conversation, expected response).

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

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

Schema description coverage is 0%, so the description must compensate. It explains that 'conversation' should contain recent messages for reproduction, giving it meaning. However, 'message' and 'context' are not described beyond their names, leaving the agent to infer usage from the tool's purpose.

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: reporting a bug, missing feature, or sending feedback. It specifies to include a conversation array, which distinguishes it from sibling tools that are primarily finance-related and do not involve feedback.

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

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

The description explicitly says when to use this tool (for bugs, features, feedback) and implies the need to include a conversation array. However, it does not mention when not to use it or provide alternatives, but the sibling set makes the context clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description adds minimal behavioral context. It specifies what versions are shown (platform and adapter), which is useful but not extensive.

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

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

The description is a single, concise sentence that directly states the tool's purpose without any extraneous information. Every word earns its place.

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

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

Given the tool's simplicity (no parameters, no output schema, and annotations covering safety), the description is complete. It sufficiently explains what the tool does and what information it provides.

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

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

There are no parameters (0 params), so the baseline is 4. The description does not need to add parameter information since the schema is empty and fully 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 shows 'current MCP platform and adapter versions', specifying both the action and the resource. It distinguishes itself from sibling tools, which are primarily about authentication, finance operations, etc.

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 does not explicitly state when to use this tool vs alternatives, but given its simple nature and clear separation from sibling tools, the context is clear. There are no exclusions needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond annotations by specifying exactly what the tool reports (installed MCPs, connection status, accounts, catalog tool counts). This enriches the agent's understanding without contradicting any 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, well-structured sentence that front-loads the key purpose ('Returns the current toolkit state') and enumerates the specific data returned. Every word adds value with 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?

For a zero-parameter tool with no output schema, the description is fully complete. It tells the agent what the tool returns, which is sufficient given the tool's simplicity and the annotated safety characteristics.

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 takes no parameters, and the input schema is an empty object with 100% coverage. Per the rubric, the baseline for 0 parameters is 4. The description doesn't need to explain parameters, and it doesn't, so the score 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 clearly states the tool returns the current toolkit state, listing specific data points (installed MCPs, connection status, connected accounts, catalog tool counts). This makes its purpose explicit and distinct from sibling tools like connect or openfinance_list_accounts, which perform actions or list domain-specific items.

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 use cases: when you need an overview of the toolkit's overall status and health. It doesn't explicitly mention alternatives or when not to use, but the context of sibling tools (connect, authenticate, etc.) makes it clear this is the diagnostic/status tool. The lack of explicit exclusions is a minor gap.

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