Dock MCP

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

Annotations show idempotentHint=true and destructiveHint=false. Description adds context about permanent vs session behavior, and how to obtain the link when called with no args. No contradiction.

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

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

Two sentences, front-loaded with purpose. Every word adds value. No redundancy.

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

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

Completely describes the tool's behavior for both token and no-args calls. No output schema needed; the outcomes are 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 1 optional parameter 'token' with no description. Description fully explains its purpose: paste token for session login, or omit to get link. Compensates for 0% 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?

Clearly states the tool is for authentication, with specific actions: log in via browser or provide token. Distinguishes from sibling tools like connect and 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?

Provides explicit instructions for two usage scenarios (permanent config vs session-only token), and implies when to use each. No explicit alternatives needed since siblings are unrelated.

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 return behavior in different states (connected vs missing credentials), which adds value beyond annotations that already declare safety (readOnlyHint, idempotentHint).

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

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

Two sentences, front-loaded with main purpose, no wasted words. 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?

Given no output schema, description sufficiently covers key return fields and behavior. Could mention that output is in JSON format, but not necessary for completeness.

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

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

No parameters exist; schema coverage is 100%. The description explains the tool's purpose, meeting the baseline expectation for zero-parameter tools.

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

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

Describes specific verb ('Returns') and resource ('connection status and URLs'), with distinct scenarios for connected vs missing credentials. Could be more explicit about what 'connection status' entails beyond the given fields.

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 checking authentication state before actions, but no explicit when-to-use or when-not-to-use compared to sibling tool 'authenticate' or others.

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 annotations by detailing behavioral traits: writes require owner/admin permissions, invoke returns connect/checkout links for missing credentials or insufficient wallet, and the one-off install does not bloat the toolkit. 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 verbose (over 500 words) and contains redundant phrasing like 'THE official' and expansive explanations. While it front-loads the core flow, it could be more concise without losing essential 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?

Despite high complexity (13 params, no output schema), the description covers the overall workflow, actions, permission requirements, and exceptional behaviors (credentials, payment). Lacks parameter-level details and return values for most actions, but is largely complete for usage understanding.

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

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

Schema coverage is 0% for parameters. The description mentions 'action' and its values (search, describe, invoke, etc.) and implies usage of mcp_id and tool_id, but does not systematically explain each of the 13 parameters. Partial compensation but insufficient for low 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 identifies the tool as the official mcp.ai marketplace for discovering and running MCPs. It lists specific actions (search, describe, install, etc.) and distinguishes itself from sibling tools by being the primary entry point for MCP management.

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 first before external registries, and differentiates between invoke and install for temporary vs. permanent usage. It also explains when to use subscribe/cancel, report_bug, request_mcp, and lists_tools as 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?

Beyond annotations (destructiveHint: true), the description adds that the data becomes unavailable and returns a reconnection URL. This informs the agent of irreversibility and potential next steps.

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 redundant words, front-loaded with action and consequences. Efficient and clear.

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

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

For a simple tool, the description covers the main action and outcome but fails to parameterize properly. Missing explanation for 'item' makes it incomplete for precise invocation.

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

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

The only parameter 'item' is not explained in the description. Despite 0% schema coverage, the description does not clarify what the parameter represents or how to specify the bank. This leaves the agent guessing.

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

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

The description clearly states the action ('Revokes... consent and deletes connection data') and the resource (bank). It distinguishes from siblings like connect or list_connections by specifying it's a disconnect operation.

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 describes when to use: to disconnect a bank and that data will be unavailable. It implies no further access, and provides a reconnection URL, helping the agent understand consequences. Siblings like connect are 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?

Adds significant context beyond annotations: waits up to 60s, polls, returns fields like status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out. Annotations only indicate non-readonly, description fully explains mutation behavior.

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

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

Single paragraph, front-loaded with core action. Every sentence adds value, though slightly dense; could be broken into sections but still clear.

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

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

Given no output schema, description fully explains return structure, edge cases (timed_out, needs_action), and all parameters. Self-contained and 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?

Schema coverage is 0%, but the description fully explains both parameters: `items` as an array of selectors or omit for all, `wait` as boolean with behavior details. 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?

The description clearly states the action: 'forces the bank to re-sync one or more connections NOW and WAITS for it to finish'. It distinguishes from other tools by not disconnecting/reconnecting and mentions the specific endpoint and polling behavior.

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

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

Explicitly says when to use: 'when a balance or transaction list looks stale'. Provides alternative when it times out: 're-check with openfinance_get_item_status'. Also offers fire-and-forget option with `wait: false`.

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

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

Annotations confirm readOnlyHint and idempotence. The description adds value by detailing error handling for CREDIT accounts (non-throwing) and the response structure, going beyond annotation signals.

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

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

Three concise sentences cover endpoint, usage, error handling, and response shape without redundancy. Information is front-loaded; 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 single-parameter tool, the description covers purpose, parameter constraint, error scenarios, and response format. No output schema is needed; richness from description is adequate.

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

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

With 0% schema coverage, the description compensates by specifying that account_ids must be an array of 1–50 strings, adding a constraint absent from the schema. However, it does not explain what these IDs represent.

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 real-time balance per account ID, specifies the HTTP endpoint, and distinguishes it from sibling tools like openfinance_get_accounts_detail and openfinance_list_accounts.

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

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

The description mentions passing account_ids as an array with a size constraint (1–50), but does not explicitly guide when to use this tool versus alternatives like openfinance_get_accounts_detail or openfinance_list_transactions.

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

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

Annotations already declare readOnlyHint=true, so read-only is clear. Description adds batch shape ({ results, errors }) and array limit, but no additional behavioral details like error handling or performance.

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 providing essential information: what it returns, how to call it (endpoint, parameter constraint), and the return shape. No wasted words.

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

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

Given the simplicity of the tool (one parameter, read-only, no output schema), the description covers all necessary aspects: purpose, parameter usage, and return format. Fully adequate.

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

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

Schema has 0% coverage for account_ids, but description clarifies it is an array of IDs (1-50) and that results are per ID. Adds necessary 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 specifies the tool returns full account objects including extended creditData, per ID, and mentions the batch capability. It clearly distinguishes from sibling tools like openfinance_list_accounts which likely returns summaries.

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

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

Explicitly states to pass account_ids as an array (1–50), providing a key usage constraint. Does not explicitly compare to alternatives but context suggests when to use for detailed data.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by clarifying the batch response shape ({ results, errors }), the absence of a paid/status field, and the nuance that payments[] does not imply this bill was paid.

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

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

The description is dense and front-loaded with the core purpose, but it runs several sentences long. Given the complexity of the Open Finance nuance, the length is justified and each sentence adds value.

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

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

Given no output schema, the description thoroughly explains the return shape, what is included and excluded, batch structure, and critical behavioral notes (paid status, payments[] interpretation). It is complete for the tool's moderate 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% for the single parameter bill_ids. The description compensates by explaining its purpose and advising to first use openfinance_list_credit_card_bills to discover IDs, though it does not specify constraints on the string format.

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 bill-level detail for credit card bills by ID, specifying included fields (financeCharges, payments) and explicitly distinguishing it from openfinance_list_transactions for itemized transactions.

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

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

The description provides explicit guidance: use openfinance_list_credit_card_bills first to discover IDs, pass bill_ids as an array, and use openfinance_list_transactions for individual transactions. It also warns about the interpretation of payments[] regarding paid status.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds behavioral details: it returns status, executionStatus, connector metadata, and explains the difference in response shape (count, items vs single). No contradictions.

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

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

Two sentences, no redundant words, front-loaded with purpose. Each part adds value and is efficient.

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

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

Given the tool's simplicity (optional param, no output schema), the description covers all needed: what it returns, how to use the parameter, and behavior. Sibling tools are diverse, but this stands alone 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?

With 0% schema description coverage, the description fully compensates by explaining the item parameter: omitting gets all banks, passing gets a single bank. This adds crucial 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 that the tool returns the current status of a bank connection, listing example statuses. It distinguishes from siblings like get_account_balance by focusing on 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?

Explicitly tells when to omit vs pass the item parameter: get all banks vs a single bank. This guides the agent in choosing the correct invocation pattern.

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=true, idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: the distinction between account 'name' and 'bank' field, the aggregation behavior when 'item' is omitted, and the note that credit balance interpretation varies by connector. 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 thorough but somewhat lengthy. It is well-structured with front-loaded key information, but a slight reduction in verbosity could improve conciseness 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?

Given no output schema, the description comprehensively covers return values, structure when aggregated vs single item, and caveats about credit balance. It also directs to an alternative tool for more accurate billing data, making it complete 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?

The input schema has zero descriptions for its two parameters. The description fully compensates by explaining the effect of omitting or passing 'item' and the meaning of 'type' as part of the returned accounts. It also clarifies that 'bank' is the brand name and 'name' is the legal entity, adding semantic value beyond the schema.

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

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

The description clearly states that the tool returns accounts (BANK and CREDIT) with specific fields like balance, number, type, subtype, bankData, and creditData. It also distinguishes from the sibling tool openfinance_list_credit_card_bills by explaining that for standardized bill amounts, that tool should be used.

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 omit or include the 'item' parameter to list accounts across all banks or target a single bank. It also warns about the connector-dependent meaning of CREDIT balance and directs users to an alternative tool for standardized data.

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 nature. The description adds valuable behavioral context: caching behavior, single aggregated response, and details about response fields (id, description, etc.), which are not covered 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 concise, with three short sentences that front-load the core purpose and quickly add relevant details about caching, response structure, and related tools. 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 list tool with no parameters and no output schema, the description covers all necessary information: purpose, response format, caching behavior, and relationship to other tools. Annotations fill the safety profile.

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 schema coverage is 100%. The description adds meaning by explaining the response structure and fields, compensating for the lack of an output schema. Baseline is 4 for 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?

The description clearly states it returns 'Pluggy's transaction category taxonomy', identifies the specific action (list) and resource (categories), and differentiates from siblings by specifying it provides the category taxonomy used by openfinance_update_transaction_category.

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

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

The description explains the response is cached and provides a single aggregated response, but it does not explicitly state when to use this tool versus alternatives or mention when not to use it. However, it implicitly guides use by linking to another 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 indicate readOnlyHint=true and destructiveHint=false; the description adds context about returned fields but no additional behavioral traits.

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

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

Single sentence, efficiently states purpose and key return fields, 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?

For this simple list tool with no output schema, the description sufficiently describes the return value including the add_connection_url.

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 naturally covers them; baseline for zero parameters is 4.

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

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

The description clearly states it returns saved bank connections with specific fields (connector_id, item_id, bank name, add_connection_url). It distinguishes from sibling tools by focusing on the list of connections, not accounts or 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 does not provide explicit guidance on when to use this tool vs alternatives. However, its narrow purpose makes usage fairly self-evident.

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 annotations by detailing payment semantics, derived payment_status, connector asymmetry, and that include_open_bill triggers an extra scan. It explains that the tool does not return a native paid/status field. 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 sections. Every sentence adds necessary context for the complex Brazilian Open Finance semantics. However, it could be slightly more concise by front-loading the main return structure.

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

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

The description covers return fields, payment logic, open_bill details, connector asymmetry, and opt-in behavior. However, it lacks pagination details (page, page_size) and does not mention error handling. Overall, quite complete given 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 explains account_id, account_ids, and include_open_bill, but does not mention page or page_size parameters despite the schema having no descriptions. This is a significant gap for a list tool.

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

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

The description clearly states the tool returns closed credit card bills for a CREDIT-type account. It distinguishes itself from siblings by noting that for itemized transactions, use openfinance_list_transactions, and that results are bill-level summaries.

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

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

The description provides clear guidance on when to use this tool versus alternatives (e.g., for transactions, use openfinance_list_transactions). It explains the opt-in behavior for open_bill and connector asymmetry. However, it does not explicitly differentiate from the sibling openfinance_get_credit_card_bill.

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 the tool as read-only, non-destructive, and idempotent. The description adds valuable behavioral context: it returns a specific error structure on 403 or upstream errors, and lists the types of investments and fields returned, enhancing agent understanding 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, dense sentence that lists many asset types and fields. It conveys essential information but lacks structure; breaking it into shorter sentences would improve readability.

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

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

The description covers the core purpose, error behavior, and key fields returned. However, it omits guidance on pagination (page/page_size parameters) and does not describe the output structure beyond the warning object. Given no output schema, more detail would be beneficial.

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 4 parameters (item, page, type, page_size) with 0% schema description coverage. The description does not explain the meaning or usage of these parameters, such as what 'item' refers to, how 'page' interacts with 'page_size', or the effect of the 'type' filter. This is a significant gap.

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

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

The description clearly states the tool returns an investment portfolio for a connection, listing specific asset types (FIIs, stocks, etc.) and fields. It distinguishes itself from sibling tools like openfinance_list_accounts or openfinance_list_investment_transactions by focusing on the full portfolio.

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

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

The description provides clear context on when to use the tool (for connections with INVESTMENTS product enabled) and how it behaves on errors (returns warning object instead of throwing). However, it does not explicitly mention alternatives or 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 and destructiveHint=false. The description adds detailed output fields (quantity, value, expenses breakdown) and bulk behavior, but does not cover potential rate limits or authentication details. Slight additional value 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 dense sentences plus a line on bulk support; no redundancy. Front-loaded with key purpose and output details.

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

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

Covers fields and bulk, but lacks pagination details, default sizes, sorting, or total count info. Good but not fully comprehensive for a 4-parameter tool without 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?

Schema has 0% description coverage, so description must compensate. It explains investment_id and investment_ids well (prerequisite and bulk use), but pagination parameters (page, page_size) are not addressed. Partial compensation.

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, etc.), and distinguishes it from sibling tools like openfinance_list_investments by specifying the prerequisite.

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 advises to use after openfinance_list_investments to get the investment_id, and mentions bulk support for batched execution, providing clear context for 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?

Annotations indicate read-only, idempotent, and non-destructive. The description adds transparency about rate-limit spacing, per-connection results/errors structure, and how multiple connections are handled. 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?

Three sentences, front-loaded with purpose, no filler. Efficiently covers all necessary behavioral and parameter details.

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

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

Despite no output schema, the description explains the return format. Tool has one parameter, well explained. Annotations cover safety. Complete for a list tool with clear usage patterns.

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

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

Schema has 0% coverage for 'items'. The description fully compensates by explaining that items are connection selectors (item_id uuid, connector_id, or connector_name) and the behavior difference when present or absent.

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

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

The description clearly states the action ('Lists loan contracts') and the resource ('per bank connection (GET /loans)'). It distinguishes from sibling list tools by specifying the per-connection behavior and the option to list 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?

Provides explicit guidance: how to use 'items' to fetch specific connections, omit for all banks, and describes sequential querying with rate-limit spacing. No ambiguity about usage.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds rich behavioral context: aggregation logic with search_queries, error handling (returns warning/error), bulk support, and health check guidance for credit accounts. 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 fairly long but every sentence adds value. It is front-loaded with the main purpose and then covers details in a logical order (CREDIT specifics, date/pagination, search, error handling, health check, bulk). A slight reduction in length could improve conciseness, but the structure is clear.

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

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

The description is highly complete given the complexity: 7 parameters, no output schema, and no schema descriptions. It covers all parameters, edge cases (truncated:true, CREDIT total 0, connector variance), error handling, and even references a related tool (openfinance_get_item_status). 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?

Schema description coverage is 0%, so the description carries full burden. It explains all parameters: from/to (ISO YYYY-MM-DD), pagination (max 500/page), search_queries (case-insensitive substring match, OR semantics), and bulk via account_ids. The description compensates fully for the missing 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 it returns transactions for bank accounts (BANK or CREDIT type), specifies the verb 'returns', and distinguishes itself from siblings like openfinance_list_credit_card_bills and openfinance_update_transaction_category.

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

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

The description explicitly says when to use this tool (only way for CREDIT itemized transactions) and when not to use it (for standardized open bill total, use openfinance_list_credit_card_bills). It also provides context on PENDING vs POSTED behavior varying by connector.

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 idempotent. Description adds behavior not in annotations: fan-out across accounts, default compact summary, truncation limit per account with flag, and raw granularity effect. No contradictions.

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

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

Description is detailed but well-structured. First sentence captures core purpose. Minor redundancy like 'consolidated' appears twice, but overall 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 6 parameters, 2 enums, no output schema, the description covers purpose, usage, parameter details, behavioral traits (truncation), and alternatives. Return structure is hinted (compact summary vs. raw rows). Complete for agent decision-making.

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

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

Schema coverage is 0%, so description fully compensates by explaining every parameter: item (connector_id/name/omit-all), from/to (ISO dates), granularity (monthly vs. raw behavior), type (BANK/CREDIT), top_n (implied in top lists). Defaults and effects are clear.

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

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

Description clearly states verb 'analyze' and resource 'transactions for a bank connection' in one consolidated call. Distinguishes from siblings like openfinance_list_transactions by specifying it resolves accounts internally, avoiding manual multi-step processes.

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

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

Explicitly provides when to use (cash-flow analysis, annual/monthly, top expenses) and when not to (no need for openfinance_list_accounts). Includes specific use-case phrases and options like granularity and type filtering.

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 safety. The description adds value beyond annotations by detailing the return data: global indicator, degraded components, open incidents, and your_banks_affected. It also implies no authentication needed as it checks a public status page. 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 reasonably concise at 4-5 sentences, each adding value. The first sentence states purpose, the second gives usage context, and the third details return data. It is well-structured, though slightly longer than the 2-sentence ideal seen in the HIGH calibration example.

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 specifies what the tool returns: global indicator, degraded components, open incidents, and a flag for affected banks. It provides complete context for understanding the output without relying on a schema. The zero parameters also reduce 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?

There are no parameters (0 params). Schema description coverage is 100% since there are no parameters. Baseline for 0 params is 4 according to guidelines. The description does not need to add param 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 checks the LIVE operational status of the Open Finance provider, distinct from the user's own connection ('separate from your own connection's openfinance_get_item_status'). It specifies the verb 'checks' and the resource 'provider status', and distinguishes from the sibling tool openfinance_get_item_status.

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

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

Explicitly tells when to use: 'whenever data looks incomplete or stale even though a connection shows UPDATED'. It also explains what it doesn't do ('separate from your own connection') and provides an alternative tool for connection-level status (openfinance_get_item_status). This is a clear use case with both inclusion and exclusion criteria.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral details: it honors the user's plan (PF vs PJ), returns a connect_url, and 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 somewhat long but front-loaded with the main action and each sentence adds value. Could be slightly more concise, but overall efficiently conveys necessary 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 no output schema and 0% param coverage, the description covers the tool's purpose, parameters, return values, and usage context. It lacks error handling details but is sufficient 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?

With 0% schema description coverage, the description compensates well by explaining keywords as an array of strings with examples and stating it is required, and explaining include_accounts triggers returning accounts. It adds 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 searches bank connectors by name and returns specific details like connector id, access type, audience, linked connections, and connect_url. It distinguishes itself from listing all connectors by emphasizing that keywords are required and without it returns a hint, not the full catalog.

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

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

The description explicitly says to call this tool BEFORE connecting to provide a one-click link, and warns that keywords are required. It does not explicitly mention alternatives or when not to use it, but the context is clear given the sibling 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 description discloses critical behavioral traits beyond annotations: it overrides automatic categorization, creates a Category Rule for the client (case-insensitive exact match), and explains the batch error handling ('per-item errors do not fail the whole batch'). Annotations only indicate idempotentHint=false and destructiveHint=false, but the description adds valuable context about side effects and mutation behavior.

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

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

The description is relatively long but each sentence serves a purpose: explaining input format, side effects, return shape, and error behavior. It could be slightly more concise by merging some sentences, but it remains highly informative 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?

The description covers all necessary aspects for an AI agent: input requirements (items array with IDs), data sources for IDs, side effects (creating category rules), return shape (updated, results, errors), and error handling behavior. Given no output schema, this is complete and self-sufficient.

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 thoroughly explains the 'items' parameter: it is an array of objects with transaction_id and category_id, and specifies where each ID originates (openfinance_list_transactions and openfinance_list_categories). This adds significant meaning beyond the schema's type definitions, enabling correct usage.

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 corrects the category of one or more transactions, specifying the HTTP method PATCH. It names the resource (transactions) and the action (update category), and includes the endpoint path. This is a specific verb+resource combination that distinguishes it from sibling tools like openfinance_list_transactions or openfinance_list_categories.

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

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

The description explicitly tells when to use this tool: 'use this to fix miscategorized transactions and improve categorization accuracy going forward.' It also provides detailed guidance on how to construct the input, referencing sibling tools openfinance_list_transactions and openfinance_list_categories for obtaining IDs. This gives clear context and 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 indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds that conversation is needed for reproduction, but otherwise does not disclose side effects or behavior 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 with no redundancy: first states purpose, second provides usage guidance. Every word earns its place.

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

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

No output schema exists, and parameter descriptions are minimal. The tool is simple (feedback reporting), but missing details on expected response or handling of submissions. Adequate but not thorough.

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

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

Schema coverage is 0%, so description must compensate. It only explains the 'conversation' parameter partially ('include the conversation array with recent messages'), but offers no detail on 'context' or 'message' fields, leaving three parameters under-documented.

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

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

The description clearly states the verb and resource: 'Report a bug, missing feature, or send feedback.' It distinguishes from sibling tools, which are all finance or authentication related.

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

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

It provides explicit guidance to include the conversation array for reproduction, but does not specify when not to use the tool or mention alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no extra behavioral context (e.g., no mention of output format or side effects). It neither contradicts nor significantly enhances the annotations.

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

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

The description is a single, concise sentence that efficiently conveys the tool's purpose without 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?

For a simple, zero-parameter version tool with no output schema, the description adequately conveys what the tool does. No additional context is needed.

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

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

There are zero parameters, and the schema has 100% coverage (empty). The description need not add parameter details. Baseline for no params is 4.

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

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

The description clearly states the action ('Show') and the resource ('current MCP platform and adapter versions'). It is specific and differentiates from sibling tools, which are primarily focused on financial operations.

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

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

The description does not explicitly state when to use this tool versus alternatives. However, its purpose is self-evident as a version query tool, making explicit guidelines less critical.

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 behavior. The description adds value by specifying what state details are returned (installed MCPs, connection status, catalog counts), going beyond the annotations.

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

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

Single sentence, front-loaded with the main action, no extraneous words. Highly efficient.

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

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

Given no parameters and no output schema, the description adequately explains the return values. Could be improved by adding format details, but sufficient for a simple info tool.

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

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

No parameters defined, and schema coverage is 100%. Baseline for 0 parameters is 4, and the description adds no parameter-specific information, which is acceptable.

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

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

The description clearly states the tool returns the current toolkit state with specifics (installed MCPs, connection status, catalog tools count), making it distinct from sibling tools like show_version or report_bug.

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

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

No explicit guidance on when to use this tool versus alternatives like show_version or marketplace. The usage is implied from the description but lacks when-not-to-use or prerequisite context.

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