Midway MCP

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

Adds useful context beyond annotations: distinguishes permanent non-expiring connections from session-only logins, and discloses that calling with no args returns a link. Annotations only provide idempotentHint; the description offers practical behavioral details that help the agent understand side effects.

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

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

A three-sentence paragraph that is informative and structured, though the opening context 'MCP.AI for IDE agents' is slightly verbose. No redundant wording, and the flow from browser login to two authentication options is logical.

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 tool with one optional parameter, the description covers how to use it and the behavior of each mode. It lacks explicit return value descriptions for the token call, but that is not critical for the agent to 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?

Despite 0% schema description coverage, the description fully explains the optional 'token' parameter: it is the JWT to paste for session-only login, while omitting it fetches the link. This completely compensates for 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 the action: authenticate with the server by logging in via browser and handling access tokens. It distinguishes itself from sibling tools as the sole authentication tool and explains the two invocation modes (permanent header 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?

Provides clear context for IDE agents (Cursor, etc.) and explicitly describes two usage modes: permanent header configuration and session-only token pasting. It does not contrast with sibling tools like 'connect', but the guidance on when to use each mode is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the exact response shape in two scenarios (authenticated:true with empty pending[] vs. connect_url when credentials are missing), which is more specific than the annotations alone.

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

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

The description is two sentences long, front-loaded with the primary purpose, and every sentence provides concrete behavior. It is appropriately sized for a simple status tool.

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, read-only annotations), the description fully covers the necessary context: what the tool returns and under what conditions. It is complete for an agent to invoke correctly.

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

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

The tool has zero parameters, so the schema provides complete coverage (100% by default). Per the rubric, a 0-param tool gets a baseline of 4. The description does not need to add parameter details and does not.

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

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

The description clearly states the tool's function: 'Returns connection status and URLs.' It provides specific behavior for different states (all providers connected vs. credentials missing), which distinguishes it from sibling tools like authenticate that would initiate authentication rather than report 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?

The description implies usage for checking connection status and URLs, but does not explicitly mention when not to use it or compare it to alternatives like authenticate or openfinance_list_connections. It gives clear context but lacks explicit exclusions.

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

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

Annotations specify readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false, and the description expands on this by disclosing that invoke runs tools one-off even when not installed, returns connect links for missing credentials, returns checkout links when the wallet is empty, and requires owner/admin for writes. No contradictions with annotations.

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

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

The description is a dense, single-paragraph wall of text covering many features. It is information-dense but lacks structural breaks, making it harder to parse. While appropriate for the tool's complexity, it could benefit from clearer organization (e.g., bullet points or subsection headings).

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 the tool's complexity and lack of an output schema, the description covers the primary user journeys, describes key behavioral outcomes (e.g., invoke return behavior, install's permanence), and mentions the prompt library. It omits details on return formats and some edge cases, but overall provides enough context for an agent to operate.

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

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

The schema has 23 parameters with 0% description coverage. The description explains the central actions (search, describe, invoke, install, etc.) and mentions relevant parameters like action, query, mcp_id, tool_id, and arguments. However, many parameters (e.g., cancel_reason, cancel_comment, report_context, request_details, immediate, tier_slug) are not covered, leaving gaps for those sub-actions.

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 is the official mcp.ai marketplace—the catalog and runner for MCPs/tools. It distinguishes itself from sibling tools by outlining the core search → describe → invoke flow and secondary prompt library functionality, making its multi-purpose nature explicit.

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 for actions: prefer invoke for single/occasional use, use install for permanent toolkit additions, use list_tools to see callable tools, and use subscribe/cancel for billing. It also explains when to use search_prompts/get_prompt/publish_prompt, and notes auth requirements for writes.

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 set destructiveHint=true, but the description adds important behavioral context: what gets deleted (connection data), the consequence (data no longer available), and a re-connection URL. This goes beyond the bare annotation and accurately describes the irreversible nature.

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

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

Two concise sentences, front-loaded with the action and consequence, followed by the return value. No unnecessary words or repetition.

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

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

For a single-parameter destructive tool with no output schema, the description covers purpose, behavior, and return value. It lacks guidance on where to find 'item' (e.g., from list_connections) but is otherwise sufficiently complete.

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

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

With 0% schema description coverage, the description's mention of 'a specific bank' is the only hint that 'item' refers to a bank identifier. It doesn't specify the format, source, or how to obtain this value, leaving the parameter somewhat underspecified.

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 the Open Finance consent for a specific bank and deletes the connection data.' It uses a specific verb ('revokes'/'deletes') and resource ('bank connection'), distinguishing it from sibling read/sync 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 provides clear context: use when you need to disconnect a specific bank and delete its data. It doesn't explicitly name alternatives or exclusions, but the 'specific bank' phrasing and connection-deletion purpose make the intended use 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 only give readOnlyHint=false and destructiveHint=false, but the description adds rich behavioral detail: PATCH method, polling up to ~60s, return structure with `synced` and `needs_action`, `reconnect_url` behavior, and that no slot is consumed. This aligns with annotations and provides critical context about side effects.

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

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

Though dense, every sentence carries operational value: core action, return format, error states, timing, and alternative mode. The semi-colon structure and explicit commands ('Pass... OMIT... Set...') make it easy to scan despite length.

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

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

No output schema exists, so the description covers return details (`{ results, errors }`), per-result fields, needs_action with reconnect_url, timed_out handling, and wait behavior. This is complete for a tool with polling and re-authentication 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 coverage is 0%, so the description fully compensates. It explains `items` as an array of selectors (item_id, connector_id, connector_name, custom_label) and the special 'omit to sync ALL' case, plus `wait` as a boolean to toggle synchronous waiting vs fire-and-forget.

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 precise action: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish' – a specific verb, resource, and behavior. It distinguishes from sibling tools like openfinance_get_item_status by describing the polling mechanism and explicitly framing this as the 'fresh data' tool.

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

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

Provides explicit when-to-use guidance: 'Use this when a balance or transaction list looks stale'. It also explains alternatives and constraints: no disconnect/reconnect needed, use openfinance_get_item_status for re-checking timed_out cases, and wait:false for fire-and-forget.

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 readOnly/idempotent annotations: it explains that updateDateTime/updatedAt is the sync instant, not a live read; describes BALANCE_FETCH_ERROR and BALANCE_CONSENT_ERROR; and details row degradation to realtime:false with warnings. These are non-obvious behaviors the agent needs to interpret results correctly.

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 the length is justified by the complex error, degradation, and freshness semantics. It is front-loaded with the core purpose and endpoint, and each subsequent sentence adds meaningful operational detail rather than filler.

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

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

Given that there is no output schema, the description covers the response shape, the errors array structure, per-row warning behavior, and the realtime flag. It also references sibling tools for the recovery path. Nothing essential for invoking or interpreting the tool is missing.

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

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

With 0% schema coverage, the description compensates by telling the agent to pass account_ids as an array and constraining it to 1–50 items. It does not specify the exact format of each account id string, but for a single required parameter this is nearly sufficient.

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

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

The description states a specific verb and resource: 'Returns the latest available balance per account id' with the exact endpoint. It clearly differentiates this from list-type tools and ties the snapshot semantics to the sync anchor rather than a live read.

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

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

It explicitly tells the agent when to use the alternative: if the balance is stale or disagrees with openfinance_list_transactions, run openfinance_force_sync and re-read. It also covers credit-account error cases and when degradation occurs, giving clear decision context beyond a simple tool description.

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 cover readOnly and idempotent hints, so the description adds valuable non-obvious behavior: the provider_incident block and warning that credit limits may be unreliable. This goes beyond the structured metadata and aids correct interpretation.

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 front-loaded with the main purpose, then provides essential usage details and a safety warning. No redundant or filler 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?

With no output schema, the description explains the return structure (full account objects, batch shape, provider_incident) and parameter constraints. It is complete 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?

The schema only says account_ids is an array of strings, but the description adds critical semantics: array size 1–50, batch shape { results, errors }, and the meaning of each item as an account id. With 0% schema coverage, this fully compensates.

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 account objects including extended creditData per id, referencing the endpoint. It distinguishes from sibling tools like openfinance_get_account_balance and openfinance_list_accounts by emphasizing the 'full account objects' and 'creditData' scope.

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

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

Usage context is clear: pass account_ids as an array (1–50) and get a batch result shape. It doesn't explicitly state when to use this over alternatives, but the description implies it for detailed account data. No exclusions are given, so it falls short of a 5.

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

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

The description goes far beyond the annotations' readOnly/idempotent/destructive hints. It reveals that the bill payload has no embedded transactions, that transactions_basis may be a low-confidence estimate, that pending bills have no billId, that payments[] reflect the previous bill's payment, and that totalAmount is authoritative — none of this is inferable from the schema.

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 never wasteful: it uses clear sectioning and front-loads the core return fields before caveats. Every paragraph covers a distinct operational concern, and no sentence merely restates the tool name or schema field names.

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

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

Despite lacking an output schema, the description covers the response shape, batch errors, transaction-matching caveats, optional performance cost, authoritative total semantics, and paid-status pitfalls. An agent has the information needed to use this tool correctly and know what the results mean.

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

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

With 0% schema description coverage, the description must carry parameter meaning, and it does well for bill_ids, account_id, and include_transactions. However, it never explains transactions_detail or its enum values (compact/rich/raw), leaving a real gap for an agent deciding which detail level to request.

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 an explicit action and resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)'. It also distinguishes itself from bill listing and transaction listing tools by defining its exact output scope, including the optional transaction expansion.

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

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

It gives explicit routing guidance: use openfinance_list_credit_card_bills first to discover IDs, prefer that list tool for paid status, and optionally use openfinance_list_transactions for transaction retrieval. It also clarifies when to pass include_transactions and why the opt-in may be worth the extra cost.

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 convey read-only and idempotent behavior. The description adds valuable context about the reconnect_url (reopens widget in UPDATE mode without disconnecting or consuming a connection slot) and bulk execution support, which are not captured in annotations.

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

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

The description is well-structured and front-loaded. The first sentence packs in the core return values and behavior, followed by concise usage notes and a final line about bulk support. No filler or redundancy.

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

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

Given the lack of an output schema, the description adequately outlines the return structure (status, executionStatus, connector metadata, reconnect_url, and the `{ count, items }` shape for bulk calls). It covers primary usage patterns but omits edge cases such as error responses or pagination.

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

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

The schema has zero description coverage. The description explains the semantics of `item` (single vs all) and `item_ids` (bulk), but leaves `item_id` undefined and does not clarify its relationship to `item`. This partial coverage leaves ambiguity 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 identifies the tool's function: returning the current status of bank connections, with specific examples of statuses and additional data like executionStatus, connector metadata, and reconnect_url. It distinguishes itself from sibling tools like openfinance_list_connections by focusing on status and reconnect functionality.

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 usage context: omit `item` for all banks, pass `item` for a single bank, and use `item_ids` for bulk. However, it does not explicitly name alternative tools for when not to use this tool, or mention exclusion scenarios.

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, so the description need not repeat safety. It adds the GET endpoint, the `{ results, errors }` batch shape, and the array limit, which are meaningful behavioral details 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 thorough but well-organized with a colon to introduce field groups and a clear separation of purpose, usage, and batch format. It is longer than ideal, yet every sentence conveys necessary detail.

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

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

For a read-only batch tool with no output schema, the description provides the return fields, parameter constraints, endpoint, and usage sibling. It is sufficiently complete 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?

Schema coverage is 0%, but the description compensates fully by explaining that `loan_ids` is an array (1-50) and that it is passed to the endpoint. This adds cardinality and usage semantics missing from 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?

Clearly states it 'Returns full loan contract detail by id' and enumerates specific fields, distinguishing it from sibling openfinance_list_loans. The verb-resource pairing is precise and the batch nature is clarified.

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

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

Explicitly instructs to 'Use after openfinance_list_loans to deep-dive on a specific contract,' providing when-to-use context relative to its sibling. The parameter limit (1-50) further guides proper usage.

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

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

Even though annotations already mark the tool read-only and non-destructive, the description discloses many non-obvious behaviors: `name` is the legal entity rather than the brand, credit `balance` is connector-dependent, `balance_notice` means a zero value should not be presented as no debt, `bankData` fields can lag, and `provider_incident`/`identity_notice` can invalidate normal interpretation. This goes far beyond the annotations and prevents serious misreporting by an agent.

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

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

The description is long, but every section earns its place by introducing a caveat that materially changes how the agent should interpret results. It front-loads the main purpose and then organizes edge cases into focused blocks. It is slightly more verbose than strictly necessary, but the density of useful information is high.

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 complete responsibility for explaining return values and edge cases. It covers the core fields, bank attribution, credit-bill semantics, provider incidents, identity notices, and bulk execution, giving an agent everything needed to call the tool and interpret its response correctly.

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

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

With 0% schema description coverage, the description takes on the parameter-semantics burden and largely succeeds: it explains the key `item` contrast, mentions `item_ids` for batch calls, and the BANK/CREDIT enum is already self-describing in the schema. However, `item_id`'s precise relationship to `item` is left implied rather than explicitly described, preventing a perfect score.

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

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

The opening sentence states a precise verb-resource pair ('Returns accounts for a bank connection') and explicitly lists the two account types and the payload fields. It also clarifies the all-banks vs single-bank behavior, making the tool's purpose and scope unambiguous even among many similar sibling tools.

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

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

The description explicitly tells the agent when to omit `item` (user asks for 'my accounts/cards' without naming a bank) and when to pass it. It also names `openfinance_list_credit_card_bills` as the correct alternative when standardized bill amounts are needed, and calls out `openfinance_force_sync` for reconciling stale derived fields.

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, so the description adds value by disclosing caching behavior and that the response is a single aggregated response with no batch ids. This goes beyond the structured fields and helps an agent understand repeated call semantics and output shape.

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 extremely concise: two sentences. The first sentence states the core function and endpoint, the second details the entry structure and usage nuances. Every sentence earns its place with no fluff.

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?

This is a low-complexity tool with no parameters and no output schema. The description fully covers the taxonomy structure, language options, caching, and cross-tool relationship with the update tool, making it complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to add parameter information, and it correctly focuses on the return field meanings instead.

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 Pluggy's transaction category taxonomy (GET /categories) and provides specific detail about each entry's structure, including the id being the categoryId used by another tool. This distinguishes it from sibling tools like openfinance_list_transactions or 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 implies when to use it (e.g., to get valid categoryIds for openfinance_update_transaction_category, with caching for the adapter session) and notes a preference for descriptionTranslated for pt-BR users. However, it does not explicitly state when not to use it or name alternatives, so it falls short of a 5.

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

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

Annotations already indicate read-only and idempotent, but the description adds valuable contextual details: the reconnect_url opens the widget in UPDATE mode for existing connections, does not consume a connection slot, and does not require disconnection. This is beyond what annotations provide and is consistent 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?

The description is moderately sized but every sentence earns its place. It front-loads the core purpose, then explains the reconnect_url behavior and its exceptions. No fluff or repetition.

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

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

With no output schema, the description properly lists the return fields and explains the add_connection_url and reconnect_url behaviors. It covers the key usage scenarios and constraints, making the tool fully comprehensible for an agent.

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

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

This tool has zero parameters, so the baseline is 4. The description does not need to explain parameter syntax, but it still adds context about the return fields, which is helpful given there is no 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 the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes itself from sibling tools by focusing on connections and explaining the reconnect_url's update mode, which is unique.

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

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

The description provides explicit guidance on when to use the reconnect_url: for re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data). It also clarifies that it does not consume a connection slot and does not require disconnecting first, giving clear context for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds critical behavioral context: payment_status semantics, payment cycle timing, connector asymmetry, confidence levels for projections, and bill_grouping_reliability warning. No contradiction with annotations.

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

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

The description is long but front-loaded with the core result and caveats. Every major sentence adds value, though it could be tightened with headings or bullet points. The density is justified by the tool's complexity, but it is not concise by casual standards.

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

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

Given the tool's complexity (no output schema, 0% schema param descriptions), this description provides comprehensive coverage: return fields, derived status legend, alternative tools, connector-specific limitations, reliability warnings, and bulk support. It almost fully compensates for the lack of structured metadata.

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

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

Schema has 0% description coverage, so the description compensates well for include_open_bill (detailed semantics), account_ids (bulk support), and account_id (echo block). However, page and page_size parameters are not explained at all, leaving a minor gap.

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

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

The description clearly states it 'Returns CLOSED credit card bills for a CREDIT-type account' with specific fields. It distinguishes itself from siblings by explicitly contrasting with openfinance_list_transactions and openfinance_get_credit_card_bill (singular). The scope and resource are 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: use openfinance_list_transactions for itemized purchases, use include_open_bill for standardized pending debt instead of balance, and warns against cross-bank attribution. Also explains when open_bill is unavailable and to check the bank app.

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 false), the description adds rich behavioral detail: graceful fallback on 403/upstream errors with a warning field, data-integrity cross-checking when positions mass-zero out, the `data_integrity_warning` and `integrity:'suspect_zeroed'` flags, and explicit guidance not to treat suspect zeros as real balances. This far exceeds what annotations alone provide and does not contradict them.

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

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

The description is long but front-loaded with the purpose, then covers error handling and a critical data-integrity scenario. Every sentence delivers meaningful operational guidance, though the asset-type list and row-field enumeration could be trimmed or structured more tightly. Overall it earns its length for a financial data tool.

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, no output schema, and sparse parameter schema, the description covers return fields, error fallback shape, bulk support, and an important edge case with detailed handling instructions. It omits the normal top-level response shape and pagination/filter parameter behavior, which would make it fully complete, but it is still substantially informative.

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 description coverage, the description carries the burden but only mentions `item_ids` (for bulk support). It does not explain `item`, `item_id`, `page`, `page_size`, or `type` semantics, nor the distinction between `item`/`item_id`/`item_ids`. The enum for `type` exists but no guidance is given on its use as a filter.

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

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

The description uses a specific verb ('Returns') with a clearly identified resource ('investment portfolio for a connection') and enumerates the asset types included. It distinguishes itself from siblings like openfinance_list_investment_transactions by focusing on portfolio positions rather than transaction history.

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 the tool: for a connection with the INVESTMENTS product enabled, and it mentions bulk support via item_ids. However, it never explicitly contrasts this with alternatives (e.g., when to use openfinance_list_investment_transactions instead) or states 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by detailing the returned fields (quantity, value, netAmount, itemized expenses) and confirming bulk execution support. This goes beyond the structured annotations, though it does not cover pagination behavior or error cases.

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

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

The description is concise, using short paragraphs with every sentence providing value. It front-loads the core purpose in the first sentence, then details output fields and usage sequencing. No fluff or redundancy.

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

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

The tool returns a list with pagination parameters, but the description does not mention default page size, pagination behavior, or limits on bulk investment_ids. It thoroughly describes the output fields but omits operational details needed for effective invocation, making it adequate yet incomplete.

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 for parameter meaning. It explains investment_id (obtained from openfinance_list_investments) and investment_ids (batch support), but page and page_size are left undocumented. This is partial compensation with clear gaps for pagination 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 movement history for a specific investment position, listing specific transaction types (BUY, SELL, TAX, etc.). This distinguishes it from sibling tools like openfinance_list_transactions and openfinance_list_investments, which handle broader or different resources.

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

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

The description provides an explicit usage sequence: 'Use after openfinance_list_investments to get the investment_id.' It also mentions bulk support via investment_ids. However, it does not explicitly state when not to use the tool or name alternative tools for non-investment transactions, so it lacks exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it discloses that multiple connections are queried sequentially with rate-limit spacing, and that the return shape is `{ results, errors }` per connection. This gives the agent insight into performance and error handling without contradicting annotations.

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

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

The description is three sentences with no redundant content. It front-loads the core purpose and immediately covers parameter usage, behavior for multiple connections, and return format in a structured way. Every sentence 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?

For a simple tool with one optional parameter and no output schema, the description is complete. It provides the endpoint, parameter semantics, behavior for both modes, and return format. Given the annotations and sibling context, there are no significant gaps 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 description coverage (0%) for the `items` parameter, so the description carries the full burden. It fully explains that `items` is an array of connection selectors (item_id uuid, connector_id, or connector_name), how it is used (one entry per connection), and the behavior when omitted. This compensates completely for the schema's lack of detail.

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

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

The description clearly states the tool lists loan contracts per bank connection via the endpoint GET /loans. It distinguishes itself from sibling tools like openfinance_get_loan_detail by focusing on listing rather than individual details, and specifies the scope (per connection or all banks).

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

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

The description provides explicit guidance on when to pass `items` (to specify connections) and when to omit it (to list across all linked banks). It also explains that multiple connections are queried sequentially with rate-limit spacing. However, it does not explicitly mention alternatives like openfinance_get_loan_detail, though the purpose and sibling context imply the distinction.

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 substantial behavioral nuance beyond the annotations: it explains automatic pagination with a 5000-transaction ceiling, manual pagination semantics, per-connector variation in credit card pending/posting behavior, scheduled installment rows ordered at the top, the shape of error responses, and the presence of provider_incident blocks. It also explicitly says JSON attributes like scheduled, scheduled_count, and notice, and warns about sparse billId population on specific connectors. These behaviors go far beyond the readOnly/idempotent/destructive annotations and do not contradict them.

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

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

The description is extremely long and contains some redundancy, e.g., the warning against using billId to reconstruct bill totals appears more than once in slightly different form. However, the complexity of the tool and the total absence of schema description coverage justify almost all of the length. The text is moderately front-loaded with the core purpose and includes clear headings for special topics like PAGINATION and PENDING vs POSTED semantics, though a tighter version would remove repeated warnings.

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 complex behavior, eight parameters, and no output schema, the description provides remarkably complete context. It covers return structure, account echo, pagination, error handling, detail modes, credit-specific quirks, scheduling, date ordering, health check instructions, and provider incidents. While some nuances may vary per connector, the whole and clarifies that, which is the most important honesty for this API.

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 0% description coverage, so the description carries the full burden of explaining all eight parameters. It does this for account_id, from/to, detail, page/page_size, search_queries, and account_ids, adding concrete semantics, examples, default values, constraints, and behavioral caveats. For example, it explains that detail has 'compact', 'rich', and 'raw' modes and what each adds, and that using search_queries can aggregate 5000 transactions and requires narrowing from/to if truncated.

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

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

The description clearly states the tool's function: it returns transactions for a BANK or CREDIT account and explicitly calls itself the ONLY way to get itemized credit card transactions. It differentiates itself from sibling tools by referencing when to use openfinance_accounts, openfinance_list_credit_card_bills, and other alternatives, 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 provides explicit guidance on when to use this tool versus alternatives: it says to use openfinance_list_credit_card_bills for authoritative bill totals, openfinance_list_accounts for closing/due dates, and openfinance_get_item_status when a credit account returns 0 transactions. It also includes 'do-not' warnings such as 'Do NOT reconstruct a bill's total by summing transactions by billId' and explains when to avoid assuming the first row is the latest purchase.

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), the description discloses important behaviors: the 5000/account scan cap with `truncated:true`, the `provider_incident` block explaining incompleteness during provider incidents, and the effect of omitting `item`. No contradictions with annotations exist. This level of disclosure exceeds the bar set by annotations.

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

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

The description is long but every sentence carries useful information. It is front-loaded with the core purpose, then covers parameters, use cases, and caveats in a logical order. It could be slightly tightened, but the density is justified by the tool's complexity and the lack of schema descriptions. No redundant or filler sentences are present.

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 9 parameters, no output schema, and zero schema descriptions, the description is remarkably complete. It explains return elements (monthly evolution, top_despesas, by_account), row enrichment options, truncation behavior, provider incidents, and bulk support. Minor details like `top_n` control are not fully specified, but the overall context is sufficient for an agent to understand the tool's capabilities and limitations.

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 strongly. It explains `item` (connector_id, connector_name or item_id), `from`/`to` ISO dates, `granularity`, `detail`, `type`, and bulk `item_ids`. However, it does not explicitly explain `top_n` or the singular `item_id` parameter, which leaves some ambiguity. Despite this, the description adds substantial meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It specifies the main resource (transactions by item) and distinguishes it from siblings by mentioning it resolves accounts internally and supports batched execution. The scope and use cases are explicit.

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 usage instructions: 'Use this for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'.' It also gives guidance on when to use `granularity:'raw'` and `detail` values. It contrasts with `openfinance_list_accounts` but does not directly compare to the sibling `openfinance_list_transactions`, which is a minor gap. Overall, clear context with no misleading 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?

The description goes beyond the readOnlyHint annotation by explaining the tool queries a public status page, returns a global indicator, degraded components, open incidents, and specifically flags those affecting the user's connected banks. It also clarifies the scope (provider health) vs. connection status, adding meaningful behavioral context beyond annotations.

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

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

The description is a single focused paragraph of about 120 words, with the main purpose stated upfront, followed by usage guidance and output details. Every sentence adds information, and there is no redundant or filler content. It is concise yet complete.

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

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

Given the tool has no parameters, no output schema, and only basic read-only annotations, the description fully compensates by explaining the return value contents (global indicator, components, incidents, affected banks) and the usage scenario. This is comprehensive for a status-checking tool with this simplicity.

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

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

The tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters but does mention that `your_banks_affected` appears when banks are connected, which is output-related rather than parameter-related. This 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's function with a specific verb ('Checks') and resource ('LIVE operational status of the Open Finance provider'). It explicitly differentiates it from the sibling tool `openfinance_get_item_status`, which checks connection health, 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?

It provides explicit when-to-use guidance: whenever data looks incomplete or stale despite a connection showing UPDATED. It also explains what the tool reveals (upstream outage, known incident) and how it helps differentiate provider-side problems from connection issues, effectively stating when not to use it (for connection-level diagnosis).

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, and non-destructive, but the description adds significant behavioral context: the caveat warning about non-auto-updating connectors, plan-specific filtering, and the hint behavior when keywords are omitted. It also discloses that the tool never dumps the whole catalog. No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: main purpose, return fields, caveat, plan behavior, and usage timing. It is front-loaded with the core function and keyword examples, then layers necessary details without fluff.

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 covers return values (connector id, access, audience, linked connections, accounts, connect_url), edge cases (caveat warning, plan limitations), and usage prerequisites (keywords required, call before connecting). It is exceptionally complete for a tool of this 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 description fully explains both parameters: keywords[] with examples ('nubank','btg') and being required (despite schema not marking it required), and include_accounts=true to include accounts. Since schema coverage is 0%, this description compensates completely, adding meanings like the caveat and connect_url behavior tied to keywords.

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'), clearly stating it searches by name with keywords. It also distinguishes itself from sibling tools like openfinance_list_connections by focusing on available connectors and returning a connect_url, access, and audience. The plan behavior and caveat details further cement its unique purpose.

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

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

Explicitly instructs to call 'BEFORE connecting' and explains that keywords[] is REQUIRED, with a hint returned otherwise. It also advises preferring Open Finance connectors for automation when a caveat exists, and clarifies plan-based visibility (PF hides PJ, PJ covers both). This provides clear context on when and how to use the 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses important side effects: it overrides Pluggy's automatic categorization and automatically creates a Category Rule affecting future transactions. It also explains batch error handling (per-item errors do not fail the batch). This is rich behavioral context that annotations alone do not convey.

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

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

The description is efficiently structured: it opens with the core action, then parameter construction, then the behavioral nuance, then the use case, and finally the return shape. Every sentence adds necessary information, and the length is justified by the tool's complexity (batch behavior, rule creation, return shape).

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 the return shape explicitly, including the structure of `results` and `errors`. It also covers the side-effect of Category Rule creation and the source of parameter values, making it fully self-contained for an agent to 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?

Schema coverage is 0%, so the description carries the full burden for parameter explanation. It clarifies that `items` is an array of objects, and explains the provenance of `transaction_id` and `category_id` from specific sibling tools. This exceeds the schema's minimal type definitions, making parameter usage unambiguous.

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 begins with a specific verb+resource: "Corrects the category of one or more transactions (PATCH /transactions/:id)". This clearly states what the tool does and distinguishes it from sibling list/category tools. It also mentions batch capability, which further disambiguates.

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 states when to use it: "use this to fix miscategorized transactions and improve categorization accuracy going forward." It also tells the agent where to obtain the required IDs from openfinance_list_transactions and openfinance_list_categories, effectively providing usage context. It does not name a direct alternative, but none exists among siblings for updating categories.

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=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the conversation array is needed for reproduction, which is useful but does not disclose what happens after reporting (e.g., how the feedback is processed). This adds some but not rich behavioral context.

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

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

The description is two short sentences, front-loaded with the purpose and ending with a practical instruction. Every word earns its place; no wasted 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?

For a simple 3-parameter tool with no output schema, the description is decent but has notable gaps. It omits explanation of the context parameter and does not mention any return/confirmation behavior. Annotations help, but 0% schema coverage increases the description's burden.

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 explicitly explains the conversation parameter and implicitly covers message ('Report a bug...'). However, the context parameter is not mentioned, leaving a gap in 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 the tool's function with a specific verb and resource: 'Report a bug, missing feature, or send feedback.' It is distinct from all sibling tools, which focus on financial data operations, so purpose clarity is high.

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 usage guidance: 'Include the conversation array with recent messages for reproduction.' This tells the agent what to provide when invoking the tool. While no alternatives are mentioned, no sibling tool offers bug reporting, so the guidance 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful behavioral context by clarifying that the tool returns both platform and adapter versions, which goes 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?

A single, front-loaded sentence conveys the complete purpose with no wasted words. It is appropriately sized for the tool's simplicity.

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

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

For a parameterless, read-only version query with strong annotations and a clear description of what it reports, nothing essential is missing. The output is simple and adequately described 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 there is nothing for the description to explain. The baseline of 4 is appropriate since the schema is trivially complete and no parameter clarification is needed.

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

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

The description uses a specific verb ('Show') and identifies the exact resource ('current MCP platform and adapter versions'), making the tool's purpose unambiguous. It also distinguishes itself from sibling tools like toolkit_info by specifying version information rather than general toolkit 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?

The usage context is implied: use this when version information is needed, likely for debugging or support. However, there is no explicit when-to-use guidance or mention of alternatives, which would help an agent decide between this and similar informational tools.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these flags by specifying what 'state' includes (installed MCPs, connection status, accounts, catalog tool counts), giving the agent a realistic expectation of the returned data without needing to guess.

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 that contains no filler. Every phrase adds substantive detail about the return value, making it both concise and information-dense.

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

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

For a read-only, zero-parameter informational tool, the description is complete. It names all major return categories (installed MCPs, connection status, connected accounts, count of catalog tools), which is sufficient for an agent to know what to expect. No output schema exists, but the description covers the essential return structure.

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?

This tool has zero parameters, so the baseline score is 4. The description correctly implies no arguments are needed, and the input schema is empty. There is nothing more to explain about parameter 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?

The description uses the specific verb 'Returns' and identifies the resource as 'current toolkit state', listing concrete components (installed MCPs, connection status, accounts, catalog tool counts). This clearly distinguishes it from siblings like 'show_version' or 'openfinance_provider_status', which focus on narrower or different aspects.

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: it is the tool for an overview of the toolkit's current state. It does not explicitly mention alternatives or exclusions, but the scope is self-evident and no other sibling seems to offer the same general status summary. Lacks explicit 'when not to use' but is not misleading.

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