Neon MCP

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

Annotations already indicate idempotentHint=true and destructiveHint=false. Description adds context about token handling and non-expiring connections, but omits details like error responses or side effects like token validation.

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 purpose, efficient sentences. Slightly verbose but every sentence adds value. Could combine some phrases.

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 moderate complexity and no output schema, description covers the main authentication flows. Lacks details on return values or error scenarios, but sufficient for an authentication 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 for the single parameter 'token'. Description compensates by explaining the token is a JWT and how to use it with or without the argument.

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 authenticates the user via a browser login and token. It distinguishes from siblings like 'connect' by focusing on token-based auth, but could be more explicit about scope.

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 when-to-use guidance: permanent config vs session-only. Does not list exclusions or alternatives like 'connect', but context signals and sibling list help.

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

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

Annotations declare readOnlyHint and idempotentHint, which are consistent. The description adds value by detailing return behavior under different connection states (authenticated vs. missing credentials), which goes beyond what annotations provide.

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

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

Two concise sentences, front-loaded with the core purpose, and no extraneous 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 simple behavior, the description covers two key states (all connected vs missing credentials). However, it does not address partial connectivity or error conditions, but for a status check tool this is acceptable.

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

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

No parameters exist and schema coverage is 100%, so description does not need to add parameter details. The focus on output behavior is appropriate.

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

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

The description clearly states 'Returns connection status and URLs' and provides specific scenarios, distinguishing it from the sibling 'authenticate' tool that likely performs authentication rather than reporting 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?

The description implies usage for checking connection status but does not explicitly state when to use it versus alternatives like 'authenticate'. No exclusions or direct comparisons 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?

Discloses key behaviors: invoke works even for uninstalled MCPs, returns connect/checkout links on credential or payment issues, and writes require owner/admin. Annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) are consistent, and description adds valuable context beyond them.

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

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

The description is packed with information in a single paragraph. While it could benefit from structured formatting (e.g., bullet points for actions), it remains fairly concise given the complexity and avoids unnecessary repetition.

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

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

With 15 parameters, no output schema, and no nested objects, the description should cover return values and explain all parameters. It does not describe the output format for actions like search or invoke, and many parameters are left undocumented, making the tool potentially confusing for agents.

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

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

Schema description coverage is 0%, and the description does not explain individual parameters like immediate, tier_slug, conversation, cancel_reason, etc. It only briefly mentions action, query, mcp_id, tool_id, and arguments in the flow. Lacks detail for most of the 15 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 identifies the tool as the official marketplace for MCPs/tools, listing all actions (search, describe, install, invoke, etc.) and distinguishing it from external registries. It provides a comprehensive overview of its role as both catalog and execution engine.

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

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

Explicitly states to use this tool first before external registries. Provides clear guidance on when to use invoke vs. install, mentions owner/admin requirements for writes, and explains the flow of search→describe→invoke. Covers all sub-actions like subscribe, cancel, report_bug, request_mcp.

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 destructiveHint=true; description adds value by stating it returns an add_connection_url for reconnection. 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 efficiently cover action and return value. Could be improved by adding parameter clarification without becoming 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?

Adequate for a simple destructive tool with one param, but missing parameter documentation leaves a completeness gap.

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% and description does not explain the sole parameter 'item'. No details on format, source, or relation to sibling tools.

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 revokes consent and deletes connection data, making bank data unavailable. It distinguishes from siblings like openfinance_list_connections by specifying a destructive disconnect 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?

Implies usage for disconnecting a bank, but lacks explicit guidance on prerequisites (e.g., listing connections first) or when not to use. No mention of alternatives.

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

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

Describes polling behavior, timeout (60s), return fields including timed_out and needs_action. Does not contradict annotations; adds context that annotations lack.

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?

Slightly verbose but front-loaded with key action. Contains no unnecessary sentences; 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 no output schema, explains return structure ({ results, errors }) and key fields. Covers failure modes and provides complete context for agent decision-making.

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

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

With 0% schema coverage, description fully explains the two parameters: wait (boolean, fire-and-forget) and items (array of selectors, omission syncs all). Adds 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?

The description clearly states the tool forces a bank to re-sync connections and waits for completion, mentioning the HTTP method and process. It distinguishes itself from related 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?

Explicitly says when to use (when balance or transaction list looks stale) and what it does not do (disconnect/reconnect). Provides alternatives like setting wait: false for fire-and-forget and explains how to sync specific items vs all.

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 valuable transparency about potential warnings for CREDIT accounts and graceful degradation (last-synced balance) without throwing errors, which is 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?

Every sentence serves a purpose: purpose, parameter usage, edge cases, and response shape. No fluff, well-structured 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?

For a simple tool with one parameter and no output schema, the description covers all necessary aspects: endpoint, parameters, error handling, and response structure. Complete enough for effective use.

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

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

The only parameter, account_ids, has 0% schema description coverage. The description compensates by specifying it's an array (1-50) and explains how different account types (CREDIT) affect the response, adding meaning beyond the schema.

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

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

The description clearly states it returns real-time balance per account ID, specifies the REST endpoint, and distinguishes it from sibling tools that list accounts or details.

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 the account_ids parameter (array of 1-50), and details edge cases for CREDIT accounts and temporary unavailability. Could explicitly mention when not to use, but context is sufficient.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint. Description adds critical behavior: batch shape {results, errors}, potential provider_incident block, and a warning about unreliable credit limits/balances during incidents. This goes well beyond annotations.

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

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

Description is three sentences, front-loaded with purpose. It efficiently covers endpoint, parameters, batch shape, and an edge case. Minor redundancy (GET /accounts/:id and batch shape phrasing) could be tightened.

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 explains return shape (full objects, extended creditData, batch {results, errors}) and the provider_incident scenario. It does not enumerate all possible fields but covers key aspects for agent decision-making.

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

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

With only one parameter (account_ids) and 0% schema description coverage, the description adds useful meaning: array of strings, 1-50 items, and batch response shape. It explains how the parameter is used but does not detail each parameter explicitly.

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

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

Description clearly states it returns full account objects with extended creditData per id, and specifies the HTTP method and endpoint pattern. It distinguishes from sibling tools like openfinance_list_accounts that likely provide summary 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?

Description specifies to pass account_ids as an array of 1-50 items, but does not explicitly state when to use this tool versus siblings like openfinance_list_accounts or openfinance_get_account_balance. No alternatives or when-not-to-use guidance is given.

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 destructiveHint=false, but the description adds valuable behavioral context: the batch response shape ({ results, errors }), the fact that Pluggy does not return a paid/status field, and the nuanced meaning of payments[] (reflecting previous bill's payment). No contradictions with annotations.

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

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

The description is well-structured, front-loading the core purpose, then detailing inclusions, exclusions, usage guidance, warnings, and notes. It is fairly concise given the complexity, though slightly verbose in some areas (e.g., the paragraph on payments).

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 reasonably explains return fields (financeCharges and payments with subfields) and the batch shape. It covers important nuances (payments interpretation, absence of paid status). However, it does not fully describe all possible fields or response structure, leaving some ambiguity.

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 is one required parameter (bill_ids) with 0% schema description coverage. The description adds some meaning by stating 'Pass bill_ids as an array' and referring to openfinance_list_credit_card_bills to discover IDs, but it does not specify format constraints (e.g., string pattern) or expected length. This is adequate but not highly informative.

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

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

The description clearly states it returns bill-level detail for one or more credit card bills by ID, listing specific fields (financeCharges, payments). It explicitly distinguishes from sibling tools like openfinance_list_transactions (for itemized transactions) and notes that openfinance_list_credit_card_bills should be used first to discover IDs. The purpose is specific and unambiguous.

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

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

The description provides explicit guidance on when to use the tool (for bill-level detail) and when not to (do not use for individual transactions; instead use openfinance_list_transactions). It also advises using openfinance_list_credit_card_bills to discover bill IDs and warns about interpreting the payments array in the context of Brazilian Open Finance. Alternatives and exclusions are 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 declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the tool is clearly safe and read-only. The description adds valuable behavioral context: the return structure for all vs. single bank and the types of status values. 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, no redundancy. The first sentence states what the tool returns, the second explains parameter usage. Every sentence serves a purpose, and the structure is front-loaded with the core action.

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

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

With one optional parameter and no output schema, the description covers return types and parameter behavior well. It could mention prerequisites (e.g., existing connection) but is sufficiently complete given the annotations and low complexity.

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

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

Schema covers 0% of parameter descriptions, but the description fully explains the `item` parameter: omit for all banks, pass for a single bank. This adds critical meaning beyond the schema, making parameter semantics excellent.

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 states 'Returns the current status of a bank connection' with specific status examples and mentions executionStatus and connector metadata, making the action and resource clear. It distinguishes from sibling tools like openfinance_list_connections by focusing on status rather than listing.

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

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

The description explicitly instructs when to omit the `item` parameter (get all banks) and when to pass it (single bank), providing clear context for usage. It does not explicitly mention when not to use or alternatives, but the guidance is sufficient for the tool's purpose.

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 that this is a batch operation with array input and returns '{ results, errors }', disclosing the batch shape and error handling pattern. It does not contradict annotations. Minor absence of rate limit or size limit details prevents a 5.

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 efficiently front-loads the purpose, then lists returned fields, followed by usage guidance and parameter specification. Every sentence adds value with no 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 output schema, the description lists many key return fields (interest rates, charges, installments, etc.). It also covers batch shape and array limits. It could be more structured or note optionality of fields, but it is largely complete for an API detail tool.

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

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

The schema only defines loan_ids as an array of strings with 0% description coverage. The description explains it should be passed as an array with limits 1-50 and that it drives batch behavior. This fully compensates for the 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?

The description clearly states the tool returns full loan contract detail by ID, listing many specific fields. It also explicitly distinguishes itself from the sibling tool openfinance_list_loans by advising 'Use after openfinance_list_loans', making the purpose and scope unambiguous.

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

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

The description provides clear guidance: use after openfinance_list_loans for deep-diving. It specifies passing loan_ids as an array of 1-50 and notes the batch return shape. While it doesn't explicitly list when not to use or alternative tools, this is sufficient context for correct invocation.

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, idempotent, and non-destructive. The description adds critical behavioral details: the 'balance' meaning is connector-dependent, a 'provider_incident' block may indicate unreliable data, and the 'name' is the legal entity not the brand. These go 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 verbose but each sentence adds value. It is front-loaded with the main purpose and then details parameter behavior and caveats. Could be slightly tightened, but it's well-organized.

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 only 2 parameters, the description covers return structure, parameter usage, and important caveats (balance semantics, provider incidents, naming distinction). Cross-referencing a sibling tool for bills adds 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?

Input schema has 0% description coverage, but the description thoroughly explains both parameters: 'item' for filtering by bank or omitting for all, and 'type' for filtering by account type. It also clarifies that omitting 'item' aggregates all connections with each row tagged by its own bank/connector_id.

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, listing specific fields (balance, number, type, etc.) and distinguishes between BANK and CREDIT types. It also differentiates from siblings like openfinance_list_credit_card_bills by noting that tool provides standardized billing amounts.

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

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

Explicit guidance is given: omit 'item' to list across all banks (for 'my accounts/cards' queries), pass 'item' for a single bank. It warns against treating 'balance' as the bill amount and directs to openfinance_list_credit_card_bills for standardized open-bill amounts.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds useful behavioral details: caching for the session, single aggregated response, and no batch IDs, which go 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 that front-load the primary action and include all necessary details 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?

Despite no output schema, the description fully explains the return format, including field purposes and usage hints, making the tool's behavior completely understandable.

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

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

With no parameters, the description fully compensates by explaining the output structure and field meanings in detail, which is essential given the empty 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 'Pluggy's transaction category taxonomy' with specific details about the data fields. It distinguishes itself from sibling tools by mentioning its use in openfinance_update_transaction_category and the caching behavior.

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 usage context by linking to the category update tool and advising preference for descriptionTranslated for pt-BR users. However, it lacks explicit when-not-to-use instructions or alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to reiterate safety. The description adds value by specifying the returned fields (including add_connection_url), which is beyond what annotations provide.

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

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

The description is a single sentence, front-loaded with 'Returns the saved bank connections,' and every word adds value. No wasted text.

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), the description is sufficiently complete. It clearly states what is returned, though it omits details like whether the list is paginated or the data type of each field. However, these are minor 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 the schema description coverage is 100%. According to guidelines, baseline is 4, and no additional parameter info is needed.

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 saved bank connections and lists specific fields (connector_id, item_id, bank name, add_connection_url). It is a specific verb+resource combination. However, it does not explicitly differentiate from sibling list tools like openfinance_list_accounts or openfinance_list_transactions, which could be improved.

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

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

No guidance is provided on when to use this tool versus alternatives. While it is a simple read operation, the lack of any usage context or exclusions means the agent must infer usage solely from the name and description.

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 substantial behavioral context: how payments are attributed based on cycle, derivation of payment_status, open_bill derivation from pending transactions, connector asymmetry leading to unavailability, bill grouping reliability warnings, and the tool returning a warning instead of failing when product not enabled. No contradiction with annotations.

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

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

The description is front-loaded with main result fields and structured with bolded sections (IMPORTANT, CONNECTOR ASYMMETRY). While comprehensive, it is lengthy and includes some redundancy (e.g., repeating that open_bill is opt-in). For an agent, all information is relevant, but conciseness could be improved.

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 high complexity (Brazilian Open Finance semantics, derived fields, connector asymmetry, no output schema). The description covers all major aspects: return fields, payment attribution, payment_status derivation, open_bill structure, connector limitations, and fallback behavior. It also addresses edge cases like missing open bill and product not enabled. Very complete for the given complexity.

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

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

Schema description coverage is 0%, so description must explain all parameters. It thoroughly explains include_open_bill and mentions account_id/account_ids in context of echo and bulk support. However, page and page_size are not explained; their purpose is only implied by 'Bulk support' and common pagination patterns. This gap reduces the score despite good coverage of other 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 closed credit card bills for CREDIT-type accounts, listing specific fields. It distinguishes from sibling tools by mentioning openfinance_list_transactions for itemized charges and implying openfinance_get_credit_card_bill is for a single bill. The verb 'list' combined with resource 'credit card bills' is specific and unambiguous.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It warns against calling a bill 'vencida' categorically, advises cross-checking account echo when multiple banks are connected, and directs users to openfinance_list_transactions for itemized transactions. It also explains when include_open_bill should be used and its performance implications.

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

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

Annotations already indicate readOnly and idempotent; description adds specific error handling behavior (returns warning object instead of throwing on 403) and lists returned fields, adding 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?

Single paragraph with clear start on purpose, followed by details; efficient but could be more structured with parameter explanations.

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 return format and error handling well, but lacks details on pagination and filtering via parameters, which are needed for full context.

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

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

Schema description coverage is 0%; the description fails to explain any of the four parameters (item, page, type, page_size), offering no guidance on their meaning or usage.

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 investment portfolio for a connection, lists types (FIIs, stocks, ETFs, etc.) and fields returned, distinguishing it from transaction listing tools implicitly.

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?

Mentions that it requires a connection with INVESTMENTS product enabled, but does not explicitly differentiate from sibling tools 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by detailing return fields (expenses breakdown, agreedRate, brokerageNumber) and bulk capability. 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 concise paragraphs, front-loaded with action and types, no fluff. Well-structured.

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

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

No output schema, description lists returned fields (quantity, value, amount, netAmount, agreedRate, brokerageNumber, expenses). Mentions prerequisite of investment_id from list_investments. Complete for the tool's purpose.

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 0% so description must compensate. Describes investment_id and hints at investment_ids, but does not explain page and page_size parameters. Adds some meaning but not fully comprehensive.

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

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

The description clearly states the tool returns movement history for a specific investment position, listing transaction types (BUY, SELL, TAX, INTEREST, AMORTIZATION, TRANSFER) and specific fields returned. It distinguishes itself from sibling tools like openfinance_list_investments (which lists investments) and openfinance_list_transactions (general transactions).

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

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

Explicitly recommends using after openfinance_list_investments to obtain investment_id. Mentions bulk support via investment_ids. Does not provide when-not-to-use or alternative tools, 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 cover read-only and idempotent nature. Description adds critical behavior: sequential querying with rate-limit spacing and per-connection `{ results, errors }` return structure. 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 efficiently deliver purpose, parameter usage, and behavioral nuances. Front-loaded with main action. No unnecessary words.

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

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

Complete for a read-only list tool: covers filtering, multi-connection handling, rate limiting, and response format. Lacks output schema but compensates by describing the structure.

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, description thoroughly explains the `items` parameter: allowed types (item_id uuid, connector_id, or connector_name) and the effect of omission (list all). Adds significant 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?

Clearly states it lists loan contracts per bank connection with the endpoint path. Distinguishes from financial data siblings (accounts, transactions) by specifying 'loan contracts'.

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 concrete guidance on when to use: pass `items` for specific connections or omit for all. Implicitly contrasts with other list tools by focusing on loans, but lacks explicit when-not-to-use instructions.

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, and the description aligns without contradiction. It adds rich behavioral context: credit card pending/posted variation, sparse billId population, upstream error handling, truncation at 5000, and provider incident block. No annotation 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 lengthy but well-structured with clear sections. Every sentence adds value, but some redundancy (e.g., repeating billId warnings) could be trimmed. Overall efficient for the 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?

Despite no output schema, the description explains the response structure: account echo block, transactions array, warning/error, truncated flag, detail fields, and provider_incident block. It also advises on diagnostics (connection health, force sync). Extremely 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 schema description coverage at 0%, the description fully compensates by explaining from/to as ISO dates, search_queries with OR semantics, detail levels (compact/rich/raw) with behaviors, page and page_size pagination, and account_ids for bulk. All parameters are meaningfully described beyond the schema.

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

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

The description clearly states it returns transactions for BANK or CREDIT accounts, and distinguishes itself from sibling tools like openfinance_list_credit_card_bills and openfinance_list_accounts. It specifies that for CREDIT accounts it is the only way to get itemized transactions, making the purpose precise and unique.

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

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

The description provides explicit when-to-use and when-not-to-use guidance. It warns against reconstructing bill totals from transactions, recommends openfinance_list_credit_card_bills for standardized totals, explains pagination modes (omit page vs explicit page), and advises checking connection health if total is 0. It also covers provider incidents and cross-checking account echo.

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 crucial behavioral details: truncation at 5000 transactions per account (flags `truncated:true`), internal fan-out of accounts, provider_incident block that may cause incomplete/wrong data, and the default compact output format. No contradictions with annotations.

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

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

The description is a single dense paragraph but front-loads the main purpose. It contains valuable information, but could be more structured with bullet points or shorter sentences for easier scanning. No redundancy, but length reduces conciseness slightly.

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 7 parameters, no output schema, and no nested objects, the description is remarkably complete. It explains the return fields (entradas, saídas, saldo_liquido, por_mes, top_despesas, top_recebimentos, by_account), truncation behavior, provider incident handling, and parameter interactions. An agent has sufficient information to select and invoke the tool correctly.

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

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

The input schema has 7 parameters with no descriptions (0% coverage). The description compensates fully: explains `item` (connector_id, connector_name, item_id, or omit for all), `from`/`to` as ISO dates, `granularity` (monthly vs raw with output differences), `detail` (compact/rich/raw with specific enrichments), `type` (BANK/CREDIT), and `top_n` implicitly via 'largest N each'. This adds substantial meaning beyond the raw schema.

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

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

The description clearly states the tool's purpose as 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It distinguishes itself from siblings like openfinance_list_accounts and openfinance_list_transactions by explicitly mentioning that users do not need to call those first. The verb 'analyze' and resource 'transactions' are specific and unambiguous.

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

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

The description provides explicit usage scenarios: 'for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'.' It explains when to use different granularities and details, and warns about provider_incident affecting results. It also tells users they can omit `item` to analyze all linked banks, and mentions alternatives like calling openfinance_list_accounts first (not 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. Description adds behavioral details: returns global indicator, degraded components, open incidents, and flags affected banks. 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 a single dense paragraph that front-loads purpose and key usage. Every sentence provides necessary information with no 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?

Despite no output schema, description fully explains what the tool returns (global indicator, components, incidents, affected banks) and provides sufficient context for effective use.

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

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

No parameters; schema coverage is 100% trivially. Description doesn't need to add param info. Baseline for zero params is 4, and no additional value beyond schema is needed.

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 checks the LIVE operational status of the Open Finance provider, distinguishes from the sibling tool openfinance_get_item_status, and specifies the verb 'Checks' with a clear resource.

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

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

Explicitly describes when to use (when data looks incomplete/stale despite connection showing UPDATED) and what it reveals (upstream outage/incident). Does not explicitly exclude other scenarios, 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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: that it honors the user's plan, returns a ready connect_url, and surfaces caveats for non-Open-Finance connectors. 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 of moderate length. Every sentence adds value, but it could be more structured (e.g., bullet points). Nonetheless, it is efficient and front-loaded with the core function.

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

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

Despite no output schema, the description comprehensively explains return values (connector id, access, audience, linked connections, connect_url). It also covers plan filtering and caveat handling. This sufficiently equips an agent to select and invoke the tool correctly.

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

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

With 0% schema description coverage, the description compensates fully. It explains the use of keywords[] with examples, that include_accounts adds account details, and that keywords is effectively required (though schema doesn't mark it). This adds meaning beyond the raw schema.

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

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

The description uses a specific verb ('Searches') and resource ('available bank connectors'), and details what is returned per match (connector id, access type, audience, linked connections, connect_url). This clearly distinguishes it 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?

Explicitly states when to call the tool ('Call this BEFORE connecting') and that keywords[] is required (without it returns a hint). While it does not explicitly mention when not to use it or alternatives, 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 provide no safety hints (readOnlyHint false, destructiveHint false). The description adds critical behavioral details: the tool is a write operation that teaches Pluggy by creating category rules, and describes batch error handling and return 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 a single focused paragraph with no redundant sentences. Every sentence contributes uniquely to purpose, usage, behavior, or output, making it information-dense yet clear.

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

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

Given no output schema, the description fully covers return shape. The tool has moderate complexity (batch processing, side effects), and the description addresses all aspects: input semantics, behavioral consequences, and error handling.

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

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

Schema coverage is 0%, so the description carries full burden. It clearly explains the items array structure, identifies the required fields (transaction_id, category_id), and tells where to source each ID from other tools, adding essential context 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 explicitly states the tool corrects transaction categories via PATCH, and distinguishes itself from sibling tools by referencing where to obtain required IDs (openfinance_list_transactions, openfinance_list_categories).

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

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

The description explains when to use (fixing miscategorized transactions) and notes side effects (creates category rules). It provides clear sourcing for parameters but does not explicitly state 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 indicate idempotentHint=true (safe to retry) and destructiveHint=false. The description adds that the conversation array is needed for reproduction, which is useful behavioral context. However, it does not disclose what happens after reporting (e.g., ticket creation, email). With annotations covering safety, a 3 is appropriate.

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

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

The description is very concise: two sentences that front-load the purpose and then provide a usage hint. Every sentence adds value with no wasted words.

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

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

For a simple feedback tool with no output schema, the description covers the essential purpose and one key parameter (conversation). It does not describe return values or success behavior, but for a non-critical tool this is acceptable. The contextual completeness is good but not exhaustive.

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 3 parameters (message required, context and conversation optional) with 0% description coverage in the schema, so the description must compensate. It explains that 'conversation' should be an array of recent messages, adding meaning beyond the schema's string type. However, it does not explain the 'context' parameter or the format of the conversation array, so some gaps remain. Baseline 3 is suitable.

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

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

The description clearly states the tool's purpose: reporting a bug, missing feature, or sending feedback. It uses specific verbs and resources, and the mention of 'conversation array' for reproduction adds specificity. The tool is distinct from its siblings, which are all related to 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 provides a clear usage hint: 'Include the conversation array with recent messages for reproduction.' This tells the agent when and how to use the tool effectively. However, it does not explicitly state when not to use it or provide alternatives, but given the sibling tools are unrelated, no exclusion is 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=true, idempotentHint=true, and destructiveHint=false. The description adds the specific output (platform and adapter versions) but no further behavioral details. This is adequate given the annotations.

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

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

Single sentence, no filler, perfectly sized for the tool's simplicity.

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, rich annotations, and straightforward purpose, the description is fully complete. No output schema needed for such a simple return.

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 the description inherently adds no parameter info. With 0 parameters, baseline score is 4 per rubric.

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 'show' and resource 'versions', specifying both MCP platform and adapter versions. It is distinct 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 tool is self-explanatory with no parameters and a simple read operation. No explicit when-not-to-use guidance is needed, though it could be slightly more explicit about being informational.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the returned state (installed MCPs, connection status, catalog counts). No contradictions; the description complements annotations well.

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 front-loaded with the main purpose and includes key details without extraneous information. Every word earns its place.

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

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

The tool has no parameters and no output schema, so the description is the sole source of context. It describes what is returned (installed MCPs, connection status, catalog counts) but does not detail the structure or format of the output. For a status tool, this is adequate but could be more complete.

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

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

There are no parameters, so schema coverage is 100% trivially. The description adds no parameter info, which is acceptable since none exist. Baseline 4 for 0 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 the tool returns current toolkit state, specifying 'installed MCPs, their connection status, and how many catalog tools each exposes.' This is a specific verb+resource that distinguishes it from sibling tools like authenticate or marketplace.

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 checking toolkit status but provides no explicit guidance on when to use this tool versus alternatives or any prerequisites. No exclusions or alternative suggestions are given.

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