ASA MCP

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

Annotations provide idempotentHint=true, and the description adds behavioral context: permanent vs. session login, and the two modes of operation (with or without token). No contradictions. It could mention side effects or response, but overall adds value 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 paragraph but is dense and front-loaded with the main purpose. Every sentence adds value, though slightly more structured formatting (e.g., bullet points) could improve readability. Still, it is concise and to the point.

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 low complexity (one optional parameter, no output schema). The description covers the main usage scenarios (with and without token, permanent vs. session). It does not describe the return value, but for an authenticate tool the response is somewhat implied. Overall, it is functionally 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 has 0% coverage with no description for the 'token' parameter. The description fully explains that the token is an optional JWT for session login, and that omitting it returns a link. This adds essential meaning beyond 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 is for authentication of IDE agents via browser login and token capture. It specifies the verb 'log in' and the resource 'access token', and distinguishes from siblings like 'connect' by focusing on token-based 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 explicitly explains when to use the tool (to get a login link or pass a token) and gives a best practice (adding to config for permanent connection). It lacks explicit when-not-to-use guidance but the context is clear enough.

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

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

Annotations already mark it as read-only and idempotent. The description adds value by explaining the response structure (authenticated, pending, connect_url) and the conditional behavior based on provider status.

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 with zero waste. Front-loaded with purpose, then provides specific state details.

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 covers the main behavior and two key states adequately. Could mention additional response fields but not necessary for a status check.

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

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

No parameters exist, so baseline is 4. The description does not need to add parameter info, but it implicitly clarifies that no input is required.

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, and describes two distinct states. However, it does not explicitly differentiate 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?

Usage context is implied through the description of two scenarios (all connected vs missing credentials), but there is no explicit guidance on when to use this tool versus alternatives.

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

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

Describes key behaviors such as invoke running tools even when not installed, returning connect/checkout links for credential/payment issues, and that search/describe flags installation status. Adds significant context beyond annotations, which are minimal.

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-loading the purpose and core flow. Every sentence adds value, though some details could be more compact. Still, it remains highly informative without unnecessary repetition.

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

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

Covers the tool's role, actions, permissions, billing interactions, and installation states comprehensively. Given the complexity (15 params, no output schema), the description provides enough context for an AI agent to select and invoke the tool correctly.

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

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

The description explains the role of the 'action' parameter and the overall flow but does not provide detailed semantics for the 15 parameters (e.g., format of 'arguments', 'conversation'). With 0% schema description coverage, the description only partially compensates by giving high-level context.

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 this is the official mcp.ai marketplace for discovering and running MCPs and tools. It sets up a core flow with specific actions (search, describe, invoke, install) and distinguishes itself from sibling tools by being the primary tool for capability discovery.

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 this tool first before any external registry, explains when to use invoke vs install, and notes that write actions require workspace owner/admin. Provides clear context for when to use this tool versus alternatives.

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

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

Annotations already indicate destructiveHint=true, and the description aligns by noting deletion of data. It adds context that data becomes unavailable and returns a reconnection URL, beyond the annotations. No contradiction.

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

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

Two sentences, front-loaded with key action and consequences. Every sentence adds value with no waste.

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

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

While the description covers the main action and outcome for a simple destructive tool, it omits clarification of the single parameter, making it less complete for an agent that has no prior knowledge.

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

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

With 0% schema coverage, the description must explain the 'item' parameter but does not. It fails to add any meaning beyond the schema's raw type definition, leaving agents to guess what 'item' represents.

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 bank data unavailable. It distinguishes from sibling tools like openfinance_list_connections (listing) or openfinance_force_sync (syncing) by its destructive 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 for disconnecting a bank but does not explicitly specify when to use this tool versus alternatives, nor provides prerequisites or exclusions. The reconnection URL hint is helpful but incomplete 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 waiting behavior (polls up to ~60s), fire-and-forget option, and return fields including status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out. No annotation 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?

Front-loaded with key action and behavior, then details. Slightly verbose but every sentence adds value. Could be tightened 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 no output schema, description thoroughly explains return shape and key fields. Covers error conditions (needs_action, timed_out) and provides sufficient context given sibling tools.

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

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

Adds full meaning beyond schema: explains items as array of selectors (item_id, connector_id, or connector_name) and omission to sync all. Describes wait parameter as fire-and-forget. Schema has 0% coverage, so description compensates completely.

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

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

The description clearly states the verb 'Forces the bank to re-sync' and the resource 'connections', with scope specification (one or more or all). It distinguishes from sibling tools like 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?

Provides explicit when-to-use guidance: 'when a balance or transaction list looks stale' and alternatives: 're-check with openfinance_get_item_status' for timed-out syncs. Also explains when to omit items and use wait: false.

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 indicating read-only and idempotent, the description details degradation behavior, warning structures, and error handling. This provides rich transparency.

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

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

Description is concise, front-loaded with purpose, then constraints, then edge cases. Every sentence adds value without redundancy.

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

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

Given one parameter and no output schema, the description covers parameter constraints, response shape, and all major error/degradation scenarios. No missing important context.

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

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

Schema coverage is 0%, but the description adds the array constraint (1–50) and names the parameter. It could specify format, but adds meaningful 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 tool returns real-time balance payload per account id and specifies the HTTP endpoint. It distinguishes itself from siblings by focusing specifically on balance retrieval, not account details or lists.

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

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

The description provides clear context on when to use the tool (real-time balance per account ids) and includes constraints (1-50 account_ids). It does not explicitly exclude alternatives, but the purpose is well-defined.

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 and idempotentHint. The description adds critical behavioral context about the provider_incident block and unreliable credit/balance data, which goes beyond annotations without contradicting them.

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?

Reasonably concise, with the main purpose front-loaded in the first sentence. Important caveats about provider incidents are included without extraneous filler.

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

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

With no output schema, the description explains the batch response shape and incident-related anomalies. It misses some detail about error handling or authentication, but covers the key risks for an agent invoking 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 coverage is 0%, so description must compensate. It clarifies that account_ids is an array (1-50) of account IDs, adding meaningful constraints beyond the raw schema's type definition.

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

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

The description clearly states it returns full account objects with extended creditData per ID, specifying the REST endpoint and the batch shape. It implies more detail than the sibling list tool, but does not explicitly contrast them.

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 specific usage instructions: pass account_ids as an array of 1-50 IDs. However, no guidance on when to use this tool vs openfinance_list_accounts or other siblings, and no exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical behavioral context: the batch shape ('{ results, errors }'), that Pluggy does not return a paid/status field, and that 'payments[]' typically reflects payment of the previous bill, not the current one. No contradiction with annotations.

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

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

The description is dense with useful information but slightly long (~120 words). It is front-loaded with the core purpose and then provides caveats. Every sentence adds value, though some minor trimming could improve conciseness.

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

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

Given the complexity (batch operation, multiple behavioral caveats, cross-tool dependencies), the description fully covers what the tool does, what it doesn't do, how to use it correctly, and common pitfalls. No output schema exists, but the description mentions the batch shape and key fields, making it 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 fully explain the single parameter 'bill_ids'. It does so by stating it should be passed as an array and that IDs can be discovered via 'openfinance_list_credit_card_bills', providing necessary semantic context beyond 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 it returns bill-level detail for credit card bills by ID, specifying the fields included (financeCharges, payments) and explicitly distinguishing itself from the transaction-listing sibling tool. The verb 'get' plus resource 'credit card bill detail' is specific and unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: it directs the agent to use 'openfinance_list_transactions' for itemized transactions and warns against reconstructing bill totals via transactions. It also recommends first using 'openfinance_list_credit_card_bills' to discover IDs and checking paid status via that tool instead.

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, destructiveHint=false, and idempotentHint=true. The description adds meaningful context: return fields (status, executionStatus, connector metadata) and return structure for all banks (count, items). No contradiction with annotations.

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

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

The description is two sentences, concise and front-loaded with the core purpose. Every sentence adds value with no redundancy. It efficiently conveys both functionality and usage.

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

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

Given the tool has one optional parameter and no output schema, the description is complete. It explains the two modes of operation and the expected return structures (count, items for all banks). No additional context is needed for correct invocation.

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

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

Schema coverage is 0% (no description for the 'item' parameter). The description compensates by explaining the semantic difference: omitting item returns all banks, passing item returns a single bank. This is critical information 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?

The description clearly states the tool returns the current status of a bank connection, listing specific status values like UPDATED, UPDATING, LOGIN_ERROR. It distinguishes two distinct use cases: omitting item returns status for all linked banks, passing item returns for a single bank. This specificity and differentiation from sibling tools make purpose very clear.

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

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

The description provides explicit guidance on when to omit vs. include the 'item' parameter, covering both collective and individual bank status retrieval. It does not mention when not to use the tool or compare with siblings, 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 declare readOnlyHint, idempotentHint, and destructiveHint. Description adds context about batch shape, array size limit, and endpoint method (GET). No additional disclosure on auth or error cases, but sufficient for a read-only tool.

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

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

Two sentences, no redundancy. First sentence lists return fields, second gives usage guidance. Front-loaded with 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?

For a read-only detail tool with one parameter and no output schema, the description fully explains the return fields, parameter constraints, and usage context. References sibling tool for proper workflow.

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 provides no description for the single parameter 'loan_ids'. Description adds meaning by specifying array size limit (1-50) and the batch result shape. This compensates for the 0% schema coverage.

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

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

Clearly states it returns full loan contract detail by id, listing specific fields like interestRates, warranties, installments schedule, etc. Distinguishes from sibling openfinance_list_loans by stating it is used after that tool for deep-diving.

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

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

Explicitly says 'Use after openfinance_list_loans to deep-dive on a specific contract.' Also provides parameter guidance (array of 1-50 loan IDs) and result shape (batch with results/errors).

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 discloses that the meaning of CREDIT balance is connector-dependent, that a provider_incident block may indicate unreliable data, and clarifies the distinction between 'name' and 'bank'.

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

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

The description is lengthy but well-structured, front-loading the core purpose. Some details could be more concise, but the information is valuable and earned its place given the tool's 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?

With no output schema, the description fully covers return fields, response structure for aggregated vs single-bank queries, and edge cases like provider incidents. It provides complete guidance for an agent to use the tool correctly.

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

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

Parameter schema coverage is 0%, so the description must compensate. It thoroughly explains the 'item' parameter's effect on response aggregation. The 'type' parameter's purpose is implied but not explicitly linked to filtering. Still, the description adds substantial value.

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

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

The description clearly states it returns accounts for a bank connection with specific fields, distinguishing between BANK and CREDIT types. It differentiates from sibling tools like openfinance_list_credit_card_bills.

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

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

Provides explicit guidance on when to use the 'item' parameter (omit for all banks, pass for a specific bank), when to use an alternative tool (openfinance_list_credit_card_bills for standardized billing), and warns about the unreliable nature of CREDIT 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, idempotentHint=true, destructiveHint=false. The description adds value by explaining caching behavior, that it returns a single aggregated response, and details the response structure (id, description, descriptionTranslated, parentId, parentDescription).

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, and front-loaded with the main action. Every sentence provides necessary information without redundancy.

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

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

Given no parameters and no output schema, the description covers the response structure and caching. It ties to a sibling tool for updating categories. Minor gap: could mention if there is any hierarchy depth, but overall 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?

With 0 parameters and 100% schema description coverage, the baseline is 3. The description adds no parameter info since none exist, but provides context on the response fields, which is helpful but doesn't affect this dimension.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy, cached for the adapter session. It distinguishes from sibling list tools by specifying it's for categories and noting the response structure and relationship to openfinance_update_transaction_category.

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

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

The description implies usage for retrieving category taxonomy to use in updating transactions, but does not explicitly state when to use this tool versus other list tools. It provides context on response fields but lacks direct usage guidance.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds value by explaining the add_connection_url field, but does not cover other traits like authentication or rate limits.

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

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

The description is a single, well-structured sentence that front-loads the verb and result. It is concise but could be slightly more efficient.

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

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

Given no input schema and no output schema, the description adequately covers what the tool returns and the purpose of the add_connection_url, but lacks details on potential filtering or ordering.

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

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

There are no parameters, so schema coverage is 100%. No parameter documentation needed; baseline of 4 is appropriate.

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

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

The description clearly states the tool returns saved bank connections and lists specific fields (connector_id, item_id, bank name, add_connection_url), distinguishing it from sibling tools like list_accounts or 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 implies usage for viewing existing connections and obtaining a URL to add more, but does not explicitly compare to alternatives or state 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 readOnlyHint, idempotentHint, destructiveHint already indicate safe read. The description goes far beyond: explains absence of paid/status field, payment allocation across bills, connector asymmetry for open_bill, bill_grouping_reliability warnings, and behavior when CREDIT_CARDS not enabled. No contradiction with annotations.

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

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

The description is very long and dense with information. It front-loads the key output fields but then goes into many caveats and details. While all information is useful, the verbosity reduces conciseness. Could benefit from more structured sections.

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 (5 parameters, no output schema, many edge cases), the description is remarkably complete. It covers output fields, payment semantics, open_bill details (including confidence and availability), connector asymmetry, warnings, and cross-references to other tools. All necessary context is present.

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

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

Schema has 0% description coverage, so the description must add meaning. It explains `account_id` (required), `include_open_bill` (opt-in, with full derived fields), and mentions `account_ids` for batch. However, `page` and `page_size` are not described, though they are standard pagination parameters. Overall adds substantial value beyond schema.

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

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

The description clearly states the tool returns CLOSED credit card bills for a CREDIT-type account, listing key fields. It distinguishes from sibling `openfinance_get_credit_card_bill` and cross-references `openfinance_list_transactions` for itemized transactions, making the specific purpose and scope unambiguous.

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

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

The description provides extensive guidance: when to use this tool (for closed bills), when to opt for open_bill, when to use transactions instead, and explicit warnings about not assuming payment status from payments array. It also tells when not to use balance for total debt and how to cross-check account echo with multiple 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?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds valuable behavioral context: that the tool returns a warning structure on errors, and lists the data fields included. This goes beyond annotations, providing detailed insight into the response.

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

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

The description is a single, well-structured paragraph that front-loads the main purpose, then enumerates details and error behavior. Every sentence adds value without 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?

The description covers the return structure, error handling, and data fields, but lacks explicit parameter explanations. Given the absence of an output schema and the tool's moderate complexity (4 params), the description partially fills the gap but leaves uncertainty about how to set parameters.

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 parameter descriptions are absent (0% coverage). The description only implicitly relates the 'type' parameter by listing asset types, but does not explain 'item', 'page', or 'page_size'. An agent would have limited guidance on how to use these parameters correctly.

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 an investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.) and includes error handling behavior. It distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on portfolio data rather than 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 specifies the condition for use ('connection with INVESTMENTS product enabled') and mentions the graceful fallback on errors ('Returns { total:0, results:[], warning } instead of throwing'). It does not explicitly mention when to avoid using this tool or compare to alternatives, but 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds valuable details about the returned fields (quantity, value, netAmount, expenses, etc.) and bulk execution, enhancing transparency beyond annotations.

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

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

The description is concise with two sentences, front-loading the purpose and key fields, and adding usage guidance without unnecessary words.

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

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

While the description covers purpose, key fields, and usage sequence, it lacks documentation for pagination parameters (page, page_size) and does not describe the response format beyond a field list, leaving some gaps for a data retrieval 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?

With 0% schema coverage, the description partially compensates by explaining investment_id (required) and investment_ids (bulk), but it omits any explanation of page and page_size parameters, leaving them undocumented.

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

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

The description clearly states that the tool returns movement history for a specific investment position, listing specific transaction types (BUY, SELL, TAX, etc.) and distinguishes it from siblings like openfinance_list_investments.

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 to use this tool after openfinance_list_investments to obtain investment_id, and mentions bulk support via investment_ids. However, it does not explicitly contrast with other transaction-listing siblings.

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 hints; the description adds behavioral context such as sequential querying with rate limiting, handling of multiple connections, 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?

Three well-structured sentences, front-loaded with purpose, each sentence adding value without redundancy. Ideal length for this tool.

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 good annotations, the description covers connection usage, return format, and rate-limiting behavior. Lacks detail on error structure but is sufficient given context signals.

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

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

The input schema has 0% coverage for parameter descriptions, so the description fully compensates by explaining that `items` are connection selectors (item_id, connector_id, or connector_name) and that omitting them fetches all linked banks. This adds significant 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 lists loan contracts per bank connection, identifies the endpoint (GET /loans), and distinguishes from sibling listing tools by focusing on loans and connection selectors.

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

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

Provides explicit guidance on when to pass `items` vs. omit it, explains what items represent, and notes sequential querying with rate-limit spacing. Does not explicitly state when not to use the tool, but context implies it for loans.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds critical behaviors: upstream error handling, auto-pagination up to 5000, per-connector variance for credit card metadata, provider incident block. 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?

Description is long but every sentence adds value. Front-loaded with purpose and key distinctions. Could be slightly more concise, but complexity justifies the length.

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

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

No output schema, so description explains return structure (account echo, results, truncated, warning, error, provider_incident). Links to related tools for additional data. Covers all major aspects for a complex 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 coverage is 0%, so description fully explains each parameter: from/to dates, page, page_size, detail enum meanings, search_queries substring matching, account_id and account_ids for bulk. Also explains auto-pagination when page omitted.

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 (BANK or CREDIT). It distinguishes from siblings by noting it's the only way for credit card transactions and references openfinance_list_credit_card_bills for bill totals.

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?

Extensive guidance: explicit when to use vs. alternatives (e.g., credit card bills), detail levels, pagination modes, bulk support, and warnings against summing by billId. Covers many edge 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?

Beyond annotations (readOnly, idempotent, non-destructive), describes truncation at 5000/account with truncated flag, provider_incident block for incomplete data, and detailed behavior for granularity/detail parameters. 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?

Long but front-loaded with core purpose. Every sentence adds value; could be slightly more concise but justified by complexity. 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?

Despite lacking output schema, description thoroughly documents return structure (monthly evolution, top expenses, per-account breakdown, truncated flag, provider_incident). Covers all parameters and their effects. Complete for agent decision-making.

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, description fully compensates: explains item as identifier types, from/to as ISO dates, granularity and detail values with return consequences, type filter, top_n. Provides meaning beyond schema.

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

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

Describes consolidation of cash-flow analysis for a bank connection in one call, avoiding separate account listing. Clearly states it resolves accounts internally and fans out transactions, distinguishing it from sibling tools like openfinance_list_transactions. Lists concrete use 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?

Provides when-to-use guidance: for consolidated analysis without prior account list, and when to choose granularity or detail levels. Does not explicitly list alternatives or when not to use, but implicitly contrasts with 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 indicate readOnly, idempotent, non-destructive. Description adds valuable behavioral context: returns global indicator, degraded components, open incidents, and flags affected banks.

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

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

Single paragraph, well-structured with front-loaded purpose. Slightly verbose but still 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?

For a zero-parameter tool with no output schema, the description thoroughly explains all return elements (global indicator, degraded components, incidents, your_banks_affected), making it complete.

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

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

No parameters, schema coverage 100%. Description does not need to add param info; baseline 4 is appropriate.

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

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

Explicitly states it checks the LIVE operational status of the Open Finance provider, distinguishing it from the connection's status tool. Provides specific use-case scenarios to clarify its purpose.

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

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

Clearly explains when to use this tool (data looks incomplete/stale despite updated connection) and distinguishes from the sibling openfinance_get_item_status.

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

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

The description adds significant behavioral context beyond the annotations: it explains the return of a connect_url, the caveat warning for non-Open-Finance connectors, and the plan-based filtering. It aligns with the annotations (readOnlyHint, idempotentHint) and does not contradict them.

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 is well-structured with logical flow. Every sentence adds value, though it could be slightly more concise (e.g., splitting into bullet points for clarity). No wasted words.

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

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

Given the absence of an output schema, the description thoroughly explains what the tool returns (connector id, access type, audience, linked connections, connect_url, caveat). It also mentions edge cases (non-Open-Finance connectors, plan limitation) and provides sufficient context for an agent to use the tool correctly.

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

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

With 0% schema description coverage, the description fully compensates by explaining the `keywords` parameter (required array of strings, example values) and the `include_accounts` parameter (boolean, controls whether linked accounts are returned). It also clarifies that keywords is required despite schema not marking it as required.

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 ('Searches', 'returns') and clearly identifies the resource ('bank connectors'). It distinguishes the tool from siblings by stating its role as a pre-connect search that returns a one-click connect URL, which is unique among the sibling 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 states when to use this tool ('Call this BEFORE connecting') and provides guidance on required input ('keywords[] is REQUIRED'). It also explains what happens without keywords (returns a hint) and mentions context-sensitive behavior like honoring the user's plan.

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 beyond annotations: overrides Pluggy's automatic categorization, creates a Category Rule (case-insensitive exact match), and describes batch error handling (per-item errors do not fail the whole batch). No contradictions with annotations.

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

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

Every sentence adds value; front-loaded with purpose. Slightly long but well-structured and informative.

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

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

Covers all aspects: purpose, parameters, side effects, return format, error handling. Despite lack of output schema, the described return shape suffices for a batch update 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?

Adds essential meaning to the sole parameter 'items': explains that transaction_id comes from openfinance_list_transactions and category_id from openfinance_list_categories. Provides return shape which aids understanding. Schema coverage is 0%, so description fully compensates.

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 'Corrects' and resource 'category of one or more transactions' with the HTTP method and endpoint. It distinguishes from sibling tools by referencing where transaction_id and category_id come from.

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?

Clearly states when to use: 'fix miscategorized transactions and improve categorization accuracy going forward.' Explains the side effect of creating a Category Rule. Lacks explicit 'when not to use' but is otherwise strong.

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, openWorldHint=false, idempotentHint=true, destructiveHint=false. The description adds that this tool sends feedback, which aligns with idempotent and non-destructive behavior. No contradictions, but it does not elaborate on side effects or communication process.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no redundant 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?

For a simple bug-reporting tool with no output schema, the description adequately covers the main usage and provides a key instruction (include conversation array). It could mention return behavior or confirmation, but is mostly 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?

With 0% schema coverage, the description partially compensates by explaining that 'conversation' should hold recent messages for reproduction. However, it does not describe the 'context' parameter, leaving its meaning unclear. The 'message' parameter is implied by context.

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: 'Report a bug, missing feature, or send feedback.' It uses a specific verb (report) and resource (bug/feature/feedback), distinguishing it from siblings focused on authentication and 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 implies when to use (when reporting issues) and instructs to include the conversation array, but it does not explicitly state when NOT to use or suggest alternatives. The guidance is limited to the reproduction hint.

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, destructiveHint. The description adds context by specifying what versions are shown (platform and adapter). No behavioral contradictions; safe and idempotent nature is implied.

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

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

Single sentence of 9 words, front-loaded with the verb, and no superfluous information. Every word contributes to clarity.

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 is adequate for a simple tool with no parameters and annotations covering safety. However, without an output schema, a hint about the return format (e.g., object or string) would improve completeness.

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

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

With 0 parameters and 100% schema coverage, baseline is 4. The description adds meaning by specifying the tool's output scope (platform and adapter versions), compensating for the lack of an output schema.

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

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

The description clearly states the tool shows version information, with specific verb 'show' and resource 'MCP platform and adapter versions'. It is distinct from sibling tools which focus on authentication, connection management, or finance 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 versus alternatives like toolkit_info. The context implies it is for retrieving version info, but differentiation from similar info tools is missing.

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

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

Annotations already declare readOnlyHint, destructiveHint false, and idempotentHint true. The description adds value by specifying the exact information returned (installed MCPs, connection status, catalog tools count), which goes beyond annotation hints.

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

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

The description is a single sentence that is clear, front-loaded, and contains no unnecessary 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 zero-parameter read-only info tool with strong annotations, the description is adequate. It covers all key aspects of the returned state. Missing details like return structure or error handling are not critical for this simple informational 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?

There are zero parameters, so schema coverage is 100% and no additional parameter information is needed. The description adds no param details, but this is acceptable given the lack of parameters.

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

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

The description explicitly states the tool returns toolkit state including installed MCPs, connection status, and catalog tool counts. It clearly distinguishes from sibling tools (e.g., authentication, Open Finance 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 implies the tool is for checking toolkit state but provides no explicit guidance on when to use it versus alternatives. Given the read-only nature, usage is straightforward but lacks depth.

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