QI SCD MCP

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context: calling with no args returns a link, calling with token sets session. It explains the difference between permanent (config) and session (direct call). 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 each sentence adds value. It is front-loaded with audience and purpose. A slight reduction in wording could improve conciseness, but it is 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?

With no output schema, the description does not explain what the returned link looks like or what a successful authentication returns. However, it covers the three usage scenarios thoroughly. A complete description would include return value details.

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 bears full responsibility. It explains the 'token' parameter as a JWT and describes the two invocation modes (with token or without). This provides essential meaning beyond the raw schema.

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

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

The description clearly states the tool's purpose: authenticating an MCP server for IDE agents. It specifies three distinct usage modes (config, session token, no args) and distinguishes itself from sibling tools which are unrelated to authentication.

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

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

The description provides explicit guidance on when to use each authentication method (permanent config vs session token vs link generation). It implies alternatives but does not explicitly state when not to use the tool, though the 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?

The description adds behavioral context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It explains the output structure (authenticated, pending, connect_url) and how it varies by state. This helps the agent understand what to expect from the call, without needing to repeat annotation info.

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 very concise: two sentences that immediately state the purpose and then elaborate on the two main states. Every word is useful. No filler or repetition.

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

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

For a tool with no parameters and no output schema, the description provides a clear picture of what the tool does and what it returns in two key states. It is fairly complete, though it could mention potential error cases or other outcomes, but given simplicity, it is 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?

There are zero parameters, and the schema has 100% coverage (no properties). The description correctly does not need to add parameter semantics. With no parameters, a baseline of 4 is appropriate since the description is not missing any parameter information.

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

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

The description uses specific verbs ('Returns connection status and URLs') and clearly states the resource (connection status). It distinguishes this tool from siblings like 'authenticate' (which actually performs authentication) by focusing on status reporting. The explanation of the two output states (all connected vs credentials missing) adds clarity.

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 by explaining the tool's behavior in two distinct scenarios: when all providers are connected versus when credentials are missing. This helps the agent know when to call this tool (e.g., before or after authentication). However, it does not explicitly mention when not to use it or compare to alternatives like 'openfinance_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?

Discloses all key behavioral traits: read and write operations, external registry calls, one-off nature of invoke vs persistent install, and authentication/payment flows. No contradiction with annotations (readOnlyHint=false, openWorldHint=true).

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 and well-structured, front-loading the main purpose and flow. It is slightly lengthy but every sentence adds value, making it effective despite not being maximally concise.

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

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

Covers the main functional aspects including search-describe-invoke flow, install vs invoke, and credential/payment handling. Lacks details on output format and some parameter specifics, but given the complexity, it is fairly 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?

The description explains the 'action' parameter and gives context for query, mcp_id, tool_id, and arguments within the workflow. However, with 15 parameters and 0% schema description coverage, it does not systematically cover all parameters (e.g., limit, immediate, tier_slug), leaving 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 mcp.ai marketplace for discovering, describing, and running MCPs/tools. It distinguishes itself from external registries and sibling tools by explaining its core flow (search, describe, invoke) and how it relates to other actions like install, list_tools, etc.

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

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

Provides explicit guidance on when to use this tool first, when to prefer invoke over install, and when workspace owner/admin is required. It also explains how to handle credential and payment scenarios with connect/checkout links and retry behavior.

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

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

Annotations already indicate destructive hint, so the description adds value by specifying that it revokes consent, deletes data, and returns a re-connect URL. 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, concise and front-loaded with the key action and consequences. 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?

Missing output schema is compensated by mentioning the return URL, but the lack of parameter explanation leaves the tool incomplete for an agent to invoke correctly.

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

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

The input schema has 0% description coverage for the required 'item' parameter. The description does not clarify what 'item' represents (e.g., bank ID or connection ID), leaving ambiguity.

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

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

The description clearly states the tool revokes consent and deletes connection data, making data unavailable. It distinguishes well from sibling tools like openfinance_force_sync or list 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 explains the effect (data unavailable) and returns a re-connect URL, but does not explicitly state when to use this tool versus 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 indicate non-read-only and non-destructive. The description adds behavioral context beyond annotations: it waits up to ~60s, returns results/errors, explains return fields (status, executionStatus, lastUpdatedAt, synced), and notes the wait:false alternative. 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 well-structured with front-loaded main action, followed by conditions and return details. While slightly long, every sentence adds value. Minor room for tightening but no redundant information.

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

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

Given no output schema, the description covers return structure and error/status states comprehensively. It also differentiates from sibling tools like openfinance_get_item_status, ensuring the agent knows when to use each.

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 compensates: it explains the boolean `wait` parameter for synchronous vs fire-and-forget, and the array `items` parameter with allowable selectors (item_id, connector_id, connector_name) and default behavior (sync all when omitted). This provides complete 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 defines the tool's purpose with a specific verb ('forces re-sync') and resource ('one or more connections'), distinguishing it from disconnecting/reconnecting. It also contrasts with sibling tool openfinance_get_item_status by mentioning it for timed_out cases.

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

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

The description provides explicit usage guidance: use when data looks stale, pass items as selectors or omit for all, set wait:false for fire-and-forget. It also advises on subsequent steps for needs_action and timed_out scenarios. Lacks explicit when-not-to-use but is clear overall.

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 non-destructive nature. Description adds real-time behavior, structured error handling (warning vs error), and degradation details, enriching 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?

Concise and front-loaded: first sentence covers purpose, then details. Every sentence adds value 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?

Covers response shape, error handling, degradation, and array constraints. No output schema exists, but description provides sufficient detail for a read-only balance tool.

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

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

Despite 0% schema coverage, the description compensates by specifying that account_ids is an array with size constraint (1-50), which is not in 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?

Clearly states 'Returns real-time balance payload per account id' and specifies the REST endpoint. Distinguishes from sibling tools that handle other account details or lists.

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 usage context: pass account_ids as array (1-50), describes error and degradation behavior. Does not explicitly list when not to use, but the purpose 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?

Adds important behavioral context beyond annotations: batch response shape, provider_incident block, and warning about unreliable balances. Annotations already indicate read-only, so description enhances.

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 4 sentences, front-loaded with purpose, then details. Could be slightly more structured but efficient.

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

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

Covers response shape, batch structure, and potential reliability issues. No output schema, but description provides sufficient context for a detail endpoint.

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?

Adds array size constraint (1-50) and clarifies usage of 'account_ids' parameter, which is not described in the schema (0% coverage).

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

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

Description clearly states it returns full account objects by ID with creditData, but does not explicitly differentiate from sibling tools 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?

Provides cautions about unreliable data during provider incidents, but no explicit guidance on when to use this vs 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?

Discloses beyond annotations: batch shape { results, errors }, absence of individual transactions, that Pluggy does not return a paid/status field, and crucial nuance about payments[] reflecting previous bill's payment in Brazilian Open Finance. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint are 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?

Description is fairly long but every sentence adds value. It is front-loaded with the main purpose and usage. Some detail (e.g., Brazilian Open Finance note) could be more concise but is justified given the tool's complexity. No redundant 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?

Given no output schema, the description explains the return shape (batch shape, fields like financeCharges and payments with subfields), caveats about payment status, and cross-references sibling tools for discovery and transactions. Complete for a single-parameter 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?

Input schema has only one parameter (bill_ids array of strings) with 0% schema description coverage. The description adds significant semantics: clarifies that bill_ids should be an array, and advises using openfinance_list_credit_card_bills first to discover ids. Fully compensates for lack of schema description.

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

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

The description clearly states it returns bill-level detail for credit card bills by id, and distinguishes from sibling tools like openfinance_list_credit_card_bills (for discovery) and openfinance_list_transactions (for itemized transactions). The verb 'returns' plus resource 'bill-level detail' makes the purpose specific and unambiguous.

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

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

Explicitly advises when to use this tool (bill-level detail) and when not to (for individual transactions, prefer openfinance_list_transactions). Also warns against reconstructing bill totals from transactions and recommends using openfinance_list_credit_card_bills first to discover ids. Alternative tools are named and context 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is clearly safe. The description adds useful return format details (status, executionStatus, connector metadata, and the `{ count, items }` shape for all banks), providing behavioral context beyond annotations.

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

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

Two concise sentences. First sentence conveys the function and return contents. Second sentence explains the two usage modes with clear syntax. No unnecessary words.

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

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

Given the tool's low complexity (one optional parameter, no output schema), the description provides complete guidance: return values, use cases, and output shape. No missing critical information.

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?

Though the schema has 0% parameter description coverage, the description fully explains the sole parameter `item`: omitting it returns all banks, passing it returns a single bank. This adds complete semantic meaning beyond the raw schema.

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

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

The description clearly states it returns the current status of a bank connection, listing example statuses (UPDATED, UPDATING, LOGIN_ERROR), executionStatus, and connector metadata. It also explains two distinct usage modes (all banks vs. single bank), differentiating 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 explicitly explains when to omit or pass the `item` parameter, covering both use cases. However, it does not directly compare with sibling tools or state when not to use this tool, missing a clear alternative recommendation.

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, covering safety. The description adds the batch output shape and endpoint 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?

The description is a single paragraph that efficiently conveys purpose, usage, parameter details, and output, 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 no output schema, the description thoroughly lists the returned fields (interest rates, charges, warranties, schedule, etc.) and explains the batch shape, making it complete for the agent to understand the output.

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 that loan_ids is an array of 1-50 items and mentions the batch return shape, which is not in the schema. With 0% schema coverage, this compensates well, though the format of each ID string is not specified.

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 retrieves full loan contract detail by ID, listing specific fields. It distinguishes from sibling tool openfinance_list_loans by specifying this is for deep-diving after listing contracts.

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 'Use after openfinance_list_loans to deep-dive on a specific contract', providing direct guidance on when and how to use the tool.

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

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

Annotations indicate read-only, idempotent, and non-destructive behavior. The description goes beyond by clarifying that credit balance meaning is connector-dependent, that provider_incident may appear and balances could be unreliable, and that the response aggregates accounts from all connections when 'item' is omitted. 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 thorough and front-loaded with the main purpose. It is slightly verbose but every sentence adds value. It could be slightly more concise, but the structure is logical and easy to follow for 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?

No output schema exists, but the description explains the return values (accounts with fields like balance, number, type, subtype, bankData, creditData, plus bank and connector_id) and mentions the optional provider_incident block. It also points to a sibling tool for credit card bills, providing a complete picture for 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?

Schema description coverage is 0%, so the description fully compensates. It explains that 'item' targets a single bank, while omitting it lists all accounts. It explains that 'type' filters by BANK or CREDIT. This provides essential meaning beyond the schema's name and enum values.

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 accounts for a bank connection, distinguishes between BANK and CREDIT, and details the returned fields. It differentiates from sibling tools by specifying it lists accounts with balance, number, type, etc., and provides guidance on when to omit or pass the 'item' parameter.

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

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

The description explicitly states when to omit 'item' (for all banks) and when to pass it (for a single bank). It warns about the connector-dependent meaning of credit balance and directs users to identify the standardized open-bill amount using openfinance_list_credit_card_bills. It also explains the provider_incident block and advises not to present unreliable values.

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. The description adds value by noting caching behavior and that it returns a single aggregated response with no batch ids.

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

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

The description is a single sentence that front-loads the main action and includes essential details about the response fields. Slightly dense 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?

Given no parameters and no output schema, the description fully explains the response structure (fields like id, description, parentId) and mentions caching and usage context. It is complete for this simple list tool.

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

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

The input schema has zero parameters, so the description does not need to cover parameter details. Full schema coverage (100%) with no parameters means baseline 4 applies.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy via GET /categories, cached for the session. It distinguishes from sibling tools that deal with accounts, transactions, etc.

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

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

No explicit when-to-use or when-not-to-use guidance. The description implies it can be used before openfinance_update_transaction_category because it mentions the categoryId, but it does not provide clear guidelines on context 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 provide readOnlyHint=true and destructiveHint=false, so the description does not need to repeat those. It adds value by specifying the returned data fields and the add_connection_url, giving clear behavioral context beyond annotations.

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

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

The description is a single concise sentence that front-loads the core purpose ('Returns the saved bank connections') and then lists key fields and the add_connection_url. Every part adds value 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?

The tool has no parameters and no output schema, so the description carries the full burden. It completely describes what the tool returns (specific fields) and mentions the add_connection_url, which is enough for an agent to understand its behavior. No obvious 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?

With no parameters and 100% schema description coverage, the description does not need to explain parameters. It correctly focuses on explaining the output, which is appropriate for a parameterless 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 that the tool returns saved bank connections for the install, listing specific fields (connector_id, item_id, bank name) and an add_connection_url. This directly addresses the tool's purpose and distinguishes it from siblings like openfinance_list_accounts or connect.

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 indicates the tool is for listing saved connections and provides an add_connection_url for linking more banks, implying when to use it. However, it does not explicitly state when not to use it or mention alternatives among siblings, though the 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?

Annotations provide readOnlyHint (true), idempotentHint (true), destructiveHint (false). Description adds critical behavioral traits: payment_status derivation logic (pre-payment vs cross-bill matching), PAST_DUE_UNCONFIRMED status, open bill availability fallbacks, bill_grouping_reliability warning, and response warning on disabled product. 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?

Description is very detailed and informative but excessively verbose with run-on sentences and nested clauses. While front-loaded with core purpose, it could benefit from structured sections (e.g., 'Payment Status', 'Open Bill', 'Connector Notes'). Every sentence adds value, but readability is reduced. A more concise rewrite would improve.

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 Brazilian Open Finance bill semantics, the description is remarkably complete. It covers payment_status derivation edge cases, connector asymmetry for open bills, bill grouping warnings, and fallback behavior. No output schema exists, but return fields are described in detail. All scenarios (success, warnings, unavailable open bill) are addressed.

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 thoroughly explains include_open_bill (opt-in, derived data, reliability warnings) and account_ids (bulk support). Page/page_size are mentioned but not detailed (e.g., default values not given). The required account_id is implicit from context. Meaningful context beyond schema is provided for key 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 explicitly states it returns closed credit card bills for a credit-type account, listing key fields like dueDate, totalAmount, payments[], and derived payment_status. It clearly distinguishes from sibling tools such as openfinance_list_transactions (itemized purchases) and openfinance_get_credit_card_bill (singular bill). The verb 'returns' and resource 'CLOSED credit card bills' are specific.

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

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

Provides extensive when-to-use guidance: use for closed bills, avoid reconstructing totals from transactions by billId, use openfinance_list_transactions for itemized data. Includes caveats for payment_status derivation, connector asymmetry, and opt-in include_open_bill. Explicitly warns about grouping reliability and bank app verification.

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 valuable context: it returns a structured error object ({total:0, results:[], warning}) instead of throwing on 403 or other errors. It also lists specific return fields (balance, amount, rate, dueDate, etc.), which is beyond annotation coverage.

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

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

The description is a single paragraph that front-loads the main purpose and includes useful detail on asset types and return fields. It is slightly long but mostly 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?

Without an output schema, the description partially covers return shape (fields like balance, amount, etc.) but lacks parameter documentation. This leaves gaps for an agent to understand how 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?

With 0% schema description coverage, the description must explain parameters. It does not: it mentions item, page, type, and page_size in the schema but provides no explanation of their meaning, formats, or usage. This is a critical gap.

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

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

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

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 retrieving investment portfolio data, but does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions or prerequisites. The context is clear but guidance on selection is absent.

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 destructiveHint. The description adds significant behavioral context: it lists the types of transactions returned and details the fields included (quantity, value, expenses breakdown). This goes beyond what annotations provide, though it could mention pagination 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?

Two short paragraphs: first defines purpose and key fields, second mentions bulk support. No filler, every sentence provides value. Front-loaded with the most important 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?

No output schema exists, so the description must explain return values. It does so by listing fields and types of transactions. It also addresses bulk execution. However, it omits pagination details (page, page_size) which are present in the schema but not explained.

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

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

The input schema has zero description coverage for individual parameters. The description mentions investment_id and investment_ids in context but does not explain required format, page, or page_size. Given low schema coverage, the description insufficiently compensates for parameter meaning.

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

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

The description clearly states the tool returns movement history for investment positions, listing specific transaction types (BUY, SELL, etc.). It also provides usage context by referencing a sibling tool, helping distinguish it from similar tools.

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

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

The description explicitly advises using this tool after openfinance_list_investments to obtain investment_id, and mentions bulk support. However, it does not specify when not to use it or exclude alternatives beyond the single sibling mention.

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 and idempotentHint; description adds sequential execution with rate-limit spacing and return format `{ results, errors }` per connection, providing behavioral context beyond annotations.

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

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

Four tightly focused sentences: purpose, parameter usage, omission case, return shape. No fluff; front-loaded with core action.

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 endpoint, parameter usage, behavior (sequential, rate-limited), and return structure. For a simple list operation with one optional parameter and no output schema, this is nearly complete. Minor omission: no pagination mention, but acceptable.

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 explains `items` parameter in detail: allowed values (item_id uuid, connector_id, connector_name), purpose per connection, and special case of omitting to fetch all. Adds full meaning beyond 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 verb 'list', resource 'loan contracts', and scope 'per bank connection' with the GET /loans endpoint. It distinguishes from sibling tools like openfinance_list_accounts by specifying the resource and connection-based filtering.

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 when to pass `items` (for specific connections) and when to omit (all linked banks). Also notes sequential querying with rate-limit spacing. No explicit 'when not to use', but sibling names make differentiation 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 declare readOnlyHint=true and idempotentHint=true. The description adds significant behavioral details: error handling returns a structured object instead of throwing, pagination auto-aggregates up to 5000 transactions, and the detail parameter affects data richness and token cost. It also mentions provider incidents and per-connector inconsistencies, providing full transparency 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 lengthy but well-organized with clear sections. It front-loads the core purpose and then systematically covers details. While some repetition exists (e.g., billId caveat appears twice), the structure is logical and each sentence adds value, though it could be slightly more concise.

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

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

Given the tool's complexity (8 parameters, no output schema, multiple behavioral nuances), the description is exceptionally complete. It covers error states, pagination, relationship with sibling tools, per-connector variability, troubleshooting steps (checking item status), and response structure with account echo block. No gaps are evident.

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

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

Schema coverage is 0%, so the description must explain each parameter. It does so thoroughly: from/to as ISO date filters, page omitting for auto-pagination or explicit for manual, page_size max 500, detail options with explanations (compact, rich, raw), search_queries with case-insensitive substring match and OR semantics, and account_id/account_ids for batch. The description adds meaning that the schema lacks entirely.

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 a bank account, distinguishing between BANK and CREDIT types, and emphasizes that for CREDIT accounts it is the only way to get itemized transactions. It also clarifies the relationship with credit card bills, making the purpose very specific and unambiguous.

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

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

The description provides extensive guidance on when to use this tool vs. alternatives. It explicitly warns not to reconstruct a bill's total by summing transactions by billId, directs users to openfinance_list_credit_card_bills for standardized open-bill total, and advises using openfinance_list_accounts for closing/due dates. It also covers pagination options and error handling, making alternative tools and appropriate contexts 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?

Beyond annotations (readOnly, idempotent), description discloses scan cap of 5000/account with truncated flag and provider_incident block. 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?

Front-loaded with purpose, then structured as logical flow: what it does, how to use, parameters, use cases, edge cases. Every sentence adds value without repetition.

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

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

Covers all aspects: purpose, usage, parameter details, return structure (compact summary with totals, monthly evolution, top expenses/revenues, per-account breakdown; raw with transaction rows, detail options), and edge cases (truncation, provider incidents). No output schema, but description compensates fully.

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, description explains meanings for all 7 parameters: from/to as ISO dates, item as connector identifier, granularity and detail options with effects, type filter, and top_n implied by 'largest N'. Each parameter's role is clarified.

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

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

Description clearly states it provides consolidated cash-flow analysis for a connection in one call, distinguishing it from sibling tools that require account_id. Specific verb ('analyze') and resource ('connection transactions') are evident.

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

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

Explicitly explains when to use (for annual/monthly analysis, cash flow, etc.) and when not to (no need to call openfinance_list_accounts first). Describes conditions for granularity and warns about provider incidents.

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 tool is read-only (reads public status page), consistent with annotations. Adds details on return values: global indicator, degraded components, incidents, and affected banks. Exceeds annotation info.

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?

Every sentence serves a purpose: first states what it does, then when to use, then what it returns. No fluff. Well front-loaded with the primary action.

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?

Fully explains purpose, usage scenarios, return values, and distinguishes from sibling. No missing context despite lacking output schema. Annotations already cover safety, description adds depth.

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 input parameters, so baseline is 4. Description doesn't need to add parameter details, and it provides no extra parameter info. Adequate for a zero-parameter tool.

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

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

Clearly states it checks the PROVIDER's health, distinct from the connection's status. Uses specific verb 'checks' and resource 'LIVE operational status of the Open Finance provider'. Distinguishes from sibling 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 states when to use: when data is incomplete/stale despite updated status. Tells it reveals upstream outages or incidents. Provides clear context and differentiates from connection status 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 readOnly, idempotent, and non-destructive behavior. The description adds behavioral details about the caveat for non-Open-Finance connectors (no auto-update), the plan-based filtering, and the fact that it returns a connect_url, going well 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 concise, well-structured with the main purpose first, and each of the roughly six sentences adds essential information. No redundant or unnecessary content.

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

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

The description covers what the tool does, what it returns (including edge cases like caveat), when to use it (before connecting), and key constraints (required keywords, plan filtering). Despite no output schema, the information provided is sufficient for the agent to understand the tool's full behavior.

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 explains both parameters: keywords is an array of strings with examples, and include_accounts controls whether accounts are returned. It also clarifies behavior when keywords is omitted (returns a hint). This compensates completely for the bare schema.

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

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

The description clearly states the tool searches bank connectors by name and returns specific fields including connector id, access type, audience, and connect_url. It distinguishes itself by noting it should be called before connecting, setting it apart from sibling tools like connect.

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 this tool before connecting to provide a one-click link, mentions that keywords is required and without it returns a hint, gives guidance on preferring Open Finance connectors over credential-based ones, and notes that the user's plan is honored (PF hides PJ banks).

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 (which only indicate non-readonly, non-destructive, etc.), the description reveals critical side effects: recategorizing automatically creates a Category Rule that affects future transactions. It also details batch error handling (partial failures). This goes well beyond what annotations provide.

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

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

The description is a single dense paragraph that includes all necessary information. While it is informative, it could be more scannable (e.g., using bullets for response shape). However, it is not overly long and front-loads the core purpose.

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

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

Given no output schema, the description provides the return shape and error handling. It covers all needed context: purpose, parameter explanation, side effects, and batch behavior. No gaps remain for the agent to invoke correctly.

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

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

The schema has 0% description coverage, yet the description fully explains the `items` parameter structure: an array of objects with transaction_id and category_id, where these IDs come from, and the response shape (updated, results, errors). This compensates entirely for the schema's lack of descriptions.

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

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

The description clearly states the tool's purpose: 'Corrects the category of one or more transactions' with the HTTP method (PATCH) and endpoint path, making the verb+resource relationship explicit. It also distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_categories by referencing them as sources for IDs.

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

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

The description explains when to use the tool (to fix miscategorized transactions and improve categorization accuracy) and provides guidance on sourcing IDs from other tools. However, it lacks explicit when-not or alternative tool recommendations, leaving a slight gap.

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 include idempotentHint=true, which aligns with logging feedback. The description adds no behavioral traits beyond purpose, but the tool is straightforward. No contradictions with annotations.

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

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

The description is a single, clear sentence that front-loads the purpose. It is concise, but could be slightly more structured by separating the reporting types from the reproduction instruction.

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

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

Given the lack of output schema and only 0% schema description coverage, the description should provide more context about return values, expected format of 'conversation' (JSON string), and the role of 'context'. The current description leaves these 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%. The description only adds meaning for the 'conversation' parameter (mentioning it should contain recent messages for reproduction) but does not mention 'context' or specify that 'conversation' should be a JSON string. This is insufficient for a 3-parameter tool.

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

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

The description clearly states the tool's purpose: reporting bugs, missing features, or sending feedback. It uses a specific verb and resource, and distinguishes itself from sibling tools which are 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 provide guidance on when to use this tool versus alternatives. It mentions including the conversation array but offers no context about prerequisites or situations where this tool is appropriate.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, which tell the agent this tool is safe and idempotent. The description adds no additional behavioral context (e.g., no mention of return format or side effects). With annotations doing the heavy lifting, the description adds minimal extra value, so a score of 3 is appropriate.

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

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

The description is a single sentence with no wasted words. It is perfectly concise and front-loaded, immediately communicating the tool's purpose.

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

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

Given no parameters and no output schema, the description is mostly complete. It states what versions are shown (platform and adapter). However, it does not mention whether the output is JSON or plain text, but this is minor. Annotations fill safety gaps. A score of 4 reflects that it is adequate but could benefit from a brief note on output format.

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 parameters, so schema_description_coverage is 100%. Baseline is 3, and the description adds no parameter information because none exist. No additional meaning is needed 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 shows the current MCP platform and adapter versions. It uses a specific verb ('Show') and resource ('versions'), and the purpose is distinct from all sibling tools, which either authenticate, connect, or perform openfinance 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?

No explicit guidance on when to use this tool vs alternatives is provided. However, given its simple informational nature and the absence of parameters, usage is implicitly clear: use it when you need version information. No when-not or alternatives are mentioned, but the context of sibling tools makes it obvious.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context by specifying the exact return contents (installed MCPs, status, catalog counts), which goes beyond the annotations.

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

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

A single sentence that is clear, front-loaded with the main purpose, and contains no extraneous information. Every word earns its place.

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

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

Given the simplicity (no parameters, no output schema), the description adequately describes what is returned. It could include an example or mention of the format, but it is complete enough for an agent to understand the output.

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 no parameters, so the description does not need to add parameter information. Baseline for 0 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 the tool returns current toolkit state with specific details (installed MCPs, connection status, catalog tool counts). It uses a specific verb-resource pair ('Returns the current toolkit state') and distinguishes itself from sibling actions like authenticate or connect.

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 for checking toolkit state but does not explicitly state when to use it versus alternatives like show_version or other info tools. No exclusion criteria or when-not guidance is provided.

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