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?

Annotations indicate readOnlyHint false, etc. The description adds significant behavioral context: invoke works even if MCP not installed, returns connect/checkout links, per-MCP billing via subscribe/cancel, and mentions that install/uninstall/subscribe/cancel require owner/admin. 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 lengthy but well-structured, front-loaded with purpose and flow. Every sentence adds value, but it could be more concise without losing information. Still efficient overall.

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 13 parameters, no output schema, and rich annotations, the description covers essential usage patterns, ecosystem role, and decision points thoroughly. It enables correct tool selection and 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 explains the action enum and its roles (search, describe, install, etc.). It doesn't detail each parameter like mcp_id or arguments, but provides enough context for the main actions. Barely misses a 5 due to lack of specific param details.

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

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

The description clearly states it's the official marketplace for MCPs/tools, used for discovering, describing, and invoking tools. It distinguishes itself from sibling tools like authenticate or report_bug by focusing on marketplace actions and core flow.

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 first before external registries, explains the core flow (search->describe->invoke), and distinguishes between invoke (one-off) and install (permanent). Also notes that writes require 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 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?

The description adds significant behavioral context beyond annotations: it explains error handling (credit accounts return warnings), response shape, and that it is a real-time GET request. It does not contradict any 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: two sentences, no wasted words. Purpose is front-loaded, followed by constraints and return format.

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?

Since there is no output schema, the description explains the response shape. However, it does not detail the fields inside the results array (e.g., account_id, balance). Still, it is fairly complete given the tool's simplicity.

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

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

Schema description coverage is 0%, but the description fully compensates by specifying that account_ids is an array (1-50 items) of string IDs. This adds meaning beyond the bare schema definition.

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

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

The description clearly states that the tool returns real-time balance per account id, using a specific endpoint (GET /accounts/:id/balance). This distinguishes it from sibling tools like openfinance_list_accounts (which lists accounts) and openfinance_get_accounts_detail (which likely returns account details, not 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 clear usage context: pass account_ids as an array (1-50) and mentions that CREDIT accounts may return a structured warning instead of throwing. It does not explicitly compare to alternatives or say when not to use, but the context is sufficient.

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

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

Annotations already declare readOnly and idempotent; description adds batch behavior and response shape without contradiction, enhancing understanding of side-effect-free operation.

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 brief sentences front-load purpose and endpoint, then parameter and response details; 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?

Low complexity with one param and no output schema; description covers endpoint, batch limit, and response shape; could elaborate on creditData content but adequate.

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

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

Schema has 0% description coverage; description fills gap by specifying array length constraint (1–50) and batch nature, though ID format is already in 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 explicitly states the tool returns full account objects with extended creditData per ID, and distinguishes from list tools by specifying the batch operation with 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 clear batch size limit (1–50) and parameter usage, but does not explicitly exclude when not to use or compare with sibling tools like openfinance_list_accounts.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds critical behavioral context: the batch shape { results, errors }, the absence of a paid/status field, and the specific meaning of payments[] in Brazilian Open Finance, preventing misuse.

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 but contains multiple informative sentences. Every sentence adds value, though it could be more structured (e.g., bullet points). It is front-loaded with 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?

Despite no output schema, the description details the output shape (financeCharges, payments with fields) and the batch format. It addresses potential confusions (paid status) and provides necessary context for a tool with moderate complexity.

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

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

Schema coverage is 0%, so the description fully compensates by specifying that bill_ids should be passed as an array and that they can be discovered via openfinance_list_credit_card_bills. This adds essential usage context 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 returns bill-level details for credit card bills by id, listing specific fields (financeCharges, payments) and explicitly stating what it does NOT return (individual transactions). It distinguishes itself from siblings like openfinance_list_transactions and openfinance_list_credit_card_bills.

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

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

The description provides explicit guidance on when to use this tool vs alternatives: use openfinance_list_transactions for itemized transactions, use openfinance_list_credit_card_bills first to discover ids, and prefer openfinance_list_credit_card_bills to check paid status. It also warns about misinterpretation of payments[] in Brazilian Open Finance.

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=true and idempotentHint=true, so the tool is safe. The description adds critical behavioral context: credit card 'balance' is connector-dependent and not a reliable bill amount, and the open billing cycle details are in creditData fields. 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 core purpose and then providing detailed usage and caveats. Every sentence adds value, though it could be slightly trimmed without losing essential guidance.

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

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

Despite no output schema, the description explains all key return fields (bank, connector_id, account data, balance nuances). It addresses connector-dependent behavior, cross-references sibling tools for billing details, and covers parameter usage extensively, leaving few ambiguities.

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 for parameter descriptions is 0%, but the description compensates by explaining how 'item' and 'type' parameters work in context: omitting 'item' aggregates across all banks, passing it targets a single bank; 'type' filters to BANK or CREDIT. This adds clear operational meaning beyond the schema.

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

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

The description clearly states it returns accounts for a bank connection, specifying types (BANK and CREDIT) and detailed fields (balance, number, type, subtype, bankData, creditData, bank, connector_id). It distinguishes the tool from siblings like openfinance_list_credit_card_bills by explaining what each tool covers.

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 guidance is given on when to omit 'item' to list all linked banks (e.g., 'my accounts/cards' without naming a bank) vs. passing 'item' for a single bank. It also advises against misinterpreting credit card balance as 'this month's bill' and directs to openfinance_list_credit_card_bills for standardized billing amounts.

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

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

Annotations already 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 already show readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds complex behavioral traits: payment derivation logic, derived payment_status, connector asymmetry, opt-in open bill scanning, and warning for disabled products. 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 long and dense, but each sentence contributes value. It is front-loaded with purpose but could be reorganized for easier digestion. Not overly concise, but appropriate given 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?

Given no output schema and complex behavior, the description is remarkably complete: explains return structure, payment logic, derived fields, opt-in feature, connector asymmetry, and cross-reference to other tools. Covers all critical aspects.

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 description must compensate. It explains include_open_bill in detail (opt-in, meaning, fallback). For page, page_size, account_id, account_ids, it mentions bulk support but does not explain defaults or limits. Some value added beyond schema, but not exhaustive.

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

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

The description clearly states it returns CLOSED credit card bills for a CREDIT-type account, listing specific fields and derived payment_status. It distinguishes from siblings like openfinance_get_credit_card_bill and openfinance_list_transactions, making 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?

Provides extensive guidance: when to use, when not to assume payment status, how to interpret payments, opt-in for open bill, connector asymmetry, and alternatives for itemized transactions. Explicitly states when-not and gives alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds 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, idempotentHint, and destructiveHint. The description adds significant behavioral context: auto-pagination, truncation at 5000, upstream error handling (returns error object instead of throwing), PENDING vs POSTED behavior for credit cards, and detail level effects. 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 very long (multiple paragraphs) and could be more concise. However, it is well-structured with clear sections (pagination, detail levels, error handling). It front-loads the main purpose but includes extensive detail that might overwhelm some agents.

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), the description is exceptionally complete. It covers pagination behavior, error handling, credit card specifics, links to other tools, and even explains what to do when total is 0. No gaps are apparent.

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

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

Schema description coverage is 0%, but the description fully explains all 8 parameters: from/to as ISO date filters, page and page_size for manual pagination, detail enum (compact/rich/raw), search_queries with case- and accent-insensitive OR semantics, required account_id, and account_ids for batch. This adds meaning far 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 returns transactions for bank accounts of type BANK or CREDIT. It specifically distinguishes that for CREDIT accounts, it is the ONLY way to get itemized transactions. It differentiates from sibling tools like openfinance_list_credit_card_bills and openfinance_list_transactions_by_item.

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

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

The description provides explicit when-to-use guidance: for credit card itemized transactions; for bill totals, use openfinance_list_credit_card_bills. It explains pagination behavior in detail (omit page for auto-pagination, 5000 ceiling, truncation warning), when to use detail levels, and when to check connection health if total is 0.

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 key behaviors: resolves accounts internally, caps at 5000/account with truncation flag, different detail levels and their effects. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

The description is thorough but slightly lengthy; it front-loads the core purpose and organizes details logically. Every sentence adds value, though could be trimmed slightly without loss.

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 7 parameters, no schema coverage, and no output schema, the description is unusually complete: covers all parameters, return structures (compact vs raw), truncation, and use cases. No gaps for an AI 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?

Despite 0% schema coverage, the description explains all parameters: 'item' (connector_id/name), 'from'/'to' (ISO dates), 'granularity' (monthly/raw), 'detail' (compact/rich/raw), 'type' (BANK/CREDIT), and implies 'top_n'. Provides defaults and behavior.

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

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

The description clearly states the tool's purpose: consolidated cash-flow analysis for a bank connection in one call, resolving accounts internally. It distinguishes itself from siblings by eliminating the need to call openfinance_list_accounts first.

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

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

Explicitly provides usage context: use for 'análise anual/mensal', 'fluxo de caixa', etc. Advises when to omit 'item' for all banks, and when to use 'granularity:raw' vs 'monthly'. Also mentions not calling openfinance_list_accounts first.

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.