Ágora MCP

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description aligns with these, explaining that no-arg calls return a link (non-destructive) and token-based calls perform authentication. It adds context about session vs permanent setup, which helps the agent understand behavior 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 no wasted words. It is front-loaded with the tool's target audience and core action, and each sentence adds value by clarifying usage, options, or best practices.

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 simple schema and no output schema, the description covers the two main use cases (with and without token) and provides best-practice guidance. It could be improved by noting potential error states, but overall it is sufficiently complete for the tool's complexity.

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

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

The input schema has 0% description coverage, but the description compensates by explaining the 'token' parameter (a JWT access token) and the effect of omitting it. This adds essential meaning that the schema alone does not provide.

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 an IDE agent by either providing an access token or obtaining a login link. It distinguishes from sibling tools by focusing specifically on 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 explicit guidance on when and how to use the tool, including two modes (with token for session login, without token to get link) and a best practice for permanent setup. It does not explicitly exclude scenarios, 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds value by detailing response content in two conditions (authenticated:true and empty pending[] vs connect_url). No contradiction.

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

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

Two sentences, front-loaded with purpose, no extraneous words. Efficiently communicates 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?

For a parameterless tool with output schema absent and annotations complete, description sufficiently covers behavior and response scenarios.

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% with empty properties. Baseline score of 4 for 0 parameters is appropriate; description adds no param info because none exist.

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

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

Description clearly states the tool returns connection status and URLs. It specifies the verb 'Returns' and the resource, distinguishing it from sibling tools like 'authenticate' or 'openfinance_provider_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?

Description explains when to use (check connection status) and describes different scenarios (all connected vs missing credentials). It doesn't explicitly exclude alternatives, but context from sibling tools makes the purpose 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?

Beyond annotations (which indicate non-read-only, open world, non-idempotent, non-destructive), the description adds critical behavioral context: invoke runs MCPs even if not installed, returns connect/checkout links for credentials/payment, and explains that writes require workspace owner/admin. This significantly enhances transparency.

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

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

The description is lengthy (around 700 characters) and contains a lot of information. While it is well-organized with separate points for core flow, invoke specifics, and other actions, it could be more concise. Some redundancy exists (e.g., mentioning that invoke works without installation twice).

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 (15 params, no schema descriptions, no output schema), the description covers the main workflow, edge cases (missing credentials, payment), and permissions. It lacks detail on return values for each action, but overall it is quite comprehensive for such a multifaceted tool.

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

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

The input schema has 0% description coverage for 15 parameters. The description explains key parameters like action, query, mcp_id, tool_id, and arguments within the context of the core flow (e.g., action=search, action=describe, action=invoke). It does not detail all parameters (e.g., limit, message, tier_slug), but the essential ones are semantically clarified.

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 as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It clearly distinguishes itself from sibling tools by instructing to use this tool first before any external registry, and it details the core flow of search, describe, and invoke actions.

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

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

The description provides explicit when-to-use guidance: 'use THIS tool FIRST' for capability queries, prefer invoke over install for single use, and use install for permanent addition. It also mentions that writes require owner/admin permissions. This clearly differentiates from sibling tools.

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

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

The description adds context beyond the destructiveHint annotation by stating data will no longer be available and that a reconnection URL is returned. This provides useful behavioral insight for the agent.

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 primary action, followed by consequences and return value. 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 destructive tool with one parameter and no output schema, the description covers the key points: action, effect on data, and reconnection capability. Minor lack is not explaining the 'item' parameter, but overall complete enough.

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 sole parameter 'item' has no description or meaning provided. With 0% schema coverage, the description fails to clarify what 'item' represents (e.g., bank connection ID), leaving the agent without crucial context.

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

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

The description clearly states the tool revokes Open Finance consent and deletes connection data for a specific bank, with a return value for reconnection. The verb 'revokes' and 'deletes' are specific, and it distinguishes from sibling tools like openfinance_list_connections or openfinance_force_sync.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., using list_connections first to identify the bank). No prerequisites or when-not-to-use conditions are indicated.

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 detailed behavior: polls up to ~60s, returns status fields, handles errors like needs_action and timed_out, and emphasizes that it pulls fresh data without disconnecting. Annotations are minimal but consistent; 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 front-loaded with the core action and use case, then details parameters and returns. While verbose, every sentence serves a purpose, though minor trimming could improve conciseness.

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

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

Given no output schema and minimal schema descriptions, the description fully covers purpose, parameters, return format, error states, and next steps. It is complete for effective tool 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?

Adds essential meaning: explains that items can be item_id, connector_id, or connector_name, that omitting items syncs all banks, and that wait=false triggers fire-and-forget. This fully compensates for the 0% schema description coverage.

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

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

The description clearly states that it forces a bank to re-sync connections and waits for completion. It specifies the action (force sync), resource (connections), and distinguishes from siblings like openfinance_get_item_status by mentioning polling and timeout.

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

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

Explicitly tells when to use ('when a balance or transaction list looks stale') and provides alternatives such as setting wait=false for fire-and-forget. Also advises re-checking with openfinance_get_item_status if timed out.

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 warning behavior for CREDIT accounts, degradation to last-synced balance with realtime:false, and response shape. Adds value beyond readOnlyHint and idempotentHint annotations.

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

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

5 sentences, front-loaded with core purpose, each sentence adds distinct value. 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?

Covers edge cases, warnings, degradation, and response shape. Complete for a single-parameter read tool with no output schema.

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

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

Adds array range (1-50) to the undocumented schema parameter. Could further clarify item format (e.g., UUID format).

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

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

Description states specific verb ('returns'), resource ('real-time balance payload per account id'), and endpoint. Distinguishes from siblings like openfinance_list_accounts and openfinance_get_accounts_detail.

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

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

Specifies parameter range (1-50) and cases for CREDIT accounts and degradation. Lacks explicit when-not-to-use or alternatives, but 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 declare readOnlyHint and destructiveHint. The description adds critical context: a provider_incident block may appear, making credit limits and balances unreliable. This goes beyond annotations.

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

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

Four sentences, front-loaded with purpose and input requirements. Every sentence adds value, warning about provider incidents is concise yet critical.

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 input, output shape, edge cases (incident block), and safety profile via annotations. Complete for agent use.

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

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

Input schema has one parameter with 0% coverage, so description carries full burden. It specifies the parameter is an array of strings, size 1-50, and the batch shape, adding essential semantics.

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

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

The description clearly states it returns full account objects with extended creditData per account ID. It distinguishes from sibling tools like openfinance_list_accounts (list without details) and openfinance_get_account_balance (only balance).

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 pass account_ids as an array of 1-50, and describes the batch shape {results, errors}. While it doesn't state when not to use it, the context is clear and effective.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds critical behavioral context: batch shape {results, errors}, Pluggy connector does not return a paid/status field, and payments[] typically reflect the previous bill's payment during this billing cycle, so a non-empty payments array does not mean this bill was paid. These details are essential for correct invocation and interpretation.

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

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

The description is relatively long but well-structured: it starts with the core purpose, then lists what is NOT included, then provides usage guidance and important caveats. Each sentence adds value, though some consolidation could make it more concise without losing critical information. The use of notes and calls to sibling tools is effective.

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

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

Given the lack of output schema, the description thoroughly explains what the tool returns: financeCharges and payments with subfields, the batch shape, and the authoritative totalAmount. It also covers connector-specific behavior (Pluggy status field absence) and the semantics of payments[]. This provides sufficient context for an agent to use the tool correctly without seeing an output schema.

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

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

Schema coverage is 0%, so the description must compensate. It explains that bill_ids comes from the list endpoint and should be an array. However, it doesn't provide examples, constraints on ID format, or clarify whether the array can be empty or have duplicates. While the guidance is helpful, it doesn't fully elaborate on parameter semantics beyond the schema's type and required flag.

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

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

The description clearly states that the tool returns bill-level detail for credit card bills by ID, listing specific fields (financeCharges, payments[]). It explicitly distinguishes itself from siblings by stating what it does NOT return (individual transactions) and directing to openfinance_list_transactions for that purpose.

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

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

Provides explicit guidance: use openfinance_list_credit_card_bills first to discover IDs; for itemized transactions, use openfinance_list_transactions with date range; warns against reconstructing bill total from transactions; advises on checking paid status via the list endpoint. This clearly tells the agent when and how to use this tool vs 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. The description adds value by detailing the return information (status, executionStatus, connector metadata) and the dual behavior based on the `item` parameter.

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

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

The description is two sentences, front-loaded with the main purpose, and no unnecessary words. It is concise and well-structured.

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

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

Despite no output schema, the description covers the return format: status, executionStatus, connector metadata, and for all banks, { count, items }. This is sufficient for an agent to understand the output.

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

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

Schema coverage is 0%, but the description fully explains the `item` parameter: omitting it returns status for all banks, passing it returns status for a single bank. 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 that the tool returns the current status of a bank connection with specific statuses like UPDATED, UPDATING, and LOGIN_ERROR, and distinguishes between all banks or a single bank. This differentiates it from sibling tools like openfinance_list_connections.

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

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

The description explicitly explains when to omit or include the `item` parameter, providing clear usage context. It does not mention alternatives explicitly, but the context implies the tool is for status retrieval, not other actions.

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 detailing the batch behavior and the specific data returned, though it doesn't mention authentication or rate limits, which is acceptable given the annotations.

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

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

The description is concise, packing purpose, usage guidance, parameter details, and return structure into a single sentence. It is front-loaded and efficient, though the list of fields could be slightly more 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, the description thoroughly describes the return fields and batch shape. It covers all essential aspects for an agent to understand the tool's output and usage 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 has 0% description coverage, but the description compensates by explaining the parameter: 'Pass `loan_ids` as an array (1-50).' This adds size constraints and format beyond the schema's type definition.

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

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

The description clearly states the function: 'Returns full loan contract detail by id' and lists specific fields returned. It distinguishes itself from the sibling tool 'openfinance_list_loans' by indicating it is for deep-diving after 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?

Explicitly guides usage: 'Use after openfinance_list_loans to deep-dive on a specific contract.' It also specifies input format ('Pass `loan_ids` as an array (1-50)') and describes the batch output shape ('{ results, errors }').

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

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

Annotations already declare readOnlyHint and idempotentHint, so description adds value by warning about `provider_incident` blocks, unreliable balances during provider incidents, and the connector-dependent meaning of credit balance. 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 lengthy but well-structured, front-loading the main purpose. Most sentences add value, though some details could be streamlined. It is clear but not maximally 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?

For a listing tool with 2 params and no output schema, the description covers return fields, param usage, warnings about data interpretation, and incident handling. It is fairly complete but relies on the description to compensate for missing output schema.

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

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

With 0% schema description coverage, the description fully compensates by explaining `item` (omit for all, pass for single bank) and `type` (BANK or CREDIT with meaning). It adds semantic 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 clearly states the tool returns accounts for a bank connection, specifying types BANK and CREDIT and listing fields like balance, number, type, etc. It implicitly distinguishes from siblings like openfinance_get_accounts_detail by describing the function, but does not explicitly contrast with sibling tools.

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

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

Provides explicit when-to-use guidance: Omit `item` for all accounts, pass `item` for a single bank. Warns about connector-dependent `balance` and suggests using openfinance_list_credit_card_bills for standardized amounts. Clearly indicates when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's addition of caching, single aggregated response, and field details provides meaningful 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 three sentences, front-loaded with the core purpose, and each sentence adds specific value. There is no redundant or superfluous 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 absence of an output schema, the description fully describes the output structure (fields, types, and hierarchy). It also notes caching and the single-response nature, making it sufficient for an agent to understand what the tool does and what it returns.

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

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

With zero parameters and 100% schema coverage, the description is not required to document parameters. The baseline score for no parameters is 4, and the description adds no parameter information because none exist.

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

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

The description explicitly states the tool returns Pluggy's transaction category taxonomy via a GET /categories endpoint, with a clear verb and resource. It also distinguishes the tool from siblings by noting the cached nature and the specific fields returned.

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 by mentioning the id is used by openfinance_update_transaction_category, but it does not explicitly state when to use this tool versus alternatives or provide exclusions. Without clear guidance, the agent must 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?

Annotations already declare readOnlyHint and idempotentHint. Description adds context about returned fields and add_connection_url for linking additional banks, providing useful behavioral detail 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 sentence with no wasted words. Front-loaded with purpose, efficiently conveys what is returned and includes a key detail about add_connection_url.

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 parameterless list tool with no output schema. Description sufficiently covers return fields and includes the important add_connection_url, making it clear for agent 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?

No parameters; schema coverage is 100% vacuously. Baseline of 4 is appropriate as description doesn't need to explain parameters and adds no extra param info.

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 saved bank connections and lists specific fields (connector_id, item_id, bank name, add_connection_url). Distinguishes from siblings like openfinance_list_accounts which return account 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?

Implied usage: when agent needs to list existing bank connections. No explicit when-not-to-use or alternatives mentioned, but given no parameters, usage is straightforward.

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 extensively discloses behavioral traits beyond annotations, including derived payment_status logic, payment assignment across bills, connector asymmetry for open bills, data reliability warnings, and bank attribute consistency checks. Annotations already indicate read-only, idempotent, non-destructive behavior, which is consistent.

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 and contains valuable details but lacks concise structuring. It front-loads the core purpose but then rambles through multiple warnings and asides, which could be better organized or abbreviated.

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

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

Given the absence of an output schema, the description thoroughly details the return fields (dueDate, totalAmount, payments, payment_status, open_bill structure, future_bills) and covers edge cases, warnings, and reliability notes, making it complete for an agent to interpret results.

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

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

With 0% schema coverage, the description heavily compensates for include_open_bill, explaining its effect and use cases. However, pagination parameters (page, page_size) and account_ids for bulk execution are not explained, leaving gaps in parameter understanding.

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 it returns closed credit card bills for a CREDIT-type account, and explicitly differentiates from sibling tools like openfinance_list_transactions and openfinance_get_credit_card_bill by highlighting that this provides bill-level summaries and directing to other tools for itemized purchases.

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

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

The description provides explicit guidance on when to use this tool (for closed bills), when to use alternatives (openfinance_list_transactions for itemized purchases), and includes important caveats such as opt-in for open bill via include_open_bill, cross-bank bank naming, and avoiding aggregation pitfalls.

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

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

Description adds error handling behavior beyond annotations: returns a structured object with warning instead of throwing 403. Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. The description provides useful context on failure modes.

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 long sentence packed with details but lacks structure (e.g., bullet points). It is not overly verbose but could be more scannable.

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 listing return fields and error handling, the description omits parameter semantics entirely. With no output schema and 0% schema coverage, the tool definition is incomplete for an agent to correctly select and invoke it without additional 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?

The description provides no explanation for any of the four input parameters (item, page, type, page_size). With 0% schema description coverage, the description fails to add meaning to the 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 investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.) and fields returned. This distinguishes it from sibling tools like openfinance_list_accounts or 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 usage for viewing investment portfolio but does not explicitly state when to use this tool versus alternatives like openfinance_list_accounts or openfinance_list_investment_transactions. No guidance on prerequisites or 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?

Annotations (readOnlyHint, idempotentHint) already indicate safe read operation. Description adds value by detailing return fields like quantity, value, expenses breakdown, which goes beyond annotations.

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

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

Two sentences, front-loaded with main purpose, no fluff. The second sentence adds value by providing usage tip and bulk support.

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 gives good overview of return fields and transaction types. Missing pagination information despite page/page_size parameters.

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

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

Schema has 0% description coverage. Description only partially covers parameters: mentions investment_id and investment_ids, but omits page and page_size. This is a significant gap.

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

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

Description clearly states it returns movement history for a specific investment position, listing transaction types (BUY/SELL/etc.) and detailed fields. It distinguishes from sibling openfinance_list_investments by specifying 'Use after...'.

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 prerequisite (use after openfinance_list_investments to get investment_id) and mentions bulk support. Lacks explicit when-not or alternatives, 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 readOnly, idempotent, and non-destructive behavior. The description adds behavioral details such as sequential querying with rate-limit spacing and the return structure per connection, providing value beyond annotations.

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

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

The description is concise, front-loaded with the core purpose and endpoint, then efficiently covers parameter usage, behavior, and return structure. Every sentence adds value.

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

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

The description covers parameter behavior, sequential fetching, rate-limiting, and return structure (results/errors per connection). It does not mention pagination or specific data fields, but given the tool's simplicity and no output schema, it is adequately complete.

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

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

With 0% schema description coverage, the description fully compensates by explaining the `items` parameter: it accepts an array of connection selectors (item_id uuid, connector_id, or connector_name), sequential fetching with rate-limit spacing, and omission leads to listing across all banks. This is thorough and clear.

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

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

The description clearly states it lists loan contracts per bank connection and provides the HTTP endpoint. However, it does not explicitly differentiate from sibling tools like openfinance_list_accounts or openfinance_list_transactions, relying on context.

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

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

The description explains when to use the `items` parameter for specific connections and when to omit it for all connections, and mentions sequential querying with rate-limit spacing. It does not explicitly state when not to use this tool or provide 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses many behavioral traits: credit card transaction behavior varies by connector (pending vs posted), search_queries aggregates up to 5000 transactions, auto-pagination with a 5000 ceiling and truncation warning, error response structure on upstream failures, per-connector inconsistency of billId, and provider incident handling. This is far 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 long (10+ paragraphs) but well-structured: main purpose first, then credit card specifics, pagination, detail levels, error handling, and bulk support. Every section adds necessary information given the tool's complexity. However, it could be slightly more concise without losing value, so 4 rather than 5.

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 thoroughly explains the response: account echo block, total, results, warning, error, provider_incident block, truncation flag, and the effect of different detail levels (rich adds merchantInfo and extra fields). It also covers edge cases like zero results for credit accounts and connection health checks. No gaps remain.

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 no parameter descriptions (0% coverage), so the description must and does compensate. It explains each parameter: from/to as ISO date filters, page and page_size for pagination, detail as an enum with full semantics, search_queries as case- and accent-insensitive substring match with OR semantics, and account_ids for bulk support. This provides complete parameter understanding.

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 starts by clearly stating 'Returns transactions for a bank account (BANK or CREDIT type).' It specifies the exact resource (transactions) and the action (returns). It also distinguishes between account types and mentions that for CREDIT accounts this is the only way to get itemized transactions, which contrasts with 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?

The description provides extensive usage guidance: when to use this tool vs alternatives (e.g., for credit card bills use openfinance_list_credit_card_bills for totals), pagination strategies (omit page for auto-pagination, explicit for manual), detail levels ('compact' default, 'rich' for merchant info, 'raw' for full data), and when to check other tools for dates or connection health.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses important behaviors: scan caps at 5000/account with truncated flag, provider_incident block, and the fact that reconnecting doesn't fix incomplete data. This provides significant added value.

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 but somewhat lengthy. It front-loads the core benefit, then details parameters, use cases, and caveats. While every sentence is valuable, slight trimming could improve conciseness without losing information.

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

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

Given the tool's complexity (7 parameters, no output schema), the description covers all necessary aspects: output structure (compact vs raw summary), per-account breakdown, provider incident handling, and truncation. It is fully self-contained for an AI agent to understand usage and results.

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

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

Despite 0% schema description coverage, the description thoroughly explains each parameter: item (value types and omission behavior), from/to (ISO dates), granularity (default and effects), detail (options and enrichment), type (filtering), top_n (largest N). It adds critical context not in the schema.

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

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

The description clearly states it does consolidated cash-flow analysis for a whole connection in one call, resolving accounts internally. It distinguishes from sibling tools like openfinance_list_accounts and openfinance_list_transactions by explaining the convenience and consolidated nature.

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 use cases ('Use this for análise anual/mensal, fluxo de caixa...') and conditions for when to choose raw granularity. However, it does not directly name alternative sibling tools for comparison, though the context implies when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds valuable behavioral context: it checks a public status page, returns a global indicator, degraded components, open incidents, and flags incidents affecting the user's connected banks. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core action, then provides usage guidance and return value details. It is slightly long (4 sentences) but every sentence contributes meaning. Could be tightened slightly but remains effective.

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

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

Given no parameters and no output schema, the description is remarkably complete. It describes all key outputs: global indicator, degraded components, open incidents, and a list of affected banks. No additional information seems necessary for effective tool 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?

The tool has 0 parameters and schema coverage is 100%. With no parameters, the description does not need to explain them. A baseline of 4 is appropriate as there is nothing to add beyond what the schema already conveys.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, distinguishing it from the sibling tool `openfinance_get_item_status` which checks the user's own connection. The verb 'checks' and specific resource 'provider status' make the purpose precise.

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 advises when to use this tool: when data looks incomplete or stale despite an updated connection. It explains the tool can reveal upstream outages or incidents, helping differentiate provider-side problems from connection issues. This provides clear context and alternatives.

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

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

The description discloses behaviors beyond annotations: it honors the user's plan (PF hides PJ banks), keywords[] is required and without it returns a hint, and non-Open-Finance connectors carry a caveat. Annotations already declare readOnlyHint and idempotentHint, and the description adds valuable context 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?

The description is informative but slightly verbose. It is well-structured with a main purpose, details, and guidance. Could be tightened by removing redundant phrasing, but it remains clear and valuable.

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 explains return fields (connector id, access, audience, linked connections, accounts if include_accounts, connect_url) and notes the caveat. It covers all necessary information for the agent to use the tool effectively.

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

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

Despite 0% schema description coverage, the description adds significant meaning: keywords[] is REQUIRED (contrary to schema showing required:0), examples given, behavior without it explained; include_accounts boolean clarified with effect. This compensates fully for the schema gap.

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

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

The description clearly states the tool's purpose: searching available bank connectors by name. It specifies the verb 'searches' and the resource 'bank connectors', and distinguishes its role as a prerequisite before connecting, differentiating it from siblings like 'connect' and '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 explicitly advises to call this tool before connecting, providing clear context on when to use it. It also explains the caveat for non-Open-Finance connectors, guiding the agent to prefer Open Finance connectors. However, it does not explicitly state when not to use it or list alternatives.

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

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

Discloses that it overrides automatic categorization and teaches Pluggy by creating a Category Rule. Also details error handling (per-item errors don't fail full batch) and provides the response shape. 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?

Concise yet comprehensive; front-loaded with purpose, then usage, then behavioral details. 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 includes the response shape and error behavior. It covers parameters, side effects, and batch semantics, making it fully complete for the tool's complexity.

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

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

Despite 0% schema coverage, the description fully explains each parameter: transaction_id and category_id, their sources, and the required array structure. This compensates completely 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?

The description clearly states it corrects the category of one or more transactions with the HTTP method and resource. It distinguishes from sibling tools like listing transactions or accounts by specifying the action (corrects category) and the batch capability.

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 where to get the required IDs (transaction_id from openfinance_list_transactions, category_id from openfinance_list_categories) and notes the side effect of creating a Category Rule. It lacks an explicit 'do not use for' but the context is clear.

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

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

Annotations include idempotentHint=true and destructiveHint=false, so the description adds value by specifying the need to include conversation data. 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 sentence, efficiently stating the purpose and a key instruction. However, it could be slightly more structured to list parameters.

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, the description covers the main intent but lacks details on required and optional parameters, making it incomplete.

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

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

Schema coverage is 0%, but description only mentions the conversation parameter, ignoring the required 'message' and optional 'context'. This leaves the agent uncertain about what to provide for those 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's purpose: report a bug, missing feature, or send feedback. This is specific and distinct from sibling tools which are primarily financial operations.

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

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

The description advises to include the conversation array for reproduction, which provides clear guidance. No alternatives are mentioned, but siblings are unrelated so no confusion.

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 that the tool returns version information, which is consistent and provides the specific resource shown. Since annotations cover safety, no further behavioral details are necessary, and the description does not contradict them.

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

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

The description is a single, front-loaded sentence that conveys the entire purpose without unnecessary words. It is concise and effective, earning its place with no waste.

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

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

Given the tool's simplicity (no parameters, no output schema), the description is largely complete. However, it does not mention the return format (e.g., string or object), which could help an agent understand the output. This minor gap prevents a perfect score.

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, and schema description coverage is effectively 100%. According to guidelines, zero parameters warrant a baseline score of 4. The description does not need to add parameter information, and it does not; this 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 uses a specific verb ('Show') and explicitly names the resource ('current MCP platform and adapter versions'), clearly distinguishing the tool from sibling tools focused on authentication, connection management, and financial data retrieval. There is no ambiguity about the tool's sole purpose.

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

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

The description implies the tool is for checking version information, which is self-evident. While it does not explicitly state when to use or not use this tool, the context of sibling tools (none are version-related) makes the usage intuitive. A mention of using it before reporting issues would strengthen guidance, but it is not lacking.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about the specific content returned (MCPs, connection status, catalog tool counts), which goes beyond the annotation flags.

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, front-loaded with key information, 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?

Given no parameters and no output schema, the description adequately explains what the tool returns. Could optionally mention that results are static (snapshot) but not necessary. Completeness is high for a simple info tool.

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

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

No parameters exist in the schema, and schema description coverage is 100% (empty). According to guidelines, 0 params baseline is 4. Description doesn't need to add parameter info.

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 uses specific verb 'returns' and resource 'toolkit state' with explicit details (installed MCPs, connection status, catalog tool counts), clearly distinguishing it from sibling tools that focus on authentication, OpenFinance operations, etc.

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

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

No explicit guidance on when to use this tool versus alternatives. While it's implicitly the go-to for overview/state, the description lacks directives like 'Use when you need to inspect installed MCPs' or comparisons to siblings like 'show_version'.

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