BV MCP

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

Annotations indicate idempotentHint=true, and description adds context: authentication process, token vs no-arg behavior. No contradiction. Disclosure goes beyond annotations.

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

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

Three sentences, front-loaded with purpose, then methods. No wasted words. Efficient and clear.

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

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

Covers main use cases and authentication flow. No output schema, but return value is implied (link or success). Could mention exact output format, but not critical for this tool.

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

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

Schema has 1 optional token parameter with 0% coverage; description fully explains its use: call with token for session or no args for link. Compensates for lack of schema descriptions.

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

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

Description clearly states the tool is for authentication, explaining both permanent and session-based login methods. It distinguishes from sibling tools which are about Open Finance, reporting bugs, 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?

Explicitly describes when to use: for logging in via browser (permanent) or pasting token (session). Mentions alternative of config-based permanent token, but doesn't explicitly say when not to use.

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

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

The description adds value beyond annotations by detailing the response structure (authenticated, pending, connect_url) and how it varies based on provider connection state. No contradictions with annotations (readOnlyHint, destructiveHint). It adequately communicates behavior without being overly verbose.

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 the core action, and no wasted words. Every sentence contributes to understanding the tool's purpose and behavior.

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

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

Given zero parameters, no output schema, and full annotations (readOnlyHint, idempotentHint), the description sufficiently covers what the tool returns and under what conditions. It is complete for a simple status check tool.

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

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

The tool has no parameters, so the description need not add param-level info. Baseline 4 is appropriate as there is nothing missing.

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 connection status and URLs, with specific examples of responses when all providers are connected or credentials are missing. It effectively distinguishes itself from sibling tools like authenticate and provider_status by focusing on connection status rather than authentication actions.

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 check connection status) but does not explicitly state when not to use it or mention alternatives among siblings. It implies usage by describing different response scenarios, but lacks clear guidance on tool 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?

The description discloses key behavioral traits beyond annotations: invoke runs MCPs without installing, install makes permanent, writes require owner/admin, and provides details on handling credential and payment issues. It aligns with annotations (readOnlyHint=false, openWorldHint=true) and adds significant context.

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

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

The description is a single dense paragraph with no structural breaks. While it is informative, it could be more concise and better organized (e.g., bullet points or sections) to improve readability. The content is valuable but not efficiently presented.

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

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

Given the high complexity (13 parameters, no output schema), the description is remarkably complete. It covers all major actions, the core flow, auth/payment handling, install vs invoke distinction, and flags like installed_in_toolkit vs workspace. It sufficiently contextualizes the tool's usage.

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 compensate but does not systematically detail each of the 13 parameters. However, it explains the meaning of some parameters implicitly through action descriptions (e.g., query, action, mcp_id, tool_id, arguments). This provides partial context but lacks full parameter semantics.

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 that this is the official marketplace for MCPs and tools, and outlines the core purpose: discover, describe, install, invoke, etc. It distinguishes itself from sibling tools by positioning itself as the primary entry point for marketplace actions, using clear action verbs like 'search', 'describe', 'invoke', and 'install'.

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 (e.g., 'use THIS tool FIRST'), and explains when to use specific actions (e.g., prefer invoke for one-off use, install for permanent). It also covers handling of auth and payment failures, and mentions that writes require 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 only provide destructiveHint=true. The description adds that data will no longer be available and returns an add_connection_url for reconnection. This provides clear 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, front-loaded with the main action, no unnecessary words. 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?

The description covers the core functionality and return value, but lacks explanation of the input parameter 'item', which is a critical gap. With no output schema, it could be more complete.

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

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

The only parameter 'item' (string) has no description in the schema (0% coverage). The description does not explain what 'item' represents, leaving ambiguity about whether it's a bank ID, connection ID, or something else.

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 Open Finance consent, deletes connection data, and makes bank data unavailable. It distinguishes from siblings like openfinance_list_connections by specifying the disconnection 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?

The description implies usage when disconnecting a bank, with no explicit when-not or alternative tools. However, the purpose is straightforward and an AI agent can infer appropriate usage.

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

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

Discloses polling up to 60s, fire-and-forget option with wait false, return fields like timed_out, needs_action, and synced. Annotations minimal, so description provides full behavioral context.

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

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

Well-structured with action upfront, but slightly long. Every sentence adds value, but could be trimmed by a phrase 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?

No output schema, but description covers return structure, error handling, and next steps. Accounts for timeouts, user action needs, and polling behavior. Complete for agent use.

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

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

With 0% schema coverage, description explains items as array of selectors with three types, and wait as boolean with fire-and-forget behavior. Compensates fully.

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 forces a bank re-sync and waits, with specific verb 'force sync' and resource 'connections'. Distinguishes from siblings like openfinance_get_item_status for status checking.

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

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

Explicitly says when to use (stale balance/transactions), what it does without (no disconnect/reconnect), and alternative (openfinance_get_item_status if timed_out). Full guidance.

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

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

Discloses that CREDIT accounts may return a structured warning (BALANCE_FETCH_ERROR) instead of throwing, and provides the response shape. This goes beyond the annotations, which only indicate read-only and idempotent.

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, then usage, then error handling. 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?

For a tool with one parameter and no output schema, the description provides response shape and special error handling. It is complete given the low 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?

Despite 0% schema description coverage, the description adds the constraint that account_ids must be an array of 1-50 items. This is meaningful and not present in the schema.

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

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

Description clearly states 'Returns real-time balance payload per account id' with explicit endpoint. This distinguishes it from sibling tools like openfinance_list_accounts and openfinance_get_accounts_detail.

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 context: pass account_ids as array (1-50), and explains behavior for CREDIT accounts. Does not explicitly mention when not to use or alternatives, but 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?

Description adds significant behavioral context beyond annotations: confirms read-only nature via GET, describes the batch processing with results/errors shape, and mentions extended creditData. This enriches the safety hints from annotations (readOnlyHint, idempotentHint).

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

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

Two sentences efficiently convey purpose, usage, and response shape. Every sentence adds value with no redundancy or fluff.

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

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

Despite no output schema, description covers key aspects: batch response shape and inclusion of extended creditData. It is adequate given low complexity (one parameter). Could be more exhaustive but sufficient for typical usage.

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

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

With 0% schema description coverage, the description compensates by specifying the array constraint (1-50 items) and the purpose (per id). It explains what account_ids represents, but lacks example formats or additional details about ID format.

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

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

Description clearly states it returns full account objects with extended creditData per ID, specifying the HTTP endpoint and distinguishing from siblings like list_accounts. The verb 'Returns' and resource 'accounts detail' are 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?

Description provides clear usage context: pass account_ids as an array (1-50). It implies this is for detailed info but does not explicitly state when to use versus alternatives like list_accounts or get_account_balance. The batch limit and response shape are helpful guidelines.

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=false. The description adds significant behavioral context: the batch shape {results, errors}, that Pluggy does not return a paid/status field, and the nuance that payments[] may reflect the previous bill's payment. 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 relatively long but well-structured: it starts with the core purpose, then explains what it does not do, provides usage guidance, and adds special notes. Every sentence earns its place, though minor condensation is possible. The structure is front-loaded and logical.

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, the description explains the return shape ({results, errors}) and key fields (financeCharges, payments[] with subfields). It also describes the link to transactions via creditCardMetadata.billId. However, it omits detailed structure of financeCharges and other potential fields, which could be important. Overall, it is fairly complete for the tool's complexity.

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

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

The input schema has only one parameter (bill_ids as array of strings) with 0% schema description coverage. The description fully compensates by explaining that bill_ids should be an array, that discovery of IDs should be done via openfinance_list_credit_card_bills, and the relationship to transactions. This adds 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 returns bill-level detail for one or more credit card bills by ID, specifically mentioning fields like financeCharges and payments[]. It explicitly distinguishes from getting individual transactions, which is handled by openfinance_list_transactions. This provides a specific verb+resource scope that differentiates it from siblings.

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

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

The description gives explicit guidance on when to use this tool (for bill-level detail) and when not to use it (for itemized transactions). It instructs users to obtain bill IDs from openfinance_list_credit_card_bills first, and for transactions to use openfinance_list_transactions with appropriate date ranges. It also warns about the payment semantics in Brazilian Open Finance, preventing misinterpretation.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds valuable behavioral context: returns status, executionStatus, and connector metadata, and describes the two usage modes. It does not mention any side effects or requirements, but that's acceptable given 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 only two sentences with no redundancy. The first sentence states the purpose and outputs, the second explains the parameter usage. 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 tool's simplicity (one optional parameter, no output schema), the description covers the key aspects: purpose, two operational modes, and return types. It could be more explicit about the single bank response format (e.g., 'returns a status object'), but the existing text is sufficient for an agent to use correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that omitting item returns all banks (with count and items), while passing item returns a single bank. This adds significant meaning beyond the JSON schema, but could be slightly more precise about the single-bank response structure.

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 specific status values (UPDATED, UPDATING, LOGIN_ERROR) and metadata. It distinguishes between obtaining all connections vs a single one via the optional item parameter, providing a clear verb and resource.

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

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

The description explicitly tells when to omit item (get all) vs pass item (single bank), and specifies the return format for the all-case. However, it does not compare to sibling tools like openfinance_provider_status or openfinance_list_connections, leaving some ambiguity about optimal tool 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?

Discloses critical behavioral traits: CREDIT balance meaning is connector-dependent, `name` is not the brand, and creditData fields define billing cycle. This adds significant context beyond the readOnlyHint/idempotentHint annotations.

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

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

Front-loads the core purpose, then provides usage guidelines and caveats. Each sentence earns its place, though the description is relatively long. Minor redundancy in explaining the same concept twice (e.g., bank vs name).

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 only 2 parameters, 0% schema coverage, no output schema, and 21 sibling tools, the description covers parameter usage, output fields, field semantics, and cross-references to the credit card bills tool. It is fully adequate for 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?

With 0% schema description coverage, the description compensates by detailing the `item` parameter's effect (aggregate vs single bank) and implying the `type` filter by listing account types. However, the `type` parameter could be more explicitly tied to the enum values.

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

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

The description clearly states the verb 'Returns accounts' and specifies the resource 'bank connection' with account types (BANK/CREDIT) and fields. It distinguishes from sibling tool openfinance_list_credit_card_bills by noting its different purpose for standardized bill amounts.

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

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

Explicitly explains when to omit `item` (all banks) vs pass `item` (single bank), and when to use openfinance_list_credit_card_bills instead for credit card bills. Provides clear context for parameter choices.

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 that the response is cached for the adapter session and is a single aggregated response with no batch ids, which are useful behavioral details 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 very concise, consisting of three short sentences. It front-loads the main purpose, then explains the structure and usage notes. There is no redundant or irrelevant 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?

For a zero-parameter, read-only, idempotent tool with annotations covering safety, the description fully explains what the tool returns and how to use the output. It even provides language preference guidance for Portuguese users. No output schema exists, but the field descriptions are 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?

The input schema has zero parameters, so there is no parameter information to add. Schema coverage is 100%, and the description correctly does not need to explain parameters. Baseline for zero params is 4.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy. It specifies the source (GET /categories), caching behavior, and key fields like `id`, `description`, and `parentId`. It distinguishes itself by noting that the `id` is used for openfinance_update_transaction_category, linking it to a sibling tool.

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

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

The description explains the tool is for retrieving category taxonomy for use in updating transaction categories. It provides context on the cached nature and the field usage for Portuguese users. While it doesn't explicitly state when not to use it, the purpose is clear and distinct from sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Description adds that the tool returns an add_connection_url for linking additional banks, but does not disclose any other behavioral aspects beyond what annotations provide. The description does not contradict 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, well-structured sentence that conveys the essential purpose and return value without any extraneous words. Every part 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 straightforward list tool with no parameters and no output schema, the description is mostly complete. It specifies the returned fields and the additional URL. However, it could mention that it returns all connections for the install and lacks pagination details, but these are minor given the 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?

No input parameters exist, and schema coverage is 100% automatically. The description does not need to explain parameters, but it adds no parameter-specific details. Baseline for 0 parameters is 4, which is appropriate.

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

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

The description clearly states 'Returns the saved bank connections' with specific fields (connector_id, item_id, bank name, add_connection_url). This distinctly differentiates it from sibling tools like openfinance_list_accounts which list accounts per 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?

No guidance on when to use this tool versus alternatives. For example, it doesn't mention that this should be called first to get available connections before using other tools like openfinance_list_accounts or openfinance_get_account_balance.

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, but description adds significant behavioral context: explains the payment cycle logic, derivation of payment_status, open_bill derivation, connector asymmetry, and warns about varying balance meanings. No contradiction with annotations; description reinforces read-only nature.

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

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

Description is very long (multiple paragraphs) and includes extensive detail on payment logic and semantics. While front-loaded with key return fields, the detail could be streamlined. Some information might be better in external docs. It is structured but not 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 thoroughly describes return structure (dueDate, totalAmount, payments[], payment_status, open_bill, etc.), explains derived fields, and warns about connector asymmetry and product not enabled. Covers all relevant aspects for correct invocation and interpretation.

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 bears full burden. It explains account_id (required), account_ids (bulk), include_open_bill (opt-in, default false, with details on behavior). However, page and page_size parameters are not explained in the description, leaving a minor gap. Overall adds significant 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 explicitly states it returns CLOSED credit card bills for CREDIT-type accounts, listing key fields and derived payment_status. It clearly distinguishes from sibling tools like openfinance_get_credit_card_bill and openfinance_list_transactions by specifying what this tool does not do (individual transactions).

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

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

Provides explicit guidance: when to use include_open_bill (opt-in), warns about connector asymmetry and not to assume payment status from payments[]. Advises using derived payment_status and directs to openfinance_list_transactions for itemized purchases. Clearly tells when not to use this tool and 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=true and idempotentHint=true. The description adds value by disclosing error behavior (returns a default structure instead of throwing), and detailing the rate fields and other data included (balance, amount, dueDate, etc.). This provides useful 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 front-loaded with the main purpose and includes all necessary details in a single paragraph. While it lists many asset types and rate fields, this information is valuable for an agent. It could be slightly more concise by grouping similar items, but it remains effective.

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

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

The description covers the return shape and error handling, which is helpful given the lack of an output schema. However, it omits parameter semantics, which are important for correct invocation. Overall, it is adequate but leaves gaps that could confuse an agent.

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

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

Schema description coverage is 0% for the 4 parameters (item, page, type, page_size). The description does not explain what these parameters mean, how to use them, or their expected values. For example, it does not indicate that 'item' likely refers to a connection ID or how pagination works with page/page_size.

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

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

The description explicitly states it returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.), and details the fields included. This clearly distinguishes it from sibling tools like openfinance_list_investment_transactions, which focus on transactions rather than holdings.

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 connections with INVESTMENTS product enabled by mentioning the graceful handling of 403 errors. However, it does not explicitly compare to sibling tools or provide guidance on when to use this tool versus others like 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful behavioral details: batch execution support and itemized expense breakdown. 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 focused paragraphs, front-loaded with purpose. Could be slightly more concise but 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 no output schema, description details return fields (quantity, value, expenses breakdown) and usage order. Missing pagination explanation and clarification on parameter interaction (investment_id vs investment_ids). Still fairly complete.

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

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

Schema coverage is 0%, so description must compensate. Describes investment_id (required) and investment_ids (bulk), but fails to explain page and page_size parameters. Partially adds meaning but incomplete.

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

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

Clearly states it returns movement history for a specific investment position, listing transaction types (BUY/SELL/TAX/etc.) and specific fields. Distinguishes from sibling tools like openfinance_list_investments (which lists positions) and generic openfinance_list_transactions.

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

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

Explicitly instructs to use after openfinance_list_investments to get the investment_id. Mentions bulk support for investment_ids. Lacks explicit when-not-to-use or alternatives, but the sequential guidance 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details: the API endpoint, sequential processing with rate-limit spacing when multiple connections are specified, and the return format ('{ results, errors }' per connection). 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 concise with three sentences, no redundant information. It front-loads the purpose, explains the parameter usage, and adds behavior details. Every sentence earns its place.

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

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

For a tool with one optional parameter, no output schema, and low complexity, the description covers purpose, parameter semantics, behavioral details, and return format. It is fully complete for an AI 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 only defines 'items' as an array of strings with no further description. The description compensates fully by explaining that items are 'connection selectors (item_id uuid, connector_id, or connector_name)' and how they are used. This is critical given 0% schema description coverage.

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

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

The description clearly states it lists loan contracts per bank connection, specifying the API endpoint (GET /loans). It distinguishes two modes: with an 'items' array for specific connections or omit for all linked banks. This purpose is distinct from sibling tools like 'openfinance_list_accounts' or 'openfinance_list_transactions'.

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

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

The description provides clear guidance on when to use the 'items' parameter (to fetch specific connections sequentially with rate-limit spacing) and when to omit it (to list across all linked banks). It lacks explicit when-not-to-use instructions or comparison with alternative tools, but the context is sufficient for correct usage.

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

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

Annotations already indicate readOnly and non-destructive, but description adds crucial behavioral details: CREDIT PENDING vs POSTED varies by connector, search_queries aggregates up to 5000 transactions, error handling returns specific format instead of throwing, and bulk support. These significantly enhance understanding beyond annotations.

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

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

Description is dense but well-structured, front-loading main purpose. Every sentence adds value—no fluff. It covers purpose, usage, behavioral details, and parameter semantics efficiently.

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?

Highly complete given no output schema: covers error handling, pagination, search behavior, credit card specifics, and troubleshooting. Minor gap: does not detail the structure of individual transaction objects in the results array, but overall sufficient 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 has 0% description coverage, but description explains all parameters: from/to are ISO YYYY-MM-DD, page_size max 500, search_queries performs case-insensitive substring match with OR semantics, account_ids for bulk. This fully compensates for missing schema descriptions.

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

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

Description clearly states 'Returns transactions for a bank account (BANK or CREDIT type),' specifying the verb and resource. It distinguishes from sibling tools like openfinance_list_credit_card_bills by explaining that for CREDIT accounts this is the only way to get itemized transactions, and describes the relationship with 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?

Explicitly provides when to use (for credit card itemized transactions) and when not to use (use openfinance_list_credit_card_bills for standardized open-bill total). Offers guidance on handling truncated results and zero totals, including checking connection health and force syncing.

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

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

Beyond annotations (readOnly, idempotent), description adds internal account resolution, fan-out behavior, default compact summary vs raw, truncation at 5000/account with flag, and response structure details. 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?

Well-structured with front-loaded purpose, but a single dense paragraph. Could be more concise with bullet points. Still clear and each sentence adds value.

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

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

Given no output schema and 6 parameters, description covers input, behavior, limitations (capping, truncation), response structure, and use cases. No missing information for effective tool 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?

All 6 parameters are explained despite 0% schema coverage: item (connector_id/connector_name/item_id or omit for all), from/to (ISO dates), granularity (monthly default, raw for itemized), type (BANK/CREDIT), top_n (largest N in top lists). Each parameter's effect on behavior is described.

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

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

Description clearly states it provides consolidated cash-flow analysis for a bank connection, resolving accounts internally and avoiding multi-call workflows. It distinguishes from sibling tools like openfinance_list_accounts by explicitly saying you don't need to call that first, and implies aggregation vs raw 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?

Describes when to use (for annual/monthly analysis, cash flow, top expenses) and when to use raw granularity (when itemized rows needed). Mentions scanning cap and truncation. Could have explicitly compared to openfinance_list_transactions for raw listing, but overall clear guidelines.

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 that it checks a public status page and returns global indicator, degraded components, open incidents, and flags affecting connected banks. No contradictions; adds useful behavioral context.

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

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

Description is front-loaded with main purpose. Contains necessary details but is slightly verbose with multiple clauses. Still efficient and well-structured.

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 the description explains return contents: global indicator, degraded components, open incidents, your_banks_affected. Sufficient for a simple status check tool.

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

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

No parameters exist. Schema coverage is 100%. Description doesn't need to add parameter info since there are none. 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 checks the LIVE operational status of the Open Finance provider, distinguishing from sibling tool openfinance_get_item_status which checks own connection health. It specifies the resource (provider status page) and action (checks health).

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

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

Explicitly describes when to use: when data looks incomplete or stale despite connection showing UPDATED, missing accounts/transactions. Contrasts with openfinance_get_item_status and explains this tool reveals upstream outages. Provides clear decision guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds important behavior: returns a connect_url, honors user's plan (PF hides PJ), and when missing keywords returns a hint instead of full catalog. No contradictions.

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

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

The description is a single dense paragraph that front-loads the main action. It is efficient but could be slightly more structured (e.g., separate lines for parameters). No wasted words.

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

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

For a search tool with no output schema, the description adequately covers return fields (connector id, access, audience, linked connections, accounts, connect_url) and plan filtering. Missing explicit output structure but sufficient for agents.

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 both parameters: keywords as array of strings with examples, include_accounts as boolean. However, it claims keywords is required while the schema does not mark it required, creating a mild inconsistency.

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, returns specific fields (connector id, access, audience, etc.) and a connect_url. It distinguishes from siblings by positioning itself as a prerequisite for connecting.

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

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

Explicitly says 'Call this BEFORE connecting to hand the user a one-click link' and notes that keywords are required. It lacks a clear alternative for dumping the full catalog but implies this tool should not be used for that.

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

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

The description goes beyond annotations by revealing that the action teaches Pluggy, creates a Category Rule for future similar transactions, and describes batch error handling (per-item errors do not fail the whole batch). This adds significant behavioral context not available in 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 covering purpose, input format, side effects, and output. It is front-loaded with purpose but could benefit from breaking into bullet points for clarity. However, 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?

Even without an output schema, the description fully explains the batch update process, the response structure, and error handling. It provides enough information for the agent to understand the tool's operation and outcomes.

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

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

With 0% schema description coverage, the description fully compensates by explaining the items array structure, the meaning of transaction_id and category_id, where to source them, and the required format. This provides complete parameter semantics.

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

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

The description clearly states the action (corrects category), the resource (transactions), and the HTTP method (PATCH). It distinguishes itself from sibling tools by specifying where to get the required IDs (openfinance_list_transactions and openfinance_list_categories).

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

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

The description explains the purpose: to fix miscategorized transactions and improve future categorization. It tells the agent where to obtain the IDs. However, it does not explicitly state when not to use the tool or provide clear alternatives for different use cases.

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

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

Annotations already indicate idempotent and non-destructive, and the description does not add further behavioral details beyond the purpose.

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, front-loaded sentences 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?

Adequate for a simple tool but lacks parameter details and response information; could be more complete given no output schema.

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

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

The description mentions 'conversation array' but does not explain the 'message' or 'context' parameters, even though schema coverage is 0%.

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

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

Clearly states the tool reports bugs, missing features, or feedback, distinguishing it from sibling tools which are finance-related.

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

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

Provides guidance to include the conversation array for reproduction, but does not specify when not to use or mention alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, providing safety context. The description adds that it shows platform and adapter versions, but no additional behavioral traits 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, clear sentence with no extraneous words, effectively communicating the tool's function.

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?

While the description states what the tool does, it does not describe the return format or structure of the version information, which is relevant given the absence of an 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?

With zero parameters and 100% schema coverage, the description is not required to add parameter details. The baseline for zero parameters is 4, and the description does not detract from this.

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

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

The description specifies the verb 'Show' and the resource 'MCP platform and adapter versions', clearly distinguishing it from sibling tools which focus on authentication, financial data, or system settings.

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 that the tool is for retrieving version information, but does not explicitly state when to use it or when to prefer alternatives. For a simple read-only query, the context is sufficient but not explicitly guided.

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, so the safety profile is clear. The description adds specific behavioral details about what state is returned (installed MCPs, connection status, counts), which complements 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 sentence with no wasted words, front-loading the core return value. Every part earns its place.

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

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

Given no output schema, the description adequately specifies the return value: installed MCPs, connection status, and catalog tool counts. This is complete for a diagnostic 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 with 100% coverage, so the description does not need to add parameter details. The description fully explains the tool's output.

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

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

The description clearly states the tool returns the current toolkit state including installed MCPs, connection status, and catalog tool counts. This specific verb+resource combination distinguishes it from sibling tools like authenticate or show_version.

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

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

The description implicitly indicates this is for checking toolkit state, and the sibling context shows it's separate from authentication, connection, and data operations. However, no explicit when-not or alternative guidance is provided.

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