Banco Mercantil MCP

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

The description explains the outcome of calling with or without a token, and the difference between permanent config-based and session-based login. However, it does not mention idempotency (though annotated) or security implications of handling tokens. Overall, it adds useful behavioral context beyond annotations.

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

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

The description is somewhat verbose but well-structured: it starts with the tool's purpose, then explains the two usage methods. Every sentence adds value, though it could be slightly more concise.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers all necessary context: the two authentication methods, the parameter usage, and the fallback to getting a link. No additional information 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?

The input schema has 0% description coverage, but the tool description compensates fully by explaining the token parameter: it should be a JWT pasted by the user for session login, and that calling without the parameter returns a login link. This adds essential meaning to the parameter.

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

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

The description clearly states the tool's purpose: authenticating a user via browser login and token. It specifies both a permanent configuration-based method and a session-based method with a token parameter. The purpose is specific and distinct from siblings which cover different functionalities.

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

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

The description provides explicit usage guidance: using the config header for a permanent connection, or passing a token for session-only login, or calling with no arguments to get the login link. This helps the agent decide between parameter values and modes of operation.

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 read-only, idempotent behavior. The description adds value by detailing the return structure in different states (authenticated:true vs. connect_url), providing behavioral context beyond the annotations.

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

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

The description is concise with two sentences, no unnecessary words. The first sentence immediately conveys the core purpose, making it efficient for an AI agent to understand.

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

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

Given no output schema, the description adequately explains the return values for the two mentioned states. However, it could be more complete by describing behavior in other potential states (e.g., partial connection).

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

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

The tool has zero parameters, so the baseline score is 4. The description does not need to add parameter information, and it correctly focuses on the return 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 the tool returns connection status and URLs, with specific details about different scenarios. It distinguishes itself from sibling tools like 'authenticate' by focusing on status retrieval rather than initiating authentication.

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

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

The description provides context on when to use the tool by describing the two main states (all providers connected or credentials missing). However, it does not explicitly mention when not to use it or name alternative tools like 'authenticate'.

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 behaviors beyond annotations: invoke works on uninstalled MCPs, returns connect/checkout links, and explains the one-off vs permanent installation distinction. Annotations only indicate non-read-only/non-destructive, so the description adds significant context.

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

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

The description is detailed but every sentence adds value. It is front-loaded with purpose and core flow, then expands on key behaviors. Slightly dense but not wasteful.

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 (15 parameters, multiple actions, no output schema), the description covers the full workflow, edge cases (auth, payment, retry), and distinguishes between permanent and one-off usage. It is fully actionable by an AI agent.

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

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

Schema coverage is 0% with 15 parameters. The description explains the overall flow and action parameter but does not detail each parameter's meaning, only partially compensating for the lack of schema descriptions.

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

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

The description clearly states it is 'THE official mcp.ai marketplace' and lists actions like search, describe, install, invoke, etc., distinguishing it from sibling tools by being the central discovery and execution hub.

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, provides a core flow (search→describe→invoke), explains when to use invoke vs install, and notes that writes require workspace owner/admin.

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

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

Annotations already mark as destructive (destructiveHint=true). The description adds that data becomes unavailable and returns a re-connect URL, providing useful behavioral context beyond the annotation.

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

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

Two sentences, no redundant words. First sentence states the action, second adds consequence and return value. Perfectly concise and 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?

Given the tool has one undocumented parameter, no output schema, and limited annotations, the description covers the core action and return value but leaves parameter meaning unspecified, reducing 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?

The single 'item' parameter is required but not described. The description mentions 'a specific bank' but does not link it to the 'item' field or clarify its format. With 0% schema coverage, the description fails to compensate.

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

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

The description clearly states the action: revokes consent and deletes connection data for a specific bank. It distinguishes from sibling tools like 'connect' or 'list_connections' by specifying the destructive nature and the return of a re-connect URL.

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

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

The description implies usage for disconnecting a bank but does not explicitly state when to use versus alternatives (e.g., 'openfinance_force_sync' or 'openfinance_list_connections'). No competitor tool is mentioned, leaving the agent to infer context.

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

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

Discloses that it uses PATCH and polls up to ~60s, can be fire-and-forget with wait:false, and explains return fields like status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out. 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?

Description is detailed and well-structured but somewhat lengthy. However, every sentence serves a purpose, and it is front-loaded with the core action. Minor room for trimming.

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

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

Given no output schema, the description fully explains return structure and possible statuses. It compensates for low schema coverage and provides all necessary 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?

Despite 0% schema coverage, the description thoroughly explains both parameters: items as an array of selectors (item_id, connector_id, connector_name) and wait as boolean for fire-and-forget mode. Provides full semantic meaning.

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

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

The description explicitly states it forces a re-sync of connections and waits for completion, distinguishing it from sibling tools like openfinance_get_item_status which is for checking 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 clear guidance on when to use (stale balance/transaction list), what it achieves (pulls fresh data without disconnecting), and how to use (pass items array or omit to sync all). Also mentions alternative action (re-check with 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?

Annotations declare read-only, idempotent, non-destructive. Description adds degradation behavior (warning for CREDIT accounts, upstream failures returning last-synced balance) and response shape, exceeding transparency needed.

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?

Concise with front-loaded purpose, no fluff. Could be slightly tighter but well-structured.

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

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

Covers single parameter, error handling, response shape despite no output schema. Complete for typical balance 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; description clarifies account_ids is an array of 1-50 strings, adding 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?

Description clearly states it returns real-time balance per account ID, specific endpoint, and differentiates from sibling tools like list_accounts or get_accounts_detail.

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

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

Implicitly clear when to use (need balance), but no explicit when-not or alternatives among siblings. Constraints like array size are provided.

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

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

Annotations already declare readOnlyHint and idempotentHint; the description adds valuable behavioral context about the provider_incident block and reliability warnings, and the batch {results, errors} shape.

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 no filler: two sentences covering purpose, usage, and a critical caveat, all front-loaded efficiently.

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

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

Given a single parameter, no output schema, and good annotations, the description covers usage and a notable behavioral edge case. It could mention that it's a read-only batch operation, but overall 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 provides no parameter description (0% coverage), but the description explains the parameter purpose, constraints (array of strings, 1-50 items), and usage, compensating for the gap.

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

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

The description clearly states it returns full account objects with extended creditData for specific IDs, distinguishing it from sibling tools like openfinance_list_accounts which lists all accounts.

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

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

It explains how to use (pass account_ids as an array of 1-50) and mentions batch shape, but does not explicitly compare to alternatives like openfinance_list_accounts or when not to use.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false. The description adds critical behavioral details: batch shape {results, errors}, Pluggy's missing paid/status field, payment interpretation (payments during this bill cycle typically reflect previous bill), and sparse/inconsistent creditCardMetadata.billId. 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?

Description is detailed but well-structured: starts with purpose, lists fields, then negative guidance, usage instructions, and warnings. Every part adds value, though slightly long. Could be tightened by removing redundancies.

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

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

Despite no output schema, the description covers key return fields, batch shape, edge cases (sparse billId, Pluggy status, payment interpretation), and prerequisites. For a tool with one parameter and annotations providing safety, this is highly 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?

Single parameter bill_ids (array of strings) with schema coverage 0%. The description explains its purpose (use after list bills) and that it's an array, adding context beyond the schema. Since parameter is simple, extra detail is sufficient.

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, lists specific fields (financeCharges, payments), and explicitly distinguishes it from openfinance_list_transactions, which handles individual transactions. This differentiates it from sibling tools effectively.

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: use openfinance_list_credit_card_bills first to discover IDs, pass bill_ids as array, and important caveats about not reconstructing totals and interpreting payments. It contrasts with the transaction tool but lacks explicit 'when not to use' statements.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the return fields (status, executionStatus, connector metadata) and the two operation modes. No contradictions.

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

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

Two sentences: first states the main purpose and return types, second explains parameter usage. No filler words. Front-loaded with key information.

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

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

Given no output schema and one optional parameter, the description covers parameter semantics and return structure (single vs. multiple). However, 'connector metadata' is vague; more detail 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?

The only parameter, `item`, lacks schema description (0% coverage), but the description fully explains its purpose: omit for all banks, pass for a single bank. This adds complete meaning beyond the schema.

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

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

The description clearly states the tool returns the current status of a bank connection, including specific status values like UPDATED and UPDATING, and distinguishes between retrieving a single bank's status or all linked banks.

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

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

Explicitly explains when to omit or include the `item` parameter: omit for all banks (returns count and items), pass for a single bank. No sibling tool duplicates this functionality, but the guidance is clear.

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

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

Annotations already indicate readOnlyHint and idempotentHint. Description adds batch shape `{ results, errors }` and field details, providing extra behavioral context beyond annotations.

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

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

Description is one sentence with list of fields; efficient but slightly long. 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?

With no output schema, description fully covers return fields, input constraints, and usage sequence. 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?

Schema has 0% coverage; description adds array size limit (1-50) and output shape, compensating for lack of schema description.

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 loan contract detail by ID, listing many specific fields. It distinguishes from sibling tools by mentioning usage after openfinance_list_loans.

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 to use after openfinance_list_loans and specifies passing loan_ids as an array of 1-50. No explicit when-not-to-use, but context is clear.

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

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

Annotations already mark it read-only and idempotent. Description adds critical behavioral details: connector-dependent credit balance meaning, provider incident block causing unreliable values, and that `name` is issuer not brand. These go beyond annotations, providing 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 dense and well-structured, front-loading core functionality then caveats. Could be slightly more concise, but the length is justified by the complexity of the tool's behavior.

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

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

Given no output schema, the description comprehensively covers return values (fields, meaning of `bank` vs `name`), parameter behavior, and nuances (credit balance, provider incidents). It leaves no major gaps for a tool of this complexity.

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

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

Input schema has 0% description coverage, but the description thoroughly explains both parameters: `item` (optional, controls aggregation vs single bank) and `type` (implied by coverage of account types). Also explains response fields like `bank`, `connector_id`, etc. Fully compensates for missing schema descriptions.

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

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

Clearly states it returns accounts for bank connections, distinguishing between BANK and CREDIT types. Provides specific fields (balance, number, type, subtype, bankData, creditData). 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?

Explicitly explains when to omit vs pass the `item` parameter: omit for all banks, pass for a single bank. Warns against treating CREDIT balance as bill amount and directs to alternative tool for standardized bill data. This provides clear 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?

The description discloses caching behavior, the aggregated nature of the response, and provides full details of each entry's fields (id, description, descriptionTranslated, parentId, parentDescription). This adds significant value beyond the annotations, which only indicate read-only and idempotent 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 well-structured, starting with the core functionality and then detailing return fields. While slightly lengthy, every sentence adds value and it is not unnecessarily verbose.

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

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

Given the absence of an output schema, the description provides a complete picture of the returned data, including field usage notes (e.g., Portuguese translation preference). It is sufficient for an agent to understand the tool's output and how to use it.

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

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

With zero parameters, schema coverage is 100%. The description does not need to provide parameter semantics, and the baseline score of 4 is appropriate since it does not miss any opportunity to add 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 the tool returns Pluggy's transaction category taxonomy, cached for the session. It distinguishes itself from related tools by explicitly linking the returned `id` to the parameter expected by openfinance_update_transaction_category, making its 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?

While there is no explicit 'when to use' vs alternatives, the description implies its usage by detailing the structure and connection to another tool. It lacks explicit exclusions but is clear enough for an agent to infer appropriate contexts (e.g., before updating a transaction category).

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. The description adds specific return fields and the mention of an add_connection_url, which provides useful behavioral context beyond what annotations convey.

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, complete sentence that efficiently conveys the tool's purpose and return values 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?

For a simple list tool with no parameters and clear return fields, the description is largely complete. However, it could mention whether the list is paginated or any authentication requirements, but given the zero parameters and annotations covering safety, it is sufficient.

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

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

The input schema has zero parameters, so schema description coverage is 100%. The description need not add parameter meaning; 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?

The description clearly states the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, add_connection_url). It distinguishes from siblings like openfinance_list_accounts or openfinance_list_transactions.

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

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

The description implies usage for retrieving saved connections but does not provide explicit guidance on when to use this tool versus alternatives such as openfinance_list_accounts or openfinance_get_item_status. No when-not-to-use or prerequisites are mentioned.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral depth: explains payment allocation across bills, derived payment_status logic, connector asymmetry for open bills, and reliance on authoritative totalAmount. 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?

Description is comprehensive but verbose. It repeats some points (e.g., include_open_bill explanation). Could be more concise with bullet points or structured sections. Front-loads core purpose but then dives into extensive detail.

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 (5 parameters, no output schema, many edge cases), the description covers connector asymmetry, derived fields, reliability warnings, and cross-references sibling tools. 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?

Schema description coverage is 0%, but description compensates with detailed explanation of include_open_bill (what it returns, confidence, fallbacks). account_ids and account_id are implicit. Lacks details on page/page_size, but they are standard pagination.

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 like dueDate, totalAmount, payments, and derived payment_status. It distinguishes from sibling tools like openfinance_list_transactions and openfinance_get_credit_card_bill.

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

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

Explicit when-to-use guidance: explains include_open_bill opt-in, when to avoid summing transactions by billId, and how to interpret payment_status. Provides exclusions like not to assume a bill is paid just from payments[]. References alternatives for itemized transactions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by revealing error handling behavior (returns structured response instead of throwing) and listing response fields. No contradictions.

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

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

The description is a single paragraph that front-loads the main purpose. While not extremely concise, it is informative and contains no fluff.

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

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

Given no output schema and low schema coverage, the description should explain parameters and pagination. It fails to describe what 'item' refers to or how page/page_size work, leaving gaps for an agent to correctly invoke 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?

Schema description coverage is 0% and the description provides no explanation for any of the four parameters (item, page, type, page_size). The description only mentions response fields, not input 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 clearly states it returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It distinguishes from sibling tools like openfinance_list_accounts and openfinance_list_investment_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 when to use (to get investment portfolio) and mentions error handling when INVESTMENTS not enabled. However, it does not explicitly state when not to use it or compare to alternatives like openfinance_list_investment_transactions.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds significant behavioral context by enumerating the fields returned (quantity, value, amount, netAmount, etc.) and the types of movements, which is essential since there is no output schema.

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 short paragraphs: the first explains return content, the second provides usage context and bulk capability. 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?

The tool has 4 parameters and no output schema, requiring description to cover key aspects. It explains return fields, movement types, and usage sequence. Missing pagination details and default behavior, but otherwise sufficient for effective tool use.

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

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

Schema description coverage is 0%, so the description must compensate. It explains investment_id (implied from usage hint) and investment_ids (bulk), but does not mention page or page_size parameters. This leaves pagination behavior undocumented, a noticeable 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 verb 'returns' and the resource 'movement history for a specific investment position', listing specific transaction types (BUY, SELL, TAX, etc.). This distinguishes it from sibling tools like openfinance_list_investments which lists positions.

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 instructs to use this tool after openfinance_list_investments to obtain the investment_id, and mentions bulk support via investment_ids. While it does not explicitly list when not to use, the sequence hint and bulk guidance are sufficient for typical usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds valuable context: sequential query execution, rate-limit spacing, and 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 sentences efficiently convey purpose, parameter usage, and return format. No filler, information is front-loaded with the core action and endpoint.

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

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

Despite no output schema, the description explains the return structure and key behaviors (sequential queries, rate limiting). For a read-only list tool with a single optional parameter, this provides sufficient context 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 has 0% description coverage, but the description fully compensates by explaining that 'items' is an array of connection selectors (item_id uuid, connector_id, or connector_name), each entry for one connection, and that omitting it fetches all banks. 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 lists loan contracts per bank connection, specifies the GET endpoint, and differentiates behavior when 'items' is passed vs omitted. It distinguishes from sibling list tools by focusing on loans and connection-level scoping.

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' (for specific connections) and when to omit (all linked banks). Also mentions sequential querying with rate-limit spacing. Lacks explicit when-not-to-use alternatives, but no sibling tool duplicates this functionality.

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?

Disclosures beyond annotations: auto-pagination with 5000 ceiling, truncated flag, error handling returning non-throwing objects, detail level behaviors, credit card billId sparsity, provider incidents, pending vs posted variations per connector. Annotations already indicate readOnly and idempotent, and description aligns without contradiction. Excellent 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?

Very long but well-structured with clear sections (CREDIT vs PENDING, PAGINATION, etc.) and front-loaded with core purpose. Some repetition (e.g., billId caveats mentioned twice) prevents a perfect 5, but the organization aids readability.

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 must cover return values. It describes the account echo block, total, results, truncated flag, warning/error objects, provider_incident block, and details of rich/raw output. Covers all essential response 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 must compensate. It thoroughly explains all 8 parameters: from/to (ISO dates), detail (compact/rich/raw with usage notes), page/page_size (pagination logic), search_queries (case-insensitive substring search with OR semantics), account_id, and account_ids (bulk support). Provides meaning far 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 transactions for BANK or CREDIT accounts, and distinguishes itself as the only way to get itemized credit card transactions (vs openfinance_list_credit_card_bills which provides aggregated bill data). This specificity and sibling differentiation earns a 5.

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 this tool (listing transactions, especially for credit cards) and when not to (reconstructing bill totals by billId). Suggests alternatives like openfinance_list_credit_card_bills and openfinance_list_accounts, and advises checking connection health. This comprehensive guidance merits a 5.

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

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

Annotations declare readOnly and idempotent, which description complements by disclosing truncation at 5000/account and provider_incident block that may indicate incomplete data. 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?

The description is thorough and well-organized, though slightly long. It front-loads purpose and provides structured parameter explanations. Could be trimmed slightly, but every sentence adds value.

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

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

Given 7 parameters, no output schema, and complexity (consolidation, multiple granularities, enrichment, truncation, provider incidents), the description is exceptionally complete. It explains return structure, error conditions, and usage nuances.

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

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

With 0% schema coverage, description fully explains each parameter: `item` (connector_id/name or omit), `from`/`to` (ISO dates), `granularity` (monthly vs raw with behavior), `detail` (compact/rich/raw meanings), `type` (BANK/CREDIT), and `top_n` (largest N). Provides defaults and return implications.

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 performs consolidated cash-flow analysis for a bank connection in one call, resolving accounts internally. It distinguishes from sibling tools like openfinance_list_transactions by emphasizing that you don't need to list accounts first.

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

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

Explicitly provides when-to-use scenarios: 'análise anual/mensal', 'fluxo de caixa', etc. Tells user when to omit `item` for all banks and explains use cases for different granularity/detail levels. Also specifies when not to call other tools.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context about return content (global indicator, degraded components, open incidents, your_banks_affected), going beyond annotations. No contradictions.

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

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

Single paragraph, well-structured. Every sentence adds value, but could be slightly more concise. Front-loaded with main purpose and usage conditions.

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 enumerates return fields (global indicator, degraded components, open incidents, your_banks_affected). Covers all needed context for a parameterless tool with clear annotations.

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 doesn't need to add parameter info; baseline for 0 params is 4. Description adds no param details, but that's appropriate given absence.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, distinguishes it from `openfinance_get_item_status`, and specifies the resource (provider's health). Uses specific verb 'checks' and resource reference.

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

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

Explicitly says when to use: when data looks incomplete or stale despite connection showing updated. Contrasts with `openfinance_get_item_status` and explains it helps differentiate provider-side problems from connection issues.

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 and idempotentHint. The description adds valuable behavioral details: that omitting keywords returns a hint (never dumps catalog), that it honors plan constraints, and that credential connectors have a caveat about manual reconnection. 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 dense but every sentence adds value: main purpose, return values, caveat, usage instruction, and parameter requirement. It is front-loaded with the core action and well-organized without 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 no output schema, the description adequately describes the return fields and usage constraints. It covers plan honoring and the caveat. It could be slightly more explicit about output format but is detailed enough for an AI agent to understand the tool's behavior.

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

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

With 0% schema description coverage, the description fully explains both parameters: it provides an example for keywords (['nubank','btg']), states it is REQUIRED, and describes how include_accounts=true affects the return (adds accounts). The description compensates completely for missing schema 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?

The description clearly states that the tool searches bank connectors by name (keywords). It lists the specific return fields (connector id, access type, audience, linked connections/accounts, connect_url), distinguishing it from sibling tools like 'connect' or 'list_connections'.

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

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

The description instructs to call this tool 'BEFORE connecting' and notes that it honors the user's plan, providing context on when to use. It also warns about non-Open-Finance connectors having caveats, guiding toward Open Finance. However, it does not explicitly mention when not to use or compare to all alternatives.

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

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

The description reveals that recategorizing teaches Pluggy and creates a Category Rule, which goes beyond annotation hints. It also describes batch behavior with per-item error handling. 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 slightly long but each sentence provides necessary context. The main action is front-loaded. Could be trimmed slightly without losing value.

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

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

For a mutation tool with no output schema, the description fully explains return format, side effects, and error handling. Complete for an agent to understand usage.

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

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

Schema has 0% description coverage, but the description explains where to obtain transaction_id and category_id, the batch shape, and the teaching behavior, fully compensating for the schema's lack of param descriptions.

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

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

The description clearly states the tool corrects transaction categories, references the HTTP method and endpoint, and distinguishes itself from list tools like openfinance_list_transactions and openfinance_list_categories. No ambiguity.

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

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

The description explains when to use (fix miscategorized transactions) and the side effect (creates a Category Rule). It could explicitly mention when not to use, 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 indicate idempotentHint=true and no destructiveness. The description adds context about including conversation for reproduction but does not disclose further behavioral traits (e.g., error handling, rate limits, or backend processing).

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

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

The description is only two sentences, front-loaded with the core purpose, and every word contributes. No wasted content.

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

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

For a simple tool with no output schema and three parameters (two with defaults), the description covers the main purpose and the critical 'conversation' parameter. However, it omits what happens upon submission (e.g., confirmation) and does not explain the 'context' parameter.

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 adds meaning for the 'conversation' parameter (explaining it should contain recent messages). However, it does not explain 'context' or 'message' beyond their role, leaving gaps. Baseline is low but partially compensated.

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 a specific verb 'report' and identifies the resource ('bug, missing feature, or send feedback'). It clearly states the tool's scope and is distinct from all sibling tools, which are unrelated (e.g., openfinance, authenticate).

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: include the conversation array for reproduction. While no explicit when-not-to-use or alternatives are given, the purpose is straightforward and no similar sibling exists, so the guidance is adequate.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds minimal behavioral context beyond stating what is shown. No contradictions are present, and the description does not disclose any further behavioral traits (e.g., caching, latency).

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 one sentence of 9 words, front-loaded with the action and resource, and contains no extraneous information. Every word is functional and earns its place.

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

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

Given the tool's simplicity (no parameters, no output schema, a straightforward version display), the description is complete. It adequately informs the agent of the tool's purpose without needing additional detail.

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

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

The tool has no parameters, and the schema description coverage is 100%. According to guidelines, 0 parameters yields a baseline score of 4. The description does not need to add parameter information as there are none.

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 current MCP platform and adapter versions, using a specific verb (show) and resource (versions). It uniquely distinguishes itself from sibling tools which are mainly about 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?

The description implies usage context (checking version information) but does not explicitly state when to use or avoid using this tool. However, given its simplicity and lack of parameters, the purpose is straightforward and no exclusions are needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds the specific return data (installed MCPs, connection status, catalog tool counts), providing value beyond annotations without 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?

A single sentence, front-loaded with the verb and resource, and no wasted 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?

With zero parameters, rich annotations, and a clear description of return fields, the tool is fully described despite no output schema. No gaps.

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

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

There are zero parameters and schema coverage is 100%, so the baseline is 4. The description need not add parameter info; it is complete as-is.

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

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

The description clearly states the verb 'Returns' and the resource 'current toolkit state', specifying three distinct components (installed MCPs, connection status, catalog tool counts). It easily distinguishes from sibling tools like authenticate or connect.

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

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

The description implies usage when needing toolkit state, but does not explicitly state when to use versus alternatives. However, given it is a read-only info tool, guidance is clear from context.

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