Á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?

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds valuable behavioral details: invoke runs MCPs even if not installed, returns connect/checkout links when needed, and one-off installs occur behind invoke. It also mentions permission requirements for writes. These go beyond annotations, though some behaviors (e.g., idempotency) are not fully clarified.

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

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

The description is dense and covers many aspects, but it is a single block of text without structure (e.g., bullet points or sections). It is not overly long, but the run-on style reduces scanability. Every sentence adds value, so it is acceptable but not optimal.

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 and lack of output schema/param descriptions, the description covers the essential workflow, credential/payment handling, installation vs invocation, and permission notes. It omits return value details, but that is acceptable. The main gap is insufficient parameter documentation, which prevents full completeness.

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

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

With 13 parameters and 0% schema description coverage, the description must compensate heavily. While it explains the action enum and the high-level flow, many parameters (limit, query, mcp_id, tool_id, arguments, immediate, etc.) lack any explanation of their format, purpose, or constraints. This leaves agents guessing about how to fill them properly.

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 defines the tool as the official marketplace for discovering, describing, and running MCPs/tools. It specifies the core workflow (search → describe → invoke) and distinguishes it from external registries, making the purpose unmistakable.

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 first for capability discovery, contrasts invoke vs install for one-off vs permanent use, lists sibling actions (list_tools, subscribe, etc.), and notes that writes require owner/admin. This fully equips an agent to decide when to use it.

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

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

The description 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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. Description adds real-time nature, GET method, array size limit, structured error handling for credit accounts, and response shape. Adds significant context beyond annotations.

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

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

Three sentences, no fluff. First sentence states purpose and endpoint, second gives parameter instruction, third details error handling and response shape. Front-loaded and efficient.

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

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

For a simple balance retrieval tool with one parameter and no output schema, the description covers purpose, parameter constraint, error behavior, and response structure. Nothing essential missing.

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 explains 'account_ids' is an array of strings, must be passed as array, and limited to 1–50. This adds crucial 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?

Description clearly states it returns real-time balance per account id and specifies the HTTP endpoint. However, it does not explicitly differentiate from siblings like 'openfinance_get_accounts_detail', though the resource (balance vs detail) is implied.

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: use when you need balances for specific account ids. Provides constraint (array 1–50) and error handling note but no explicit when-to-use or when-not-to-use guidance compared to 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 read-only, idempotent, non-destructive. Description adds batch result shape and creditData inclusion, but no extra behavioral details like rate limits.

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

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

Two sentences, front-loaded with purpose, no superfluous text. Efficiently conveys key information.

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

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

Covers batch return shape, differentiator of extended creditData, and parameter constraints. Lacks detail on error handling for invalid ids, but overall adequate for simple tool.

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

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

Schema coverage is 0%, but description adds valid type (array of strings) and range (1-50) for account_ids, providing valuable constraint 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 returns full account objects with extended creditData per id, differentiating from list_accounts. Includes HTTP path and batch 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?

Specifies valid array size (1-50) but does not explicitly state when to use vs siblings like list_accounts or get_account_balance.

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

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

The description goes beyond the annotations (readOnlyHint=true, destructiveHint=false) by explaining the batch return shape, the absence of a paid/status field in Pluggy, and the nuanced meaning of payments[] (previous bill's payment, not current bill's status). This provides significant behavioral context that the annotations alone do not convey.

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

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

The description is longer than average but all sentences add value, covering purpose, return data, caveats, and usage advice. It is front-loaded with the key purpose and logically structured. Some slight redundancy (e.g., mentioning the endpoint twice) could be trimmed, but overall it is well-organized and 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?

Given the tool has no output schema, the description fully explains the return shape (financeCharges, payments[] fields, batch format) and links to sibling tools for transaction details and paid status. It covers prerequisites (bill_ids discovery), limitations (no paid field), and behavioral nuances, making it complete for an agent to use correctly.

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

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

Even though the input schema has 0% description coverage, the description fully compensates by explaining the single parameter 'bill_ids' as an array, telling users how to obtain the IDs (via openfinance_list_credit_card_bills), and clarifying the expected format. This adds all necessary meaning beyond the schema's type information.

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

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

The description clearly states it returns bill-level detail for credit card bills by ID, and explicitly distinguishes itself from sibling tools by stating it does NOT return individual transactions, directing users to openfinance_list_transactions. The specific listing of returned data and the mention of the endpoint format make the purpose unambiguous.

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

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

The description provides extensive guidance: it tells when to use (to get bill detail), when not to use (for transactions), and explicitly names the alternative tool (openfinance_list_transactions). It also advises to first use openfinance_list_credit_card_bills to discover IDs, and includes a critical caveat about the paid status interpretation via payments[], preventing incorrect assumptions.

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 behavioral details: credit card balance meaning varies by connector, and the response includes aggregation logic. It does not contradict annotations. While comprehensive, it could mention rate limits or idempotency guarantees, but overall adds significant 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 somewhat lengthy due to necessary nuance, but well-structured with front-loaded main purpose followed by specifics. Each sentence earns its place, though brevity could be improved slightly without losing clarity.

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

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

Given the complexity of account types, connector dependencies, and aggregation across items, the description is thorough. It covers return fields, naming conventions, usage modes, credit balance caveats, and cross-references a sibling tool for standardized data. No output schema exists, but the description adequately describes the response 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?

Schema description coverage is 0%, so the description must compensate. It explains the 'item' parameter's effect (omit for all, pass for specific) and implies the 'type' parameter filters by account type. Although 'type' is not explicitly described as a filter, the context clarifies it. The description adds meaning beyond the schema, but could be more explicit about 'type'.

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 accounts for a bank connection, distinguishes between BANK and CREDIT types, lists key fields, and explains how to list all accounts vs. targeting a single bank. It also clarifies the difference between account name and bank brand, making the purpose 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 explicitly tells when to omit 'item' (list all linked banks) and when to pass 'item' (single bank). It warns that CREDIT balance is connector-dependent and should not be misinterpreted, and directs users to 'openfinance_list_credit_card_bills' for standardized amounts. This provides clear when-to-use and alternative guidance.

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

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

Annotations already 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?

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds significant behavioral detail: payment cycle logic, derived statuses, connector limitations, and non-failure on missing product. 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?

Long but well-organized with uppercase section headers. Front-loads main purpose. Some redundancy but all info valuable. Could be slightly more concise without losing clarity.

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

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

Thorough coverage of complex behavior: derived payment_status logic, open bill opt-in, connector asymmetry, cross-bill payment matching, and reference to other tools. No output schema but description details return fields.

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 explains all key parameters: account_id, account_ids for bulk, include_open_bill for opt-in, and pagination. Missing explicit format/constraints but adequate for schema-free case.

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 a CREDIT-type account, listing specific fields. It distinguishes from siblings like openfinance_get_credit_card_bill and openfinance_list_transactions.

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

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

Provides explicit usage context: explains payment semantics, derived payment_status, opt-in for open bill, connector asymmetry, and directs to other tools for itemized data. Includes warnings 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?

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?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint. The description adds behavioral details: PENDING vs POSTED varies by connector, error handling returns warning/error instead of throwing, detail levels affect payload and token usage, bulk support, and upstream error behavior. 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?

Very long but well-structured with front-loaded purpose and clear paragraph breaks. Some details (e.g., extensive explanation of detail levels) could be more concise, but most information is necessary. The description earns its length.

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

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

No output schema exists, so description must explain return values and behavior. It covers: error return format, truncated flag, detail level data, creditCardMetadata fields (billId, purchaseDate, etc.), and interactions with other tools. Highly complete for a complex 8-parameter 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. The description explains all 8 parameters in detail: account_id (required), account_ids (bulk), from/to (ISO dates), page/page_size (max 500), search_queries (case-insensitive, OR, aggregation up to 5000), detail (enum with behavior of each option). Also explains edge cases like zero results check.

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

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

The description clearly states the tool returns transactions for bank accounts (BANK or CREDIT) and distinguishes it from sibling tools like openfinance_list_credit_card_bills and openfinance_get_account_balance. Specific verb 'Returns transactions' and resource 'bank account' are clearly identified.

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

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

Extensive guidance provided: for CREDIT accounts, it's the only way to get itemized transactions; when to use alternative tools (openfinance_list_credit_card_bills for totals, openfinance_list_accounts for dates, openfinance_get_item_status for health); advice on narrowing date ranges if truncated:true; and handling of zero results for CREDIT accounts.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral details beyond these annotations, such as the internal resolution of accounts, the scanning cap of 5000 transactions per account with a 'truncated:true' flag, and the different behaviors of 'granularity' and 'detail' options. No contradictions with annotations are present.

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 fairly long but front-loads the core purpose and usage. Every sentence provides useful information, though it could be tightened slightly (e.g., combining the granularity and detail explanations). It is well-structured and avoids redundancy, earning a high score for value per sentence.

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, no param descriptions in schema), the description covers most necessary information: parameter roles, defaults, behavior of granularity and detail, filtering, truncation limits, and use cases. It does not explicitly describe the output structure, but since there is no output schema, this is acceptable. The description is comprehensive for its 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%, so the description must compensate for parameter meaning. It does so by explaining most parameters: 'item' (connector_id, connector_name or item_id), 'from'/'to' (ISO dates), 'granularity' (monthly vs raw), 'detail' (compact, rich, raw), and 'type' (BANK or CREDIT). However, 'top_n' is mentioned implicitly ('largest N each') but not explicitly linked to the parameter, causing slight ambiguity. Overall, it adds significant meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It explicitly distinguishes from siblings by noting that users do not need to call openfinance_list_accounts first, and it contrasts with other tools in the sibling list (e.g., openfinance_list_transactions). The verb 'analyze' and resource 'connection transactions' are specific.

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

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

The description provides clear context for when to use the tool, listing example use cases in Portuguese ('análise anual/mensal', 'fluxo de caixa', etc.). It explains that for raw itemized rows, set granularity to 'raw', and for richer details, use 'detail' options. However, it does not explicitly mention when not to use this tool or directly compare with alternative siblings, though it implies differentiation from a simple list transactions 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses mandatory keywords, plan-based filtering (PF vs PJ), and the specific return fields including connect_url. It also states the tool never dumps the entire catalog, which is a key behavioral constraint.

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 efficient and front-loaded, with each sentence adding value. It is not overly verbose, though the parenthetical example could be seen as slightly cluttered. Still, it earns a 4.

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

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

Given the absence of an output schema, the description thoroughly explains the return values (id, access, audience, linked connections, accounts conditionally, and connect_url) and key behaviors (missing keywords, plan filtering). This makes the tool self-contained 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?

With 0% schema description coverage, the description compensates well: it explains that keywords[] is required and returns a hint if missing, and clarifies the effect of include_accounts=true. However, it could add details like case sensitivity or formatting of keywords.

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

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

The description clearly states that the tool searches bank connectors by name, and distinguishes itself from siblings by explicitly saying it never dumps the whole catalog and provides a one-click connect URL. The verb 'Searches' plus the resource 'bank connectors' is specific and actionable.

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 calling this before connecting to get a one-click link, and notes that keywords[] is required (otherwise returns a hint). It implicitly distinguishes from listing all connectors, but does not explicitly name alternatives or state when not to use it. A clear exclusion would elevate to 5.

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

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

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.