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?

Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds behavioral context about specific return values (authenticated field, pending array, connect URLs) that go beyond annotation 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?

Two sentences, front-loaded with main purpose, 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 zero-parameter status check tool, the description fully explains the two main states and return values. No output schema is needed given the simple nature.

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%. Description does not need to add parameter info; baseline 4 is appropriate.

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

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

Description clearly states it returns connection status and URLs with specific cases for different states. It distinguishes from siblings implicitly by focusing on status, but does not explicitly differentiate.

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

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

Description implies usage for checking connection status, but does not explicitly state when to use it versus siblings like 'authenticate' or 'list_connections'.

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 key behaviors beyond annotations: invoke works without installation, returns connect/checkout links on credential/payment issues, writes require owner/admin. No contradiction with annotations.

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

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

The description is lengthy and includes many details. While front-loaded with essential info, it could be more concise by grouping or trimming redundant explanations. Sentences are functional but not optimally streamlined.

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 high complexity (15 parameters, no output schema), the description lacks explicit explanations for many parameters (e.g., limit, query, conversation, arguments format). It focuses on overall orchestration but leaves parameter-level details under-specified.

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 coverage, the description explains main parameters (action, mcp_id, tool_id, arguments) and their roles in the flow. However, many parameters (limit, query, message, immediate, etc.) are not explicitly documented, leading to 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 identifies the tool as the official marketplace and enumerates its core actions (search, describe, invoke, etc.), distinguishing it from sibling tools. However, the tool encompasses many sub-actions, making purpose less singular than an ideal 'verb+resource' pattern.

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 'use THIS tool FIRST' before external registries, contrasts invoke vs. install, and differentiates from siblings like list_tools, subscribe/cancel, report_bug, request_mcp. Provides clear when-to-use and when-not-to scenarios.

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

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

The description aligns with the destructiveHint=true annotation and adds value by specifying that data 'will no longer be available' and that a reconnection URL is returned. This goes beyond the annotation details.

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

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

The description is three concise sentences, each adding necessary information without redundancy. It is front-loaded with the main action and efficiently covers the key 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 low complexity and existing annotations, the description covers the tool's effect and return value. However, the lack of parameter documentation (item) leaves a gap in completeness 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?

The required 'item' parameter is not described in the schema or description, leaving its meaning unclear. With 0% schema description coverage, the description should compensate but does not.

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

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

The description clearly states the action ('revokes consent', 'deletes connection data') and the resource ('specific bank'). It also distinguishes itself from sibling tools like 'openfinance_list_connections' by specifying that it removes data and provides a reconnection URL.

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

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

The description implies use when disconnecting a bank but does not provide explicit when-to-use, when-not-to-use, or alternative tools. The context is clear but lacks comparative 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?

Describes behavior beyond annotations, including waiting up to 60s, polling mechanism, return fields (status, executionStatus, lastUpdatedAt, synced), and edge cases like needs_action or timed_out. Annotations already have readOnlyHint=false, but description adds valuable context.

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

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

The description is detailed but concise for the complexity; each sentence is informative and front-loaded. Could be slightly shorter but still very 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 complexity (sync with waiting, polling, error states) and no output schema, the description covers return structure, statuses, and error conditions comprehensively, making it complete for agent 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?

With 0% schema coverage, the description fully explains both parameters: 'items' as array of selectors (item_id, connector_id, connector_name) and option to omit for all, and 'wait' boolean for synchronous vs fire-and-forget. Adds meaning beyond 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 forces a sync and waits for completion, using specific verbs like 'forces' and 're-sync', and distinguishes itself from sibling tools like openfinance_get_item_status by explaining when to use which.

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

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

Provides explicit guidance on when to use (stale balance/transactions), what it achieves (pulls fresh data without disconnecting), and how to use it (omit items for all banks, set wait: false for fire-and-forget). No exclusions needed.

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

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

Beyond readOnlyHint and idempotentHint, it discloses error behaviors: BALANCE_FETCH_ERROR for CREDIT accounts, degradation to last-synced with realtime:false and warning. Provides structured warning mechanism.

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?

Concise single paragraph with front-loaded action, then constraint, then error handling, then response shape. No superfluous sentences.

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 error cases and top-level response shape. Lacks details on individual result fields (e.g., balance amount, currency), but acceptable given no 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 coverage is 0%, but description adds crucial '1-50 items' constraint. Does not detail the format of each account ID string, but the context implies they are account identifiers.

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 real-time balance per account ID and specifies the endpoint and array parameter constraint. Distinguishes from siblings like 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?

Explicitly notes the array size 1-50 and describes error handling (e.g., warning instead of error, degradation to last-synced). Does not provide alternatives or when-not-to-use, but context is clear.

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

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

Description adds critical behavioral info beyond annotations: the provider_incident block can indicate unreliable credit limits and balances, advising not to present those values as real. This is valuable for agent decisions, and no contradiction with readOnlyHint or other 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: three sentences covering purpose, usage, and warning. It is front-loaded and every sentence provides essential information without waste.

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 type, batch behavior, and a key caveat about provider incidents. While no output schema exists, the description touches on the response shape. However, it could list the fields included in the account objects to fully equip the agent.

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

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

The description adds meaning to the sole parameter account_ids by constraining array size (1–50) and explaining the batch shape { results, errors }. Since schema has 0% description coverage, the description compensates well, though it could specify that IDs must correspond to valid accounts.

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

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

The description clearly states the tool returns full account objects with extended creditData per ID, using a batch approach. The verb 'returns' and resource 'account objects' are specific, and it distinguishes from siblings like openfinance_list_accounts by highlighting extended creditData.

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 to pass account_ids as an array of 1–50 items, and warns about provider_incident affecting data reliability. However, it lacks explicit comparison with other tools or guidance on when to use this over siblings 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behavioral traits: Pluggy does not return a paid/status field, explains the nuance that payments in the bill likely refer to the previous bill, and warns that billId on transactions is sparse/inconsistent. This adds significant value.

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

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

The description is longer than average but well-structured: starts with purpose, then what it doesn't do, then behavioral notes. Each sentence adds value, though some repetition could be trimmed (e.g., the note about billId being sparse is repeated). Still, it is efficiently organized.

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 a single parameter, no output schema, and moderate complexity, the description covers all necessary context: what it returns, what it doesn't, how to use the parameter, important caveats about payments and paid status, and the batch response shape. It is fully adequate for an agent to select and invoke correctly.

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

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

Schema has 0% description coverage for the only parameter bill_ids. The description partially compensates by stating 'Pass bill_ids as an array' and 'use openfinance_list_credit_card_bills first to discover ids', which gives context on how to obtain the values. However, it does not specify constraints like required format or minimum length.

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 bill-level detail for credit card bills by ID, specifies the included fields (financeCharges, payments), and explicitly distinguishes itself from sibling tools by stating what it does not return (individual transactions) and pointing to openfinance_list_transactions for that purpose.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: use for bill detail, not for transactions; directs to openfinance_list_transactions for transactions and openfinance_list_credit_card_bills for discovering bill IDs. It also warns against reconstructing totals from 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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context by specifying return structure (`{ count, items }` for all, single object for one) and the inclusion of executionStatus and connector metadata. It does not contradict annotations and provides useful details beyond what annotations convey.

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

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

Two sentences that are front-loaded with the core purpose, then immediately explain the two usage modes. No redundant information or vague phrasing. Each sentence earns its place.

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

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

For a simple read-only tool with one parameter and no output schema, the description covers the main behavior, return structure for both modes, and example statuses. It could mention what connector metadata includes, but the information provided is sufficient for an agent to invoke the tool correctly.

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

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

The single parameter `item` has 0% schema description coverage, so the description must compensate. It explains that omitting `item` returns status for all linked banks, while passing it gets a single bank's status. This adds meaningful semantic information, though it does not specify format or constraints for the `item` value.

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

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

The description clearly states the tool returns the current status of a bank connection, lists example statuses (UPDATED, UPDATING, LOGIN_ERROR, etc.), and mentions additional fields (executionStatus, connector metadata). It also distinguishes between two usage modes: omitting `item` for all connections and passing `item` for a single bank. This makes the purpose specific and distinct from sibling tools like openfinance_list_connections.

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 omit vs. pass the `item` parameter, but does not explicitly compare to sibling tools or state when not to use this tool. It implies usage context through the two modes, but lacks explicit exclusions or alternatives.

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

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

The description adds value beyond the annotations by detailing the batch shape ('{ results, errors }'), the array size limit (1-50), and the specific fields returned (e.g., interestRates, installments, CET). This provides behavioral context that the annotations (readOnlyHint, destructiveHint, idempotentHint) do not cover. 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 moderately concise and front-loaded with the core purpose. It lists many fields but in a compact manner. The structure is logical: purpose, usage hint, parameter instruction, return format. It could be slightly shorter by removing the full field list, but the detail aids understanding.

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

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

Given the tool has no output schema, the description provides a thorough explanation of return values including specific financial fields. It explains the batch shape (results/errors). It is complete enough for an agent to understand what to expect, though it could mention potential error conditions for missing IDs.

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% coverage (no description) for the single parameter loan_ids. The description compensates by stating 'Pass loan_ids as an array (1-50)', which clarifies the type and size constraints. This adds significant meaning beyond the schema alone, though it could further explain the format of the strings.

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

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

The tool description uses a specific verb 'Returns full loan contract detail by id' and clearly lists the fields returned. It distinguishes itself from siblings by explicitly stating 'Use after openfinance_list_loans to deep-dive on a specific contract.' This leaves no ambiguity about what the tool does and how it relates to other tools.

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

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

The description provides clear usage guidance: use this tool after openfinance_list_loans for a deep dive on a specific contract. It also specifies passing loan_ids as an array of 1-50 items. However, it does not explicitly mention when not to use this tool or provide alternatives, though the context is sufficient for most cases.

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 operation. The description adds significant behavioral context: connector-dependent CREDIT balance meaning, provider_incident block affecting reliability, and clarifies that `name` is the legal entity not the brand. This goes beyond what annotations convey.

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

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

The description is lengthy but well-structured: starts with main purpose, then field clarifications, usage guidance, and warnings. Every sentence adds value, though could be slightly more concise without losing information.

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

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

Given the complexity of account types, field semantics, and connector-dependent behavior, the description covers most aspects including provider incidents. References a sibling tool for credit bills. Does not discuss error handling or pagination, but otherwise complete for a read-only tool.

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

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

Schema has 0% description coverage, but the description compensates by explaining the `item` parameter (omit vs. pass) and the meaning of the `type` enum (BANK checking/savings, CREDIT credit card). Adds semantic value beyond the raw schema definition.

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 accounts for bank connections with specific fields (BANK and CREDIT types, balance, etc.). Distinguishes from sibling tools by referencing openfinance_list_credit_card_bills for standardized bill amounts, but could better differentiate from other account-related tools like openfinance_get_account_balance.

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

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

Explicitly describes when to omit or pass the `item` parameter (e.g., 'my accounts/cards' vs. targeting a single bank). Warns against misinterpreting CREDIT balance and directs to an alternative tool for standardized open-bill amounts. Provides clear usage scenarios.

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

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

Annotations already mark readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that the result is cached per session and is a single aggregated response, providing beyond-annotation context.

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

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

The description is front-loaded with the main verb and noun, and every sentence adds meaningful detail. It is concise with no fluff.

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

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

Despite no output schema, the description fully explains the response structure and links to a sibling tool. For a zero-parameter, read-only tool, this 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?

There are no parameters (schema coverage 100%), so a baseline of 4 applies. The description adds value by explaining the response fields (id, description, etc.) and their 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 it returns Pluggy's transaction category taxonomy, names the endpoint, and lists the fields. It distinguishes from sibling tools like list_transactions by focusing on categories, and mentions the specific use case with updating 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 implies usage before calling openfinance_update_transaction_category, and notes that descriptionTranslated is preferred for pt-BR users. However, it lacks explicit when-not-to-use or alternative tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying returned fields and the add_connection_url for linking additional banks. No contradictions.

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

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

The description is a single, well-structured sentence that conveys all necessary information without redundancy.

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

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

For a simple, read-only list tool with no parameters and no output schema, the description adequately specifies the return content. It could mention potential limitations (e.g., no pagination details) but is sufficient for basic 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 exist (schema description coverage 100%), so the description does not need to explain parameters. The baseline score of 4 applies as the tool is parameterless.

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

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

The description clearly states the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, add_connection_url). It distinguishes from sibling list tools (e.g., list_accounts, list_transactions) by focusing on connections.

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 to view bank connections but provides no explicit guidance on when to use this tool versus siblings like openfinance_list_accounts or openfinance_get_item_status. No exclusions or alternatives are mentioned.

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

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

Disclosures include derived payment_status logic, payment-cycle mapping nuances, bill_grouping_reliability warnings, and connector asymmetry for open_bill. Annotations already indicate readOnlyHint=true, which is consistent.

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?

Very thorough but dense; all information is relevant and earns its place. However, the wall-of-text format could be improved with clearer structure (e.g., sections) for easier consumption by an AI agent.

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 return fields, derived statuses, error handling (warning instead of fail), cross-tool relationships, and opt-in behavior. Despite missing pagination param descriptions, the overall context is highly complete for a complex tool with no 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?

Description details include_open_bill and account_ids for bulk execution, but does not explain page and page_size parameters. With 0% schema coverage, these missing descriptions reduce clarity.

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

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

The description explicitly states it returns CLOSED credit card bills for a CREDIT-type account, listing key fields. It distinguishes from sibling tools like openfinance_list_transactions by clarifying that this tool provides bill-level summaries, not transactions.

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

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

Provides clear when-to-use guidance: opt-in for open bill, never sum transactions by billId, cross-check echo block against intended bank, and warns against categorically calling a bill 'vencida'. Also flags connector asymmetry and fallback 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: on errors (403 or upstream) it returns { total:0, results:[], warning } instead of throwing, and lists specific fields like balance, amount, rates, dueDate, etc. This goes beyond annotations.

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

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

The description is a single dense paragraph that packs purpose, types, fields, and error handling. It front-loads the purpose but lacks structural breaks. It is somewhat lengthy but not excessively so, though it could be more scannable.

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 covers return fields and error handling, but misses parameter explanations and pagination details. The tool has 4 optional params with no guidance, leaving some gaps for an agent.

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

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

Schema description coverage is 0%, so the description must explain the parameters. It does not elaborate on 'item', 'page', 'type', or 'page_size' beyond what the schema provides. The agent gets no additional meaning, e.g., that 'item' refers to a connection ID or that 'type' filters asset categories.

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

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

The description clearly states the tool returns investment portfolio data for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.) and fields. This distinguishes it from siblings like openfinance_list_accounts or openfinance_list_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 implicitly indicates usage for retrieving investment data, but does not explicitly state when or when not to use it, nor does it mention alternatives among siblings. However, it covers error handling (returns structured response on 403), which provides some 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 readOnly, idempotent, non-destructive. The description adds significant behavioral details: transaction types, fields returned, and bulk execution capability. 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?

Two succinct sentences cover purpose, return fields, and usage hint. No wasted words, front-loaded with key 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?

Describes return fields adequately given no output schema, but lacks pagination details (page/page_size) and precise bulk usage rules. Adequate but with clear 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 coverage is 0%, so description must compensate. It explains investment_id (required) and mentions investment_ids for bulk, but does not clarify the relationship between them (e.g., can investment_ids replace investment_id?) and omits page/page_size entirely. Incomplete parameter guidance.

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

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

The description clearly states the tool returns movement history for a specific investment position, listing transaction types like BUY/SELL/TAX. It distinguishes from sibling tools by specifying it works on a single investment (from openfinance_list_investments) and details the returned 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?

Explicitly instructs to use after openfinance_list_investments to obtain investment_id, and mentions bulk support via investment_ids. However, no explicit when-not-to-use or alternatives are provided.

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

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

Adds context beyond annotations: sequential queries with rate-limit spacing and return format { results, errors } per connection. Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and description does not contradict.

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 succinct sentences with no wasted words. Front-loaded with main action, then details on parameter usage and behavior.

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 parameter usage, behavior (sequential/rate-limited), and return shape. Lacks details on what fields loan contracts contain and error handling beyond 'errors' key, but sufficient for a list tool with good 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?

Schema has no description for `items` (0% coverage); description compensates fully by explaining that items are connection selectors (item_id uuid, connector_id, or connector_name) and that omitting fetches all connections.

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 'Lists loan contracts per bank connection (GET /loans)' with specific verb and resource. It distinguishes from sibling tools like openfinance_list_accounts by mentioning the items parameter for per-connection listing vs. omitting for 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?

Explicitly describes when to pass `items` (for specific connections) and when to omit (for all linked banks), with guidance on sequential rate-limited execution. Does not mention alternative tools but given the context, it 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 indicate readOnlyHint, idempotentHint, and non-destructive. The description aligns and adds significant behavioral context: it explains pending vs. posted transaction behavior for credit accounts (varies by connector), pagination limits (5000 ceiling, truncated flag), error handling (returns {total:0, results:[], warning, error} instead of throwing), provider incident block, and that 'rich'/'raw' detail coverage varies by bank.

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 information-dense, with every sentence providing value. It is logically structured: main purpose, credit card specifics, date filters, pagination, detail levels, error handling, bulk support. While it could be slightly more concise, the complexity of the tool justifies the length.

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

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

Given the tool's complexity (8 parameters, multiple account types, pagination, detail levels, provider incidents) and the absence of an output schema, the description is remarkably complete. It covers all relevant aspects: inputs, behavior, edge cases (e.g., truncated results), error handling, provider incidents, and references to sibling tools for additional context.

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

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

With 0% schema description coverage, the description fully compensates by explaining all 8 parameters: from/to (ISO dates), search_queries (case-insensitive, substring, OR semantics), page (omit for auto-paginate), page_size (max 500), detail (compact/rich/raw with explanations), account_id (required), account_ids (bulk support). It adds meaning beyond the schema by defining behavior and constraints.

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 starts with a clear verb-resource pair: 'Returns transactions for a bank account (BANK or CREDIT type).' It distinguishes between account types and explicitly states that for CREDIT accounts, this is the only way to get itemized transactions, differentiating it 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?

The description provides extensive guidance: when to use this tool vs. openfinance_list_credit_card_bills, pagination strategies (auto-paginate vs. manual page), detail levels, and when to check item status. It also explicitly warns against reconstructing bill totals from transactions and advises cross-checking the account echo block when multiple banks are connected.

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=true, idempotentHint=true), the description discloses the scan cap of 5000/account with a truncated flag, and a provider_incident block when open finance provider issues may affect results. This adds significant behavioral context.

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

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

The description is comprehensive but lengthy. It front-loads the main purpose and each sentence adds value. However, it could be slightly more structured by breaking into paragraphs or bullet points for readability.

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

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

Given the complexity (7 params, no output schema), the description covers all usage scenarios, return formats, error conditions (truncated, provider incident), and parameter effects. It is fully complete for an agent to invoke correctly.

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

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

Despite 0% schema description coverage, the description explains all 7 parameters: item, from/to as ISO dates, granularity defaults to 'monthly' returning summary, detail levels (compact/rich/raw), type filter, and top_n for top expenses/revenues. It adds 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 performs consolidated cash-flow analysis for a bank connection, resolving accounts internally. It distinguishes itself from sibling tools like openfinance_list_transactions by emphasizing it does not require prior calls to 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 explicitly tells when to use this tool (e.g., 'análise anual/mensal', 'fluxo de caixa') and when to omit parameters (e.g., omit item to analyze all banks). It also recommends setting granularity to 'raw' when itemized rows are needed, providing clear guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: it returns a global indicator, degraded components, open incidents, and flags incidents affecting connected banks. This goes beyond what annotations provide, though the annotations already cover the most critical behavioral aspects.

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

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

The description is moderately concise with three sentences, each adding value: first states purpose and differentiation, second provides use cases and reasoning, third lists output. It is front-loaded with the core purpose. While it could be slightly trimmed, every sentence earns its place and there is no fluff.

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

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

Given the tool has no parameters and no output schema, the description fully covers what the tool does and what it returns. It explains the use case, distinguishes from siblings, and details the output format (global indicator, degraded components, incidents, affected banks). This is complete for a status check tool.

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

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

The tool has zero parameters and schema coverage is 100%, so no parameter documentation is needed. The description uses its space to explain the tool's purpose and output instead of repeating missing parameter details. Baseline for 0 parameters is 4, and the description does not add any parameter info, which is appropriate.

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

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

The description clearly states the tool 'Checks the LIVE operational status of the Open Finance provider (its public status page)'. It uses a specific verb (checks) and resource (provider operational status), and immediately distinguishes itself from the sibling tool 'openfinance_get_item_status' by specifying it checks the provider's health, not the user's connection.

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

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

The description provides explicit guidance: 'Use it whenever data looks incomplete or stale even though a connection shows UPDATED...'. It explains the context (missing accounts/transactions, bank not returning everything) and how it helps differentiate provider-side problems from connection issues. It also names the alternative tool to use for connection status.

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

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

Annotations (readOnlyHint=true, destructiveHint=false) are complemented by description: it won't dump full catalog, honors user plan, and includes caveat warnings for non-Open-Finance connectors. 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?

Single dense paragraph, but effectively front-loaded with core purpose. Could be slightly more structured (e.g., bullet points) but not overly verbose.

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 description details returned fields (id, access, audience, connections, accounts, connect_url) and error behavior (hint without keywords). Covers edge cases and plan filtering.

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 descriptions missing (0% coverage), but description explains both parameters: keywords is required despite schema, with example format, and include_accounts triggers return of linked connections/accounts. Adds critical meaning.

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

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

Clearly states the tool searches bank connectors by name (keywords array), returning connector id, access type, audience, linked connections/accounts, and connect_url. Distinguishes from siblings like 'authenticate' and 'connect' by specifying it is a pre-connection search 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?

Explicitly states to call BEFORE connecting and that keywords[] is REQUIRED (returns hint otherwise). Provides context on when to surface caveats and that plan filtering applies, giving clear guidance on when and how to use.

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

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

The description goes beyond minimal annotations by disclosing that recategorizing creates a Category Rule, affecting future transactions. It also explains batch behavior with per-item errors not failing the whole batch, providing full transparency.

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 paragraph that efficiently packs essential information without excessive verbosity. It could benefit from clearer structuring (e.g., bullet points) but remains concise and informative.

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 absence of an output schema, the description thoroughly explains the return value and side effects. It covers the batch update process, error handling, and the automatic rule creation, making the tool's behavior complete clearly.

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 explaining that items is an array of { transaction_id, category_id }, and specifies where to obtain each ID. It also describes the return shape, adding 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 corrects transaction categories via a PATCH endpoint. It distinguishes from sibling tools by explaining that transaction_id comes from openfinance_list_transactions and category_id from openfinance_list_categories, linking to relevant 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 explains the tool is for fixing miscategorized transactions and improving future categorization. It implicitly provides guidance by referencing source IDs, but does not explicitly state when not to use it or alternatives.

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

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

Annotations already 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context that the tool returns state about MCPs, which is beyond annotations. No contradictions.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose with no wasted words.

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

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

Given zero parameters and no output schema, the description adequately covers what the tool does. It could optionally mention that it is a read-only status check, but the annotations already indicate that. Slightly lacking in output format details, but sufficient for correct invocation.

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

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

No parameters exist in the input schema, so baseline is 4. The description adds value by explaining the output content (installed MCPs, connection status, catalog tool counts), which compensates for no output schema.

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

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

The description clearly states the tool returns toolkit state, specifying 'installed MCPs, their connection status, and how many catalog tools each exposes.' This uses a specific verb and resource, and the content distinguishes it from sibling tools that perform actions or retrieve financial data.

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 state, but does not explicitly state when to use this tool versus alternatives or when not to use it. Given no sibling tool provides identical functionality, the lack of explicit guidance is acceptable but not exceptional.

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