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?

Discloses many behavioral traits beyond annotations: invoke works even for uninstalled MCPs, may require connect or payment, writes require owner/admin. Annotations are readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true, and description aligns fully, adding context about one-off runs and permanent installation effects.

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

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

The description is long but well-structured, front-loading the main purpose and then detailing the flow. Every sentence adds value, but it could be more concise; slight verbosity reduces score.

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 (13 parameters, no output schema, no schema descriptions), the description is highly complete. It covers main use cases, flow, edge cases (auth, payment), and role requirements. No output schema exists, so return values are not needed.

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 parameter descriptions), but the description adds significant meaning by explaining the action enum values and their effects, and the overall flow implies usage of parameters like query, mcp_id, tool_id, arguments. However, not all 13 parameters are individually described; the description partially 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 clearly identifies the tool as the official MCP marketplace and registry, with a specific verb ('search', 'describe', 'invoke') and resource. It distinguishes itself from sibling tools by stating it should be used first before external registries and lists other tool names.

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

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

Explicitly states when to use this tool (when the user wants a capability, use this first) and when not to (prefer external only after). Describes the core flow (search→describe→invoke) and distinguishes between install and invoke, with clear alternatives like list_tools, subscribe, etc.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by detailing the response structure, potential errors for credit accounts (structured warning), and that it returns both results and errors.

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 tightly packed sentences: purpose, parameter constraint, and response/error handling. Every sentence adds value and is front-loaded.

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 single-parameter tool with annotations, the description covers response shape, error handling, and parameter limits. No additional context seems necessary for an agent to correctly invoke and interpret results.

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

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

The schema only defines account_ids as an array of strings without constraints. The description adds array length limit (1–50) and clarifies it's an array, fully compensating for the 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 the tool returns real-time balance payload per account id, and references the REST endpoint. It distinguishes from sibling tools like openfinance_list_accounts by specifying balance retrieval.

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?

It specifies that account_ids must be passed as an array (1–50) and explains error handling for CREDIT accounts. However, it does not explicitly state when to use this tool over others, though it is implied.

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?

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds behavioral details: returns extended creditData, batch shape { results, errors }, and array size limits. This goes beyond annotations to inform about response structure and error handling.

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

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

Two sentences, front-loaded with purpose, then usage and response shape. No redundant or extra text. 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?

With no output schema, the description only hints at the response fields (full account objects with creditData) and the batch shape. It does not describe the full account object structure or other possible fields, leaving some uncertainty about what will be returned.

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

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

The input schema has zero description coverage (0%). The description adds crucial context: 'account_ids' must be an array of account ID strings with size 1-50. This fully explains the parameter's purpose and constraints, compensating for the schema's lack of documentation.

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 returns full account objects including extended creditData for specific IDs. Differentiates from sibling tools like list_accounts by emphasizing 'full' and 'extended' data, making the purpose unambiguous.

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

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

Provides usage constraints (array size 1-50, batch response shape) but does not explicitly tell when to use this tool versus alternatives like list_accounts or get_account_balance. The context is implied rather than stated.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds critical behavioral details: the batch shape { results, errors }, the meaning of payments[] (does not indicate this bill was paid), the absence of a paid/status field from Pluggy, and how to check paid status via a sibling tool. No contradictions with annotations.

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

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

The description is relatively long but well-structured, front-loading the core purpose and then providing necessary behavioral notes. While every sentence adds value, minor trimming could improve conciseness without losing information.

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

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

Given the tool has only one parameter, no output schema, and annotations covering safety, the description is fully complete. It covers return shape, limitations, domain-specific payment cycle logic, and cross-references to sibling tools for related functionality.

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 bill_ids parameter: that it should be passed as an array, and that IDs are discovered via openfinance_list_credit_card_bills. This adds essential context beyond the schema definition.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by ID, explicitly distinguishing it from sibling tool openfinance_list_transactions by specifying what it does NOT return (individual transactions). It uses a specific verb ('Returns') and resource ('bill-level detail'), making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool (to get bill details) versus openfinance_list_transactions (for itemized transactions), and advises using openfinance_list_credit_card_bills first to discover bill IDs. It also includes domain-specific behavioral notes about the payments array, preventing misuse.

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?

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral details: the `balance` field is connector-dependent and should not be interpreted as a standard monthly bill, and the `name` field is the legal entity, not the brand, advising use of `bank` for user-facing text. It also explains response structure differences based on the `item` parameter, providing valuable 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?

The description is front-loaded with the main purpose and proceeds to provide necessary details without redundancy. Every sentence adds value, from explaining the `bank` field to the warning about `balance` meaning. Despite being lengthy, it remains efficient and well-structured for an agent to parse.

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 two parameters, the description covers all essential aspects: response fields, behavior with and without `item`, nuances like connector-dependent balance, and a pointer to a sibling tool for more specific data. It is complete enough for an agent to use correctly without additional external 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?

The description thoroughly explains the `item` parameter's effect on aggregation vs. single connection, but it does not explicitly state that the `type` parameter (enum: BANK, CREDIT) acts as a filter for account types. Since schema description coverage is 0%, the description should have clarified that omitting `type` returns both types and including it filters accordingly. The mention of account types in the opening sentence is implicit but insufficient as a parameter explanation.

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 bank connections, detailing the types (BANK and CREDIT) and specific fields like balance, number, type, subtype, bankData, and creditData. It also distinguishes itself from sibling tools by mentioning the alternative tool `openfinance_list_credit_card_bills` for standardized bill amounts, making it specific and differentiated.

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 instructs when to omit the `item` parameter (to list accounts across all linked banks) and when to pass it (to target a single bank), providing clear usage context. It also warns not to treat `balance` as 'this month's bill' and directs to `openfinance_list_credit_card_bills` for standardized amounts, offering explicit alternatives and exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds 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?

The description is highly transparent about behaviors beyond annotations: it details the absence of a paid/status field, the derived payment_status logic, connector asymmetry (open bill not always available), and the fact that results are bill-level summaries. It also explains that the tool returns a warning instead of failing if the product is not enabled. Annotations (readOnlyHint, destructiveHint) are not contradicted.

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

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

The description is long but well-structured with sections (IMPORTANT, CONNECTOR ASYMMETRY). It front-loads the basic return fields and then provides necessary caveats. While dense, most sentences add value for the complex domain.

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

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

Given the complexity of Brazilian Open Finance, derived fields, connector asymmetry, and no output schema, the description is comprehensive. It covers payment status cross-check logic, open bill derivation, connector limitations, and integration with other tools. It leaves no critical gaps for an agent to misuse the 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 include_open_bill in detail, account_ids for bulk, and implicitly account_id as the credit account. However, page and page_size parameters are not explained, leaving a gap.

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

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

The description clearly states the tool returns CLOSED credit card bills for CREDIT-type accounts and lists specific fields (dueDate, totalAmount, etc.). It differentiates from sibling tools like openfinance_list_transactions by stating that this tool returns bill-level summaries, not individual transactions, and directs users to the sibling for itemized data.

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: for closed bills, with optional include_open_bill for open bills. It warns about Brazilian Open Finance semantics, explains payment_status logic, and tells users not to assume payment from payments[]. It also mentions using openfinance_list_transactions for itemized purchases and notes connector asymmetry.

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?

The description discloses many behavioral traits beyond annotations: PENDING vs POSTED behavior varies by connector, search_queries aggregates up to 5000 transactions, error handling returns warning/error object, detail levels affect token usage and coverage, and bulk support via account_ids. No contradictions with annotations.

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

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

The description is quite long but well-structured, front-loading the core purpose and progressively adding details. While every sentence adds value, some sections (e.g., credit card metadata enumeration) could be slightly compressed without loss. Still, it is appropriately sized for 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?

The description is comprehensive: covers data interpretation, error handling, search filtering, detail levels, bulk support, and links to sibling tools. Given the complexity (8 parameters, no output schema, and multiple edge cases), it provides complete contextual information 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 schema description coverage at 0%, the description fully compensates by explaining every parameter: from/to format (ISO YYYY-MM-DD), page_size max 500, detail enum with meanings and use cases, search_queries behavior (case-insensitive, OR semantics, aggregation), and bulk support. This adds critical 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 'Returns transactions for a bank account (BANK or CREDIT type)' and distinguishes between account types. It also differentiates from sibling tools like openfinance_list_credit_card_bills and openfinance_list_accounts by explaining when each should be used.

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 provides usage guidelines: for CREDIT accounts, it's the only way to get itemized transactions; recommends using openfinance_list_credit_card_bills for standardized bill totals; and suggests openfinance_list_accounts for closing/due dates. It also explains when to check connection health via 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?

Description adds critical behavioral details beyond annotations: scan caps at 5000 transactions per account with truncated flag, compact summary vs raw mode behavior. Annotations already declare readonly and idempotent, and description reinforces no destructive actions. 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 dense but well-organized: starts with purpose, then parameter details, use cases. Slightly verbose but every sentence adds value. Could be shortened by grouping some usage guidance, but not excessive.

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 7 parameters, no output schema, and complex behavior (aggregation, truncation, multiple granularities), description covers input semantics, output structure (compact vs raw), and truncation warning. Lacks details on error responses or rate limits, but overall complete 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?

Schema has 0% description coverage, but description fully documents all 7 parameters: item as connector_id/name or omitted for all, from/to as ISO dates, granularity and detail modes with results, type filter, and top_n context. Compensates completely for schema gap.

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

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

Description clearly states it does consolidated cash-flow analysis for a bank connection in one call, resolving accounts internally. Distinguishes from sibling openfinance_list_transactions by eliminating need for prior account listing and account_id passing.

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

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

Explicitly tells when to use (for cash-flow analysis) and what not to do beforehand (no need to call openfinance_list_accounts). Provides guidance on omitting item for all banks, granularity options, and detail levels. Could mention when not to use this tool (e.g., when you need raw per-account transactions without aggregation).

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?

Description adds context beyond annotations: return of connect_url, plan-based filtering, hint behavior without keywords. Annotations indicate safe read operation, and description aligns with that while enriching detail.

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 a single paragraph but dense with information. Front-loaded with main purpose. Could be slightly more structured, but no unnecessary words 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?

No output schema, but description explains all return fields. Covers parameter behavior, plan filtering, and special cases. Complete for a search tool with 2 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 has 0% description coverage, but description explains keywords as array of strings with example, states it is REQUIRED despite schema, and explains include_accounts triggers accounts in output. Adds significant meaning.

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

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

Description clearly states it searches bank connectors by name, lists returned fields (connector id, access, audience, connections, accounts, connect_url), and distinguishes behavior without keywords. It is specific and differentiates from siblings like listing 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?

Explicitly instructs to call BEFORE connecting to provide a one-click link, and notes plan-based filtering (PF hides PJ). Does not explicitly list when not to use or alternatives, but provides clear context for 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 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.