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?

Annotations provide readOnlyHint and idempotentHint. The description adds context on output variation (authenticated:true vs connect_url) 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?

Two sentences, no wasted words, front-loaded with core function. Every sentence adds value.

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

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

Given no parameters, no output schema, and robust annotations, the description adequately covers the tool's behavior. Could mention return format but not necessary.

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, and schema coverage is 100%. The description adds meaning by explaining the output based on connection state, which is sufficient for a no-param 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 explicitly states the tool returns connection status and URLs, with specific behavior for both connected and missing credentials cases. This clearly distinguishes it from siblings like authenticate or marketplace.

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

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

The description implies when to use (to check connection status), but does not explicitly guide when not to use or compare with siblings like authenticate. No exclusions 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?

The description discloses key behaviors beyond annotations: invoke works even for non-installed MCPs, returns connect or checkout links as needed, and writes (install/uninstall/subscribe/cancel) require owner/admin. It explains the one-off installation behind invoke. These details add significant context that the annotations (which are generic) do not 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 comprehensive but verbose. It front-loads the purpose and core flow effectively, but the detailed breakdown of every action (install, subscribe, etc.) could be condensed. While each sentence adds value, the length detracts from quick scanning.

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 (13 params, multiple actions, no output schema), the description is remarkably complete. It explains the search-describe-invoke workflow, when to use alternative actions (list_tools, report_bug, request_mcp), and how to handle credential/payment scenarios. It covers all major behavioral aspects needed 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?

With 13 parameters and 0% schema description coverage, the description compensates well by explaining the action enum and how mcp_id, tool_id, and arguments are used in the flow. However, several parameters (limit, query, immediate, etc.) are not individually described, leaving some gaps. The description still adds meaningful structure to the parameter usage.

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

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

The description clearly states the tool's role as 'the official mcp.ai marketplace' and explicitly contrasts it with sibling tools by outlining the core discovery flow (search → describe → invoke). It defines the tool as the primary entry point for finding and running MCPs, which distinguishes it from other tools 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 provides explicit guidance: use this tool first for capability searches before any external registry. It details when to invoke (one-off, even if not installed) versus install (permanent addition), and when to use search versus describe. It also notes permission requirements for write actions (workspace owner/admin).

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 destructiveHint=true. The description adds that data becomes unavailable and returns a reconnection URL, providing useful behavioral context beyond the annotation.

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

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

Two sentences, no wasted words. Front-loaded with the primary action and outcomes.

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 a simple single-parameter tool, the description fails to explain the parameter's meaning or how to obtain it, which is critical for a destructive operation. No output schema to compensate.

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

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

The only parameter 'item' (string) has no description in the schema (0% coverage) and the tool description does not clarify what 'item' should represent (e.g., bank ID or connection ID), leaving the agent without 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 revokes consent and deletes connection data for a specific bank, using specific verbs ('Revokes', 'deletes') and resource ('bank'). It distinguishes from sibling tools like 'connect' and '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 implies usage for disconnecting a bank and mentions a reconnection URL, but does not explicitly state when to use this tool versus alternatives like 'connect' 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?

Discloses that it does a PATCH then polls up to ~60s, and describes return fields (status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out). Adds significant context beyond annotations (readOnlyHint=false, destructiveHint=false). 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 comprehensive yet efficient, with every sentence contributing essential information. It front-loads the primary action and organizes details logically 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?

Given no output schema, the description fully explains the return format and key fields. It covers error conditions (needs_action, timed_out) and recommends follow-up tool, making it complete for autonomous 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 description coverage, the description fully explains both parameters: 'items' as array of selectors (item_id, connector_id, connector_name) with omission meaning all banks; 'wait' boolean with default behavior (waits) and fire-and-forget option. Provides concrete examples and 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 forces a re-sync of bank connections and waits for it to finish. It distinguishes itself from sibling tools by noting it pulls fresh data without disconnecting, and mentions alternative tools like openfinance_get_item_status for checking timed-out syncs.

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/transaction list, connection showing UPDATED but hours old) and mentions alternative tool for re-check. Lacks explicit 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds real-time nature, error handling for CREDIT accounts (structured warning vs throw), and response shape. 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?

Three sentences, front-loaded with purpose and endpoint, then parameter guidance, then error/response details. No filler.

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

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

Given simple parameter set, no output schema, and no nested objects, description covers parameter usage, error behavior, and response structure adequately. No obvious missing 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?

Schema coverage is 0%, so description compensates well: specifies array size constraint (1–50) and clarifies that IDs are strings (though schema already has type). Adds 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?

Description clearly states it returns real-time balance for an account ID and specifies the REST endpoint. However, it does not explicitly differentiate from sibling tools; the sibling set lacks another balance-specific tool, so differentiation is not critical but still a minor gap.

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 parameter guidance (array of 1-50 IDs) and notes CREDIT account behavior. Lacks explicit when-to-use or when-to-avoid context, no mention of 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 read-only, idempotent behavior. The description adds value by specifying the batch shape ({ results, errors }), the endpoint (GET /accounts/:id), and that it returns extended creditData, which goes beyond the 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, no filler. First sentence states core purpose and response richness; second specifies parameter and response shape. Every word serves a purpose.

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

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

Given no output schema, the description covers the return shape ({ results, errors }) and indicates extended creditData, but lacks detail on the actual account object structure. Could be more complete by describing typical fields.

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 that account_ids is an array with a 1–50 limit and its purpose. This provides complete semantic meaning for the parameter.

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, specific to a resource by ID. It distinguishes from sibling tools like openfinance_list_accounts by focusing on detailed retrieval per account ID.

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 retrieving detailed account data by IDs, but does not explicitly state when to use this versus alternatives like openfinance_list_accounts or other detail endpoints. No 'when not to use' guidance is 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), description discloses that the tool does NOT return individual transactions, notes absence of paid/status field, explains batch shape, and clarifies payment semantics. All behavioral traits are transparent.

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 informative but slightly long; essential info is front-loaded. Some minor redundancy (e.g., repeats 'does NOT return individual transactions' in different forms). Still, efficient given the complexity.

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 fully explains return shape ({ results, errors }), lists returned fields, and notes missing fields. Covers all necessary context for correct usage, including Brazilian Open Finance nuances.

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

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

Schema coverage is 0%, so description fully bears the burden. It explains the single parameter bill_ids is an array, instructs to use list tool to discover ids, and gives purpose. Adds meaningful context beyond schema type.

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, listing specific fields (financeCharges, payments). It distinguishes from sibling tools openfinance_list_transactions and openfinance_list_credit_card_bills, making the purpose unambiguous.

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

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

Explicitly guides when to use this tool vs alternatives: 'to get itemized transactions, use openfinance_list_transactions', 'use openfinance_list_credit_card_bills first to discover ids', and warns about interpreting payments[] via cross-bill match. Provides clear context for correct invocation.

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, destructiveHint, and idempotentHint as safe, which the agent can rely on. The description adds value by specifying the returned fields (executionStatus, connector metadata) and the response structure for the aggregate case ({ count, items }). 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 two sentences, front-loaded with the primary purpose. Every sentence provides distinct value—first sentence defines output, second sentence explains parameter usage. No unnecessary words or repetition.

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

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

Given the tool's simplicity (one optional parameter, no output schema, clear annotations), the description covers all relevant usage scenarios: the two modes, the response contents, and is sufficient for an agent to invoke correctly without ambiguity.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that the 'item' parameter is optional; omitting it returns all banks, passing it returns a single bank. While it does not specify the expected format or source of the item value, it adds meaningful context beyond the schema's minimal type 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?

The description explicitly states the tool returns the current status of a bank connection, listing possible values like UPDATED, UPDATING, LOGIN_ERROR, etc. It clearly distinguishes between two modes: omitting 'item' returns all linked banks, passing 'item' returns a single bank. This differentiates from sibling tools like openfinance_list_connections or openfinance_provider_status.

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

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

The description provides clear when-to-use guidance: 'Omit item to get the status of ALL linked banks at once; pass item for a single bank.' While it does not explicitly mention when not to use or alternatives, the guidance is actionable and sufficient for the agent to decide. A score of 4 reflects minor room for improvement in specifying exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: that CREDIT balance is connector-dependent, that billing cycle is defined by creditData.balanceCloseDate/balanceDueDate, and that the response structure changes based on whether 'item' is provided. No contradiction exists.

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

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

The description is fairly long but well-structured: it starts with the core purpose, then details fields, clarifies ambiguous terms ('name' vs 'bank'), and provides usage notes. Every sentence adds value, especially given the complexity of the tool. Slightly more could be trimmed, but it remains efficient.

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

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

With no output schema, the description fully explains the return structure, including dynamic root vs. results array based on 'item', field descriptions, and warnings about CREDIT balance. It also references an alternative tool for standardized bill data. This is complete for a tool with complex behavior and 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%, so the description carries the full burden. It explains both parameters thoroughly: 'item' targets a single bank vs. omit for all banks, and 'type' is an enum with BANK/CREDIT values. The description adds semantic meaning far beyond what the raw schema provides, making it clear when and how to use each parameter.

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

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

The description clearly states that the tool returns accounts for a bank connection, distinguishes between BANK and CREDIT types, lists specific fields (balance, number, type, subtype, bankData, creditData, bank, connector_id), and explains that 'name' is the legal entity while 'bank' is the brand. This specificity distinguishes it from sibling tools like openfinance_list_credit_card_bills and 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?

The description provides explicit guidance on when to omit 'item' (to list across all banks) vs. when to pass it (to target a single bank). It also advises that CREDIT balance meaning is connector-dependent and should not be treated as 'this month's bill', and directs users to openfinance_list_credit_card_bills for standardized amounts. This clearly covers when to use and when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: results are cached for the adapter session, and it explains the response structure (single aggregated response, no batch ids). No contradictions.

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

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

Two sentences, front-loaded with purpose. Every sentence adds value: purpose, caching, field details, and link to sibling tool. 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?

Despite no output schema, the description fully explains the response fields. Caching behavior is disclosed. 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?

No parameters, schema coverage 100%. With zero parameters, baseline is 4. Description adds no parameter info needed.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy, cached per session. It specifies each entry's fields (id, description, descriptionTranslated, parentId, parentDescription). This distinguishes it from sibling tools which list transactions, accounts, 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?

The description implies usage for obtaining category IDs needed by openfinance_update_transaction_category, but does not explicitly state when to use this tool versus alternatives or when not to use it. No guidance on exclusion criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying the returned data and the 'add_connection_url' field, but could further emphasize the no-side-effect behavior.

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

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

The description is a single sentence that front-loads the main purpose and lists key returned fields. Every word is informative; no wasted space.

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 sufficiently explains what the tool returns and its purpose. The agent can infer the expected output without 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?

The input schema has 0 parameters, so the description does not need to add parameter meaning. Baseline 4 is appropriate as there is nothing to improve.

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 tools like openfinance_list_accounts by clarifying it lists connections, not 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 implies the tool is for listing bank connections, but it does not provide explicit guidance on when to use it versus alternatives (e.g., when to use openfinance_get_item_status instead) or any exclusions.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. Description adds substantial behavioral context: payment derivation, cross-bill matching, open bill fallback (available false with reason), derived payment_status, and the fact that open_bill requires an extra scan. 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 very detailed and front-loaded with key information. While every sentence adds value, the length could be slightly reduced for efficiency. However, given the complexity, the structure is logical and well-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?

Despite no output schema, the description fully explains return values (including derived fields like payment_status and open_bill structure). Covers edge cases (connector asymmetry, PAST_DUE_UNCONFIRMED, fallback methods), bulk support, and product enablement warnings. References sibling tools for deeper detail.

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

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

Schema has 0% description coverage, so description must compensate. It thoroughly explains account_id (required), account_ids (bulk), include_open_bill (opt-in with detailed semantics), and implies pagination with page/page_size. Each parameter’s purpose and behavior are clearly conveyed.

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

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

The description clearly states it returns CLOSED credit card bills for CREDIT accounts and lists specific fields (dueDate, totalAmount, etc.). It distinguishes from sibling tools like openfinance_get_credit_card_bill and openfinance_list_transactions, and mentions bulk support via account_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?

Provides explicit guidance on when to use: for closed bills, with opt-in for open bill. Explains payment semantics, cross-bill logic, and connector asymmetry. Warns against assuming payment status based on payments[] alone, and directs to use list_transactions for itemized charges.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by explaining the error handling behavior (returns {total:0, results:[], warning} instead of throwing) and listing specific fields returned, 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?

The description is a single dense paragraph but is informative without wasted words. It could benefit from better structure (e.g., separating parameter and return info) but remains 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 no output schema, the description covers return fields and error handling reasonably well. However, it lacks parameter documentation and does not explain pagination or filtering by type, which are critical for effective use.

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

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

Schema description coverage is 0%, meaning the description must explain parameters, but it provides no documentation for the four parameters (item, page, type, page_size). The description only lists return fields, leaving the user guessing about parameter usage.

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

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

The description clearly states the tool returns investment portfolio details for a connection with specific asset types (FIIs, stocks, ETFs, etc.) and distinguishes it from sibling tools like openfinance_list_accounts or openfinance_list_transactions by specifying the investment focus.

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 (for connections with INVESTMENTS product enabled) and how it handles errors (returns a structured response instead of throwing a 403). However, it does not explicitly contrast with the sibling openfinance_list_investment_transactions.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds concrete details about the data returned (quantity, value, expenses breakdown, etc.) and transaction types, providing behavioral context 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?

The description is concise with two focused paragraphs. It front-loads the purpose and key data fields, then addresses bulk support. No redundant sentences, though a more structured list of parameters could improve scannability.

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 4 parameters, no output schema, and returns complex data. The description lists the main fields and transaction types, which is sufficient for an agent to understand the return envelope. However, it lacks details on pagination behavior and default page sizes, which slightly reduces completeness.

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

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

Schema coverage is 0%, so the description must compensate. It explains the main parameter investment_id and the bulk parameter investment_ids, but does not explain page and page_size. This adds partial meaning but leaves pagination undefined.

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 movement history for a specific investment position, listing transaction types (BUY, SELL, etc.) and fields. It explicitly distinguishes from the sibling tool openfinance_list_investments by instructing users to use it after obtaining the investment_id.

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

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

The description provides clear context on when to use the tool (after openfinance_list_investments) and mentions bulk support via investment_ids. It does not explicitly state when not to use it, but the relationship with sibling tools is clear enough for an agent to decide.

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 disclosing sequential per-connection execution with rate-limit spacing and the return format { results, errors } per connection.

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

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

Two sentences plus a brief note about return. Front-loaded with purpose, then parameter usage, then omission behavior. 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 1 optional parameter, no output schema, but the description covers parameter semantics, execution behavior (sequential with rate-limit), and return format. Complete enough 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?

Schema coverage is 0%, but the description fully explains the `items` parameter: an array of connection selectors (item_id uuid, connector_id, or connector_name) with one entry per connection. It also clarifies the effect of omitting `items`.

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 'Lists loan contracts per bank connection (GET /loans).' It specifies the verb (lists) and resource (loan contracts), and distinguishes from sibling list tools by focusing on loans and bank 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 explicit guidance: pass `items` for specific connections or omit for all banks. It explains sequential querying with rate-limit spacing. However, it does not explicitly state when not to use this tool versus 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 annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description enriches these by detailing the behavior of date filters, pagination with a max of 500 per page, search_queries aggregation with truncation warning, error handling returning a structured object instead of throwing, and specific credit card pending/posted behavior varying by connector. No contradictions with annotations.

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

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

The description is lengthy but well-structured, starting with the main purpose, then diving into credit card specifics, filtering, error handling, and bulk support. Each paragraph adds necessary context, though some repetition (e.g., mentioning search_queries twice) could be trimmed. Overall, it is efficient given the complexity.

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 most aspects needed for a transaction listing tool: account type differentiation, bill linking, pagination, search behavior, error handling, and troubleshooting. It lacks explicit mention of the output transaction structure (though no output schema is provided) and default pagination values, but these are minor gaps given the detailed explanations provided.

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 well by explaining the purpose of each parameter: from/to (ISO YYYY-MM-DD), page_size (max 500), search_queries (case-insensitive substring match with OR semantics), and bulk support via account_ids. However, it does not explicitly mention the 'page' parameter or default pagination behavior, and it omits detailed type 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 clearly states the tool returns transactions for bank accounts of type BANK or CREDIT. It distinguishes between account types, especially noting that for CREDIT accounts this is the only way to get itemized transactions, and it explicitly links to sibling tools like openfinance_list_credit_card_bills, setting it apart from others.

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

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

The description provides explicit guidance on when to use this tool versus alternatives. It states that for credit card itemized transactions this is the only tool, and for standardized open-bill total or total debt, users should use openfinance_list_credit_card_bills. It also advises checking item status if total is zero for a CREDIT account, directing to openfinance_get_item_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?

Adds significant detail beyond readOnlyHint: scan caps at 5000/account, truncation flag, default compact vs raw mode. 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?

Every sentence earns its place, well-structured with purpose, behavior, parameters, use cases, and edge cases. Informative yet 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 all aspects: return structure for both granularities, truncation behavior, parameter options, and use-case triggers. No output schema, but description provides necessary detail.

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?

Compensates for 0% schema coverage by explaining item, from/to, granularity effects, type filtering, and implication of top_n via 'largest N'. Top_n not explicitly described but context clarifies.

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?

Clear verb+resource (consolidated cash-flow analysis) with distinction from sibling 'openfinance_list_transactions' which likely provides raw listing. Explicitly states it resolves accounts internally, eliminating need for separate account listing.

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?

Explicit use cases ('análise anual/mensal', 'fluxo de caixa') and guidance on omitting item for all banks. Does not explicitly state when to use alternatives like openfinance_list_transactions, but implies when raw data is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds significant context: checks a public status page, returns global indicator, degraded components, open incidents, and flags incidents affecting the user's connected 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?

Two sentences with no fluff. First sentence states purpose and scope. Second sentence gives detailed usage guidance and return value summary. Every sentence adds value.

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

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

For a zero-parameter tool with no output schema, the description is remarkably complete. It explains return fields, usage context, and how to interpret results. It implicitly links to the user's connections via 'your_banks_affected'.

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

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

No parameters exist, so baseline is 4 per rules. Description does not need to add parameter info. Schema coverage is 100% by default.

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 uses specific verb 'Checks' and resource 'LIVE operational status of the Open Finance provider'. It clearly distinguishes from sibling tool 'openfinance_get_item_status' by stating it's the provider's health separate from 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?

Provides explicit when-to-use scenario: when data looks incomplete or stale even though connection shows UPDATED. Explains that it helps differentiate provider-side problems from connection issues. Does not include explicit when-not-to-use, but context sufficiently guides selection.

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. The description adds behavioral details like honoring user's plan (PF hides PJ banks) and that it never dumps the full catalog without keywords. 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?

Compact and well-structured: front-loaded with the primary action, each sentence adds value without redundancy. 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 no output schema, the description explains return fields (id, access, audience, connections, accounts, connect_url) and plan behavior. Fully sufficient for a 2-param 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 thoroughly explains both parameters: keywords (array of strings, with example) and include_accounts (boolean, describes effect). Adds essential meaning beyond 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 searches bank connectors by name and lists what is returned. It distinguishes from sibling tools like 'openfinance_list_connections' by focusing on search and providing a ready connect_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?

Explicitly instructs to call BEFORE connecting to get a one-click link, and states that keywords[] is required (without it returns a hint). Provides clear context for when 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?

Rich behavioral disclosure beyond annotations: explains side effects (overrides automatic categorization, creates Category Rule for future similar transactions), batch behavior (per-item errors don't fail whole batch), and response format. 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?

Dense single paragraph providing all necessary info. Every sentence adds value but could be more structured (e.g., bullet points for side effects). Slightly long 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?

Complete for a mutation tool with side effects: explains response format, side effects, and prerequisites. No output schema but description provides enough context for the agent to use the tool correctly.

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

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

Despite 0% schema description coverage, the description fully explains the items parameter structure (array of objects with transaction_id and category_id) and tells where to get those IDs from sibling tools. Compensates completely.

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

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

Clearly states it corrects the category of transactions, using verbs 'corrects' and 'update' and resource 'category of one or more transactions'. Differentiates from sibling list tools by being the update action.

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

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

Explicitly tells when to use: to fix miscategorized transactions and improve future categorization. References sibling tools for getting required IDs. Does not explicitly state 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?

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 indicate readOnlyHint, idempotentHint, and destructiveHint are true, so the safety profile is clear. The description adds the specific return content (installed MCPs, connection status, catalog tools count), which provides additional 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, front-loaded sentence that conveys all necessary information without any filler. 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?

For a simple info tool with no parameters and no output schema, the description comprehensively explains the return value. It fully suffices for the agent to understand what the tool does.

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

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

There are no parameters (0, 100% coverage), so the description does not need to add parameter details. Baseline is 4 for zero parameters, and the description does not provide any misleading 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 clearly states the tool returns 'current toolkit state: installed MCPs, their connection status, and how many catalog tools each exposes'. This is a specific verb and resource, and it distinguishes the tool from siblings, which are mostly openfinance actions or authentication 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 does not explicitly state when to use this tool vs alternatives, but it is the only tool that provides toolkit state information. The context is clear, though adding a sentence about when to use it (e.g., before other operations) would improve it.

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