Next MCP

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

Annotations indicate idempotentHint=true. The description explains that calling without args returns a link, and calling with token sets it. It does not contradict annotations and adds context about the login flow, though it does not mention error handling or multiple calls.

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 informative but slightly verbose; it could be more concise by separating the two methods more cleanly. However, it is well-structured and serves its purpose without filler.

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

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

Given the tool has one optional parameter and no output schema, the description covers all necessary aspects: what the tool does, how to use it in two scenarios, and what the token is. 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 has 0% coverage for parameter descriptions, but the description fully explains the 'token' parameter: it is a JWT from browser login, and how to use it for session or permanent login. This significantly adds meaning beyond the raw schema.

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

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

The description clearly states the tool is for authentication, specifying that it returns a login link or accepts a token for session login. It distinguishes itself from sibling tools, which are unrelated to authentication.

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

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

The description provides two clear usage methods: permanent configuration via config header or session login by pasting a token. It also mentions calling with no args to get the link. However, it does not explicitly state when not to use the tool or name specific 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 safety traits (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds behavioral details about return values in different scenarios, which goes beyond annotations.

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

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

Two sentences: first states the purpose, second elaborates on two possible outcomes. No wasted words, well-structured.

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

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

Given no output schema, the description adequately covers the two possible return states. For a simple status tool with no parameters, it is 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?

No parameters exist, so baseline is 4. The description does not need to add parameter info.

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

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

The description clearly states the tool returns connection status and URLs, and explains the two scenarios (all connected vs missing credentials). It distinguishes from siblings like 'authenticate' by focusing on status rather than performing authentication.

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

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

The description implies usage as a status check tool, but does not explicitly state when to use it versus alternatives or when not to use it. However, the context is clear for a read-only status endpoint.

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

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

The description adds substantial behavioral context beyond the annotations: invoke works even when the MCP is not installed, appears as a one-off without bloating the tool list, returns connect/checkout links when credentials or payment are needed, and the one-off install behind invoke requires workspace owner/admin. It also clarifies that search/describe flag installation status and that the prompt library has its own distinct lifecycle.

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 block of text but is logically organized: core flow, key invoke behavior, install vs invoke, types of writes, permissions, and the prompt library. Every sentence contributes meaningful information, though the length makes it harder to scan quickly. It is appropriately detailed for the tool's complexity, but not broken into bullet points.

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

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

Given the tool's complexity (14 actions, 23 parameters, no output schema), the description covers the overall workflow, edge cases (uninstalled MCPs, auth, payment), permission requirements, and the separate prompt library. It provides enough context for an agent to select the right action and understand return behaviors, including retry logic after connect/checkout links.

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% coverage in the description, but the description explains the central 'action' parameter and the typical parameters (action=search, describe, invoke, etc.) in the workflow. It also gives context for tool_id, arguments, prompt-related fields, and billing actions. However, many parameters (limit, query, immediate, tier_slug, etc.) are not explicitly explained, so the description does not fully compensate for the low schema coverage.

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

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

The description begins by identifying the tool as the official mcp.ai marketplace, which is the catalog of every MCP/tool, and clearly states it is the way to run them. It enumerates the specific actions (search, describe, invoke, install, etc.) and the overall intent coverage, making it distinct from the openfinance_* and utility siblings.

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

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

The description explicitly details when to use invoke over install ('prefer invoke for a single/occasional use'), when install is appropriate ('to make an MCP PERMANENT'), and maps each action to its purpose. It also lists permission requirements for writes, and explains the auth and payment flows (connect link, checkout/top-up) that affect retry behavior.

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 destructiveHint=true and readOnlyHint=false. Description adds context about returning a reconnection URL but no new behavioral traits. No contradiction.

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

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

Two sentences, no fluff, efficiently conveys the action and result. Front-loaded with key verb 'revokes'.

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 and no output schema, the description covers the action and return value. Missing explanation of 'item' but otherwise complete.

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

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

Schema has 0% description coverage. The description does not explain what the parameter 'item' represents (e.g., bank ID or connection ID), leaving ambiguity for the agent.

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 consent and deletes connection data, with a specific verb and resource. It distinguishes from siblings like openfinance_list_connections and openfinance_force_sync.

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

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

Implies usage for disconnecting a bank when data is no longer needed, but no explicit when-to-use or when-not-to-use guidance. No mention of alternatives like temporarily pausing.

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

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

The description adds significant behavioral context beyond annotations: it mentions the tool waits and polls up to ~60s, describes the return format including edge cases like 'needs_action' and 'timed_out', and clarifies that it does not disconnect/reconnect. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with this, so no contradiction.

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

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

The description is front-loaded with the core action and then provides necessary details in a logical order. Every sentence adds value, and it is concise given the complexity of the tool. 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 tool has 2 parameters and no output schema, the description covers return format, edge cases (needs_action, timed_out), and behavioral details. It is complete and leaves no ambiguity about what the tool does and how to use it.

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 both parameters: 'wait' (boolean, default behavior and fire-and-forget) and 'items' (array of selectors, omitting syncs all). This provides clear meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish'. It uses a specific verb and resource, and the behavior is distinctly described, differentiating it from sibling tools like openfinance_get_item_status which is for 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?

The description explicitly states when to use this tool: 'Use this when a balance or transaction list looks stale'. It also mentions when not to use it (no need to disconnect/reconnect) and provides an alternative for fire-and-forget using 'wait: false'. It even suggests re-checking with openfinance_get_item_status if timed out.

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

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

Goes beyond annotations by detailing that CREDIT accounts may return BALANCE_FETCH_ERROR with a warning, and that degradation to last-synced balance occurs with realtime: false when upstream is unavailable or connector is not Open Finance. Annotations only provide readOnly and idempotent hints.

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 a single paragraph with multiple sentences, efficiently covering endpoint, parameters, error handling, and response shape. Could be slightly more structured, but no redundancy.

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

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

No output schema exists, but the description explicitly provides the response shape ({ results, errors }) and explains key behaviors like warnings and degradation. This makes the tool's usage completely clear.

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, but the description fully compensates by explaining account_ids is an array of 1–50 strings, and adds context about warnings and degradation. This adds significant meaning beyond the raw schema.

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

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

The description clearly states it returns real-time balance payload per account id, specifying the endpoint GET /accounts/:id/balance. It distinguishes from siblings like openfinance_list_accounts and openfinance_get_accounts_detail by focusing on balance retrieval.

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

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

Specifies to pass account_ids as an array (1–50) and explains error handling and degradation conditions. While it does not explicitly say when to use this tool vs alternatives, the context of balance fetching is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds the batch response shape and the provider_incident block, which warns that credit limits and balances may be unreliable. This goes beyond the 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 efficiently states the purpose, parameter requirement, and a critical warning about provider_incident. It is front-loaded with the main function. The provider_incident explanation is lengthy but necessary for safe use. Could be slightly more concise but overall 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 the single parameter, no output schema, and simple semantics, the description covers the key aspects: endpoint, batch mode, parameter constraint, and reliability caveat. It is sufficient for an agent to select and use the tool correctly, though it could optionally describe the return fields more.

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 0% description coverage for the only parameter. The description explains that account_ids must be an array (1–50) and that the tool returns batch results. This adds essential meaning beyond the schema, though it does not specify string format or examples.

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

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

The description clearly states it returns full account objects with extended creditData per ID, and specifies the endpoint (GET /accounts/:id). This distinguishes it from sibling tools like list_accounts (summary) and get_account_balance (balance only).

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

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

The description specifies that account_ids should be passed as an array (1–50) and mentions the batch shape {results, errors}. It warns about provider_incident affecting reliability. It does not explicitly contrast with alternatives, but the context of sibling tools implies use for detailed account info. Clear 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?

Discloses that it does NOT return individual transactions, notes inconsistency of creditCardMetadata.billId, explains that payments[] may reflect previous bill payment, and mentions batch shape. 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?

Long but every sentence adds value. Well-structured: purpose, exclusions, alternatives, parameter guidance, caveats. Slightly verbose but acceptable.

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

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

For a tool with one parameter and no output schema, the description provides exhaustive context: usage, parameter, behavioral nuances, and limitations. Complements annotations well.

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 only parameter bill_ids is fully explained: it is an array, and the description advises to use openfinance_list_credit_card_bills first to discover ids. Schema coverage is 0%, so description compensates completely.

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

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

Clearly states the tool returns bill-level detail for credit card bills by id, specifying fields included. Differentiates from sibling tools like openfinance_list_transactions and openfinance_list_credit_card_bills.

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

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

Explicitly explains when to use this tool vs alternatives: for itemized transactions use openfinance_list_transactions, to find bill ids use openfinance_list_credit_card_bills. Also warns against reconstructing totals.

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: explains reconnect_url reopens widget in UPDATE mode without disconnecting or consuming a slot. Discloses idempotent read-only nature consistent 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?

Three sentences, front-loaded with key purpose, followed by usage variants and bulk support. No unnecessary words, every sentence adds critical 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?

Explains return fields (status, executionStatus, etc.) and behavior of reconnect_url. Mentions example statuses. Missing details about response structure for bulk mode and does not cover the 'item_id' parameter, but overall adequate for a read-only tool with annotations.

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

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

Describes usage for 'item' and 'item_ids' parameters clearly, but does not explain 'item_id' parameter, leaving its role ambiguous. With 0% schema coverage, description should cover all 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, connector metadata, reconnect_url). Distinguishes between single and bulk usage, and differentiates from siblings 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?

Provides clear usage patterns: omit item for all banks, pass item for a single bank, use item_ids for bulk. However, it lacks explicit comparison to sibling tools like openfinance_list_connections or when not to use this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds batch return shape { results, errors } and array size limit, which are behavioral traits beyond annotations. No contradiction.

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

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

Two sentences plus a list of returned fields. Efficient and informative with no fluff. Could be slightly better structured, 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 1 parameter, no output schema, and good annotations, the description is complete enough: it explains what to pass, what to expect, and how to use it alongside siblings. Minor gaps like error handling are not critical.

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

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

Schema has 0% description coverage; the description compensates by specifying that loan_ids is an array of (1-50) strings and explaining return shape. This adds significant meaning beyond the minimal 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 full loan contract details by ID, lists specific fields, and explicitly distinguishes from sibling openfinance_list_loans by advising to use it after that tool for 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 clear usage guidance: use after openfinance_list_loans and pass loan_ids as array (1-50). Does not explicitly mention when not to use or alternatives, but the context is sufficient.

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

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

Annotations already show readOnlyHint, idempotentHint, and destructiveHint. The description adds critical context: credit balance connector-dependence, provider_incident risks, identity_notice deduplication, and batch support.

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 serves a purpose. It is structured logically: starting with core functionality, then parameter usage, then caveats and special cases, and finally batch support.

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 fully explains what the response contains (fields like bank, connector_id, account details) and special blocks (provider_incident, identity_notice). It is thorough for a list tool.

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

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

Input schema has 0% description coverage, but the description explains each parameter's usage: omitting 'item' lists all accounts, passing 'item' targets one bank, and 'item_ids' for batch. It also explains the 'type' enum.

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 accounts for bank connections, distinguishing between BANK and CREDIT types. It specifies the resource and verb, and differentiates from sibling tools like openfinance_list_credit_card_bills.

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

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

Provides explicit guidance on when to omit or include the 'item' parameter, explains the credit balance caveat, provider_incident, and identity_notice. It also directs users to another tool for standardized bill amounts.

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 safe read; description adds caching behavior, single aggregated response, and field-level tips (e.g., preferring descriptionTranslated for pt-BR users). Adds useful 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?

Three sentences, each essential. First states purpose and caching, second details output fields, third clarifies no batch ids. No fluff, front-loaded.

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

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

Complete for a simple list tool with no parameters and good annotations. Covers what it returns, how to use the output for other operations, and provides internationalization tip. No gaps.

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

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

No parameters, so schema coverage is 100%. Baseline per instructions is 4. Description does not need to add param info, but it explains output fields which indirectly aids 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?

Clearly states the tool returns Pluggy's transaction category taxonomy, specifying the GET /categories endpoint, caching, and field details. Distinguished from siblings by name and content; no ambiguity.

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?

Mentions that the id field is used by openfinance_update_transaction_category, implying a use case, but no explicit when-to-use or when-not-to-use guidance compared to alternatives. Adequate for a tool with no similar siblings.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that the reconnect_url opens the widget in UPDATE mode and refreshes in place, and specifies it does not consume a connection slot. This enriches the agent's understanding of the tool's 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?

Two sentences, each adding value. The main purpose is front-loaded. Could be slightly more concise, but overall efficient.

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

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

With no parameters and no output schema, the description fully explains the returned fields and their meanings. It covers reconnect and add_connection URLs but doesn't mention ordering or limits. Adequate for a simple list tool.

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

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

There are no parameters; schema coverage is 100%. Baseline score of 4 applies as the description does not need to explain 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 it returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It explains the purpose of each URL, distinguishing the tool's functionality from others like openfinance_disconnect_bank.

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 guides when to use the reconnect_url (for re-authentication, MFA, LOGIN_ERROR, stale data) and clarifies its behavior (does not consume slot, no disconnect needed). However, it does not compare this list tool to sibling tools like openfinance_list_accounts.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds rich behavioral context: the derived payment_status logic, cycle dates, cross-bill payment matching, connector asymmetry for open bills, bulk support, and warning instead of failure if product not enabled. 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 well-structured, with clear sections and front-loaded with core functionality. Every sentence adds value, and the level of detail is appropriate for the complex Brazilian Open Finance semantics.

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

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

No output schema, but the description thoroughly explains return fields: dueDate, totalAmount, payments[], payment_status, open_bill, future_bills, etc. It also covers edge cases like connector asymmetry, warning, and account echo block. Complete for the tool's purpose.

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%, but the description compensates for most parameters: explains include_open_bill in detail, account_ids for bulk, and account_id is clear from required. However, page and page_size parameters are not explained beyond their names, which is 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, listing specific fields. It distinguishes from siblings like openfinance_get_credit_card_bill (singular) and openfinance_list_transactions (transactions vs bills).

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

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

Provides extensive guidance: when to use include_open_bill, how to interpret payment_status, not to assume payment[] means paid, cross-check account echo, and alternatives like openfinance_list_transactions for itemized purchases. Also warns about connector limitations and billId inconsistencies.

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

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

Annotations already indicate safe read-only operation (readOnlyHint, idempotentHint, destructiveHint all favorable). The description adds significant value by detailing error handling (returns warning instead of throwing), a comprehensive data integrity check for mass zeroing with 'suspect_zeroed' flags, and guidance on treating such balances as unavailable. 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 front-loaded with the primary purpose but becomes verbose in the data integrity section, which could be condensed. It is structured with clear sections but would benefit from trimming redundant explanations.

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 structure (total, results, warning) and mentions key fields. It covers error handling and data integrity. Minor gaps remain, such as pagination behavior for 'page' and 'page_size', but overall it is thorough for a read-only portfolio listing tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'item_ids' parameter for bulk execution and implies the 'type' parameter via enum values. However, core parameters like 'item', 'page', and 'page_size' are not described; their purpose must be inferred from the tool's operation.

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

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

The description clearly identifies the tool as returning an investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.) and fields (balance, amount, dueDate, etc.). It distinguishes from sibling tools like 'openfinance_list_investment_transactions' by focusing on portfolio positions rather than transactions.

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

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

The description implicitly indicates usage for retrieving portfolio data, provides context for when the INVESTMENTS product is not enabled (returns a structured response), and mentions bulk support via item_ids. However, it does not explicitly state when to use this tool over siblings, such as 'openfinance_list_accounts' or 'openfinance_list_investment_transactions'.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by detailing the returned fields (quantity, value, expenses breakdown), but does not disclose behavior like pagination limits, sorting, or error conditions.

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

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

Three sentences with no extraneous information. The purpose is front-loaded, followed by usage guidance and bulk support note. Every sentence adds value.

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

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

Given the moderate complexity (4 params, no output schema), the description covers the core purpose, prerequisite, and bulk mode. However, it lacks documentation for pagination parameters and does not explain the return structure beyond listing fields, leaving some gaps.

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

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

Schema description coverage is 0%, so descriptions must compensate. The description explains the purpose of 'investment_id' and 'investment_ids' (bulk support), but omits any explanation for 'page' and 'page_size', leaving those parameters semantically undocumented.

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 an investment position, listing specific transaction types (BUY, SELL, TAX, etc.). It differentiates from the sibling tool 'openfinance_list_investments' by specifying it is a follow-up to that call, and its resource is transaction history vs. investment positions.

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 instructs to use this tool after 'openfinance_list_investments' to obtain the investment_id, and notes bulk support via 'investment_ids'. This provides clear context and prerequisite, but does not discuss when to avoid using it or compare with other list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: sequential querying with rate-limit spacing for multiple connections, and per-connection result/error format, which is valuable beyond annotations. No contradiction.

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

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

Three sentences with clear structure: first sentence states purpose and endpoint, second explains the items parameter, third covers the omission case. No redundant or wasted words.

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

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

Given no output schema, the description adequately explains return format (`{ results, errors }` per connection) and covers both usage modes. Combined with annotations, the tool definition is complete for an agent to use correctly.

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

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

The single parameter `items` is explained in detail: it accepts an array of connection selectors (item_id uuid, connector_id, or connector_name), with one entry per connection. This adds significant meaning beyond the bare schema definition, which lacks description (0% coverage).

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

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

The description clearly states the tool lists loan contracts per bank connection, specifying the HTTP method and endpoint (GET /loans). It distinguishes from sibling tools like openfinance_get_loan_detail by focusing on listing multiple loans.

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 pass `items` (for specific connections) and when to omit it (to list across all banks). It also mentions sequential querying with rate-limit spacing, aiding safe usage. However, it does not explicitly mention when not to use this tool (e.g., for a single loan detail), though this is implied by sibling names.

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 numerous behavioral details beyond annotations: varying coverage by connector, credit card pending vs posted behavior, that creditCardMetadata.billId is a non-authoritative hint, error handling with warning/error instead of throwing, and the provider_incident block. It also explains auto vs manual pagination and the effect of detail levels. 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 well-structured with logical sections. It front-loads the core purpose. There is minor repetition regarding the billId hint, and some paragraphs could be slightly tighter. However, every sentence adds value given the tool's complexity. It is appropriately sized for the depth of 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?

Given the tool's complexity (credit vs bank, pagination, search, detail levels, error handling, bulk), the description covers all necessary context. It references sibling tools for related operations (openfinance_list_accounts for closing dates, openfinance_get_item_status for connection health). Without an output schema, it describes response structure including account echo, results, and provider incidents.

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 fully explains all 8 parameters: account_id (required), from/to (ISO date filters), search_queries (case-insensitive substring OR), page and page_size (auto vs manual pagination), detail (compact/rich/raw with semantics), and account_ids (bulk). Every parameter's meaning and usage is clarified.

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 transactions for BANK or CREDIT accounts, with specific verb and resource. It distinguishes from siblings like openfinance_list_credit_card_bills and openfinance_list_transactions_by_item, ensuring the agent knows when to use this 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?

The description provides explicit guidance on when to use the tool (e.g., for credit card itemized transactions) and when not (e.g., using openfinance_list_credit_card_bills for standardized bill totals). It also advises on pagination strategies, handling truncated results, and checking connection health when total is zero. Alternatives are clearly named.

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 behavioral details beyond the annotations: a scan cap of 5000 transactions per account with a `truncated:true` flag, and a potential `provider_incident` block when the Open Finance provider has an open incident. These are not captured by the annotations (readOnlyHint, idempotentHint, destructiveHint) and are critical for the agent to understand limitations.

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 efficient, front-loading the core purpose and then systematically covering options, edge cases, and limitations. Every sentence adds value, and the structure is logical: purpose, parameter explanations, output format, and warnings. For a tool with 9 parameters and multiple modes, this is appropriately 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?

The tool is complex with no output schema, but the description fully covers the return structure: the compact summary (entradas, saídas, saldo_liquido, por_mes, top_despesas/recebimentos, by_account), the raw granularity output, truncation flag, and provider_incident block. It also explains the behavior when `item` is omitted (analyze all linked banks). There are no gaps.

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

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

The schema description coverage is 0%, so the description bears full responsibility. It explains all 9 parameters: `item` (connector_id, connector_name, or item_id), `from`/`to` (ISO dates), `granularity` (monthly/raw), `detail` (compact/rich/raw), `type` (BANK/CREDIT), `top_n` (implied in top_despesas/top_recebimentos), `item_id`, and `item_ids`. Each parameter's purpose and allowed values are clearly described in 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 the tool's purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It specifies the resource (bank connection) and the action (analyze transactions), and distinguishes from sibling tools by emphasizing that it resolves accounts internally, eliminating the need to call openfinance_list_accounts.

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

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

The description provides explicit guidance on when to use this tool, including scenarios like 'análise anual/mensal', 'fluxo de caixa', etc. It explains the options for granularity and detail, and explicitly states that you do not need to call openfinance_list_accounts first. It also mentions bulk support with item_ids, giving comprehensive usage instructions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by detailing the return data (global indicator, degraded components, incidents, your_banks_affected) and the side effect of flagging incidents for connected 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 somewhat long but well-structured, front-loading the main purpose and then providing usage context and return information. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Despite lacking an output schema, the description thoroughly explains what the tool returns (global indicator, degraded components, open incidents, your_banks_affected). For a tool with no parameters and a clear diagnostic function, this is complete and self-contained.

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

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

The tool has zero parameters, and schema description coverage is 100%. The description does not need to add parameter semantics. Baseline 4 is appropriate as it correctly omits irrelevant parameter details.

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

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

The description uses specific verbs ('Checks the LIVE operational status') and clearly identifies the resource ('Open Finance provider status page'). It explicitly distinguishes itself from the sibling tool 'openfinance_get_item_status' by stating what it checks (provider health vs. connection 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 provides explicit when-to-use instructions (when data looks incomplete or stale despite a connection showing UPDATED) and differentiates from an alternative ('openfinance_get_item_status'). It clearly states the diagnostic purpose of separating provider-side issues from connection issues.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, indicating safe read behavior. The description adds beyond that: it explains that keywords are required (or returns a hint), details plan-based filtering, and warns about the caveat for non-Open-Finance connectors. 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 slightly long but well-structured: it starts with the main purpose, then details the return values, and ends with usage caveats. Every sentence adds value, and there is no redundancy. Minor improvement could be shortening some clauses.

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 only 2 parameters and no output schema, the description covers all needed context: when to call (before connecting), what it returns (id, access, audience, accounts, connect_url, caveat), plan-dependent behavior, and the hint on missing keywords. It feels complete for a search 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?

Despite 0% schema description coverage, the tool description fully explains both parameters: keywords (array of strings, required, example given) and include_accounts (boolean for including accounts). It adds purpose and usage examples beyond the schema's types, 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 keywords, returns specific fields (id, access, audience, links, connect_url), and differentiates from siblings like 'connect' and 'marketplace' by specifying its role as a pre-connect search. It also explains the behavior without keywords (returns a hint), making the purpose unmistakable.

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

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

The description explicitly says 'Call this BEFORE connecting', provides context about plan-based filtering (PF hides PJ banks), and advises surfacing the caveat. However, it does not explicitly state when not to use it or compare to alternatives like 'marketplace', though the context given is strong.

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

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

Goes beyond annotations by explaining the side effect of creating a Category Rule (teaching Pluggy) and batch error handling. Annotations only give readOnlyHint=false, but description adds critical 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?

Single well-structured paragraph starting with action, then input, effect, output. No wasted sentences; every sentence adds value.

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

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

Given no output schema, description provides full response shape. Covers input, side effects, and error handling. Sufficient for an agent to correctly invoke the tool.

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

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

Schema has 0% description coverage, so description carries full burden. It thoroughly explains the items array, required fields, where to get IDs, and the batch response shape. Adds complete 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?

Description clearly states it corrects transaction categories via PATCH /transactions/:id. It specifies the input format (array of transaction_id and category_id) and the effect, distinguishing it from sibling listing 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?

Explicitly states when to use: to fix miscategorized transactions and improve future categorization. Provides source of IDs from list tools. Lacks explicit 'when not to use' but strong positive guidance.

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

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

Annotations already indicate idempotent and non-destructive writes. The description adds that including conversation is needed for reproduction, which is helpful behavioral context but does not disclose if there are side effects, rate limits, or return behavior beyond that.

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 concise sentences with no wasted words. It is front-loaded with the core purpose and immediately provides an actionable tip.

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 (reporting bug/feedback) and lack of output schema, the description is minimally complete. It tells the agent what to include but does not explain the return value or confirm submission, which could be useful.

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 3 parameters with 0% description coverage. The description only covers the 'conversation' parameter by mentioning it should be included for reproduction. The 'context' parameter is not explained, and 'message' is self-evident. This partially compensates but leaves 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 the tool is for reporting bugs, missing features, or sending feedback. It identifies the resource and action, and is distinct from sibling tools which are unrelated to feedback. However, it could be more specific about the scope of '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 advises including the conversation array for reproduction, which gives a usage hint. However, it does not provide explicit guidance on when to use this tool vs alternatives (though none exist among siblings), nor does it state any prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds specific output detail (platform and adapter versions), providing behavioral context beyond annotations without contradiction.

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

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

Single, front-loaded sentence with no redundant words. Every word serves a purpose.

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

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

Given low complexity, no parameters, no output schema, and strong annotations, description fully covers what the tool does. No missing context for effective 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?

No parameters, and schema description coverage is 100%. Description adds no parameter details, which is acceptable given zero 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?

Description clearly states it shows platform and adapter versions. Verb 'show' directly indicates action, and resource is precise. Distinguishes well from sibling tools which are either authentication or openfinance-specific.

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

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

No explicit when-to-use or alternatives mentioned, but the tool's simplicity implies it is the go-to version check. Usage guidance is implied rather than stated.

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 specific details about the returned state (MCPs, status, catalog counts) 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?

Single sentence, front-loaded with the core action and result. 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?

For a simple info tool with zero parameters and good annotations, the description fully covers what the agent needs to know.

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

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

No parameters exist, so the description does not need to explain them. Baseline 4 is appropriate as the description adds no parameter info but none is needed.

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

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

The description clearly states the tool returns 'current toolkit state' with specific fields (installed MCPs, connection status, catalog tool counts). This distinguishes it from sibling tools like 'connect' or 'marketplace'.

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

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

The description implies usage for checking status but does not explicitly state when to use it versus alternatives, nor provide exclusions.

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