Sicoob MCP

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

Annotations indicate idempotentHint=true, which aligns with the description's mention of non-destructive authentication. The description adds context beyond annotations by explaining the two operational modes (permanent vs session) and that calling without args returns a login link. No contradictions, but could mention security considerations.

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 long, with no redundant words. It front-loads the core purpose and then efficiently provides alternative usage instructions. Every sentence earns its place.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete. It covers both intended workflows (config-based and session-based) and the expected inputs/outputs, leaving no ambiguity for an AI agent.

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

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

Despite 0% schema description coverage, the description compensates by explaining what the 'token' parameter expects (a JWT string) and the behavior when omitted (returns login link). It adds essential meaning beyond the schema's bare 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 tool's purpose: handling authentication for MCP.AI IDE agents. It specifies two distinct methods (config-based permanent token or session-based token paste) and distinguishes itself from sibling tools (e.g., connect, marketplace) by focusing exclusively 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 clear guidance on when to use each method: best practice (config for permanent) vs session-only (paste token). It also explains how to call the tool (with token or without) to get the link. However, it does not explicitly state when not to use this tool, though siblings are sufficiently distinct.

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

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

Annotations already declare readonly, idempotent, non-destructive. Description adds context about response format in different states, providing additional behavioral transparency beyond annotations.

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

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

Two concise sentences, no wasted words. Front-loaded with main purpose, then detail on scenarios.

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 status tool with no output schema, the description sufficiently explains the return values for both success and missing credentials cases. Could mention structure of URLs, but overall adequate.

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, so baseline 4 applies. Description does not need to add parameter details, and it correctly focuses on behavior.

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 connection status and URLs, with specific scenarios for when providers are connected or credentials missing. However, it doesn't explicitly differentiate from sibling tools like 'authenticate' or '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?

Implied usage for checking connection status, but no explicit guidance on when to use this tool versus alternatives, nor when not to use it.

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

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

The description goes well beyond annotations by disclosing key behavioral traits: invoke works even when the MCP is not installed and runs one-off without bloating the tool list; writes require workspace owner/admin; invoke may return a connect link or checkout link, after which the user acts and the agent retries. It also explains the prompt library's behavior (search_prompts, get_prompt, publish_prompt with shareable links). These details add significant context that annotations (readOnlyHint: false, openWorldHint: true) do not provide, and there is 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 long but information-dense, with every sentence adding valuable context—especially the KEY distinction between invoke and install, the ownership requirements, and the prompt library overview. It is front-loaded with the core purpose and then expands into action-specific guidance. While it could benefit from bullet points or shorter paragraphs, the density is justified given the tool's complexity and the breadth of actions it supports.

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 (14 actions, 23 params, no output schema), the description covers the essential workflows: discovery, description, invocation, installation, billing, bug reporting, request_mcp, and prompt library use. It explains critical edge cases (not-installed MCPs, credential/payment links, admin permissions). However, it omits some actions (e.g., 'resume') and does not describe the 'limit' or 'immediate' parameters, leaving the agent to infer those from the schema. Overall, it is substantially complete but not exhaustive.

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

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

With 23 parameters and 0% schema description coverage, the description compensates by explaining the semantics of the main parameters indirectly: 'action' is described through the core flow; 'query' is implied via 'capability requests'; 'tool_id' is mentioned in 'pick the right tool_id'; 'mcp_id' is referenced in 'describe returns one MCP's full profile'; 'arguments' is implied by 'invoke RUNS that tool'. The prompt library section explains the purpose of prompt-related parameters (prompt_vars, prompt_slug, prompt_body, etc.) without naming them. However, it does not cover all parameters (e.g., immediate, tier_slug, cancel_reason, conversation), so the compensation is incomplete.

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

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

The description clearly identifies the tool as the official mcp.ai marketplace, serving as both a catalog and execution layer for MCPs/tools. It specifies the core actions (search, describe, invoke) and distinguishes itself from siblings by covering the marketplace domain rather than a specific financial service or utility. The verb 'marketplace' is effectively a noun, but the description immediately defines it as 'the in-platform catalog of every MCP/tool, AND the way to run them', 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 usage guidance, outlining the core flow: 'action=search discovers MCPs by intent → describe returns one MCP's full profile → invoke RUNS that tool'. It also states when to prefer invoke over install ('Use install only to make an MCP PERMANENT in the active toolkit... prefer invoke for a single/occasional use') and when to use other actions (subscribe/cancel, report_bug, request_mcp). It cautions about credential/payment prerequisites and retry logic, giving the agent clear decision rules.

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

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

Annotations already declare destructiveHint=true, and the description consistently explains the deletion of connection data and the unavailability of bank data. It adds value by detailing the return of a reconnect URL. However, it could further clarify side effects (e.g., impact on transaction history). No contradictions with annotations.

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

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

The description is two sentences long with no unnecessary words. It front-loads the key action and then provides the return behavior briefly. Every sentence adds value.

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

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

Given no output schema and a single parameter with no documentation, the description covers the core action and return value, but omits details like the response structure (e.g., confirmation, error handling) and prerequisites (e.g., active consent). For a destructive tool, more context about post-action state would be beneficial.

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 schema description (0% coverage). The description only implies it identifies a specific bank, but does not specify the format, expected values, or how to obtain it (e.g., from list_connections). This leaves the agent guessing about the parameter's exact 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 uses strong verbs ('revokes', 'deletes') and clearly identifies the resource (Open Finance consent for a specific bank). It distinguishes from sibling tools like openfinance_force_sync by specifying the destructive action and the return of a reconnect URL.

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

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

The description implies usage when you want to disconnect a bank and delete its data, but does not explicitly state when not to use it or compare with alternatives. The mention of returning an add_connection_url hints at reversibility, but no direct guidance is provided.

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

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

Discloses waiting behavior (up to ~60s), return shape (results, errors), error conditions (needs_action, timed_out), and reconnection flow. Adds context beyond annotations, which only mark readOnlyHint=false.

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

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

The description is thorough and well-structured, front-loading key behavior. Slightly verbose but every sentence adds value; minor improvements could trim 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, description comprehensively covers return fields (status, executionStatus, lastUpdatedAt, synced, needs_action, reconnect_url, timed_out). All necessary context for a complex sync tool is provided.

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, description fully explains both parameters: wait (fire-and-forget option) and items (array of selectors or omit for all). Meaning is clearly conveyed.

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 action: force a re-sync of connections and wait for completion. It specifies the resource (connections) and distinguishes from siblings by mentioning no disconnect needed.

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 (stale balance/transactions), what it does (pulls fresh data without disconnecting), and provides alternatives like fire-and-forget with wait: false.

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

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

Annotations already indicate read-only and idempotent. The description adds critical behavioral details: structured warning instead of throwing for CREDIT accounts, degradation with realtime:false and warning when upstream unavailable, and response shape. No contradictions.

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

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

Description is a single paragraph of 5 sentences, packing multiple edge cases and response structure without redundancy. Slightly dense but well-organized.

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

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

Given 1 parameter, no output schema, and many sibling tools, the description covers error handling, degradation modes, and response shape comprehensively. No missing context for correct invocation.

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

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

Schema has 0% description coverage, so description carries the burden. It adds meaning: account_ids is an array of strings, size limit 1-50. This is helpful but could specify that IDs are likely from list_accounts.

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

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

The description clearly states it returns real-time balance per account id, with explicit endpoint reference. It differentiates from sibling tools focused on listing accounts or other 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?

Description specifies when to use (get real-time balance), parameter constraints (1-50 account_ids), and handles edge cases (CREDIT errors, upstream degradation). Could be more explicit about alternatives but is sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint), description warns about provider_incident block causing unreliable data and instructs not to present those values as real. Also explains batch shape {results, errors}. Adds significant behavioral context.

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

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

Front-loaded with main purpose, then usage, then warning. Each sentence adds value. Slightly verbose but necessary information, no fluff.

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

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

Covers key behavioral aspects and warning, but lacks full description of return objects. No output schema, so more detail on fields (beyond creditData and provider_incident) would improve completeness. Adequate for a simple param tool.

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

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

Schema coverage is 0% so description compensates minimally: specifies array of strings (account_ids) with range 1-50. Adds meaning beyond schema but lacks explanation of what account_ids represent (e.g., IDs from list_accounts).

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. Mentions HTTP endpoint and batch shape. However, it does not explicitly distinguish from sibling tools like openfinance_list_accounts which might list accounts without full 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?

Provides parameter usage (pass account_ids as array 1-50) but lacks guidance on when to use this tool versus alternatives. No mention of prerequisites or when not to use.

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

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

Discloses important behavioral traits beyond annotations: batch results/errors shape, that Pluggy does not return paid/status field, that payments reflect previous bill's payment, and that creditCardMetadata.billId is sparse/inconsistent. Annotations already indicate read-only, idempotent, non-destructive, so description adds significant context.

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

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

Well-structured and front-loaded with main purpose, then caveats and usage guidance. Every sentence earns its place with no fluff. Length is appropriate given the complexity of the semantics.

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

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

Given no output schema, description adequately explains return shape (batch {results, errors}) and included fields. Also flags missing information (paid/status). For a simple one-parameter tool with tricky semantics, this is highly complete.

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

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

Only one parameter (bill_ids) with 0% schema coverage. Description compensates by explaining it is an array and advising to discover IDs from another tool. Could be more explicit about array format, but adequately adds meaning for simple parameter.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by ID, listing specific fields (financeCharges, payments). It explicitly distinguishes itself from sibling openfinance_list_transactions by stating what it does NOT return (individual transactions) and provides alternative usage.

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: use openfinance_list_credit_card_bills first to discover IDs, use openfinance_list_transactions for itemized transactions, and prefer the bills list tool for payment status. Also warns against using payments array to infer payment status by explaining its typical meaning.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds behavioral details like the reconnect_url purpose and bulk support, which enhances understanding without contradicting 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 three sentences that front-load the main purpose. It efficiently covers singular and bulk use cases without redundancy.

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

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

Despite no output schema, the description explains the return fields and behavior. It addresses input parameters and bulk support, but could be more specific about possible status values (it says 'etc.'). Still, it provides sufficient context for an agent to use the tool correctly.

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

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

With 0% schema description coverage, the description compensates by explaining the key parameters: 'item' for single bank, 'item_ids' for bulk. It also implies 'item_id' is similar but doesn't clarify, causing slight ambiguity. Overall, it adds meaningful meaning beyond the bare schema.

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

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

The description clearly states the tool returns the current status of a bank connection, including specific fields like status, executionStatus, and reconnect_url. It distinguishes between querying one item vs all items, which 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 provides clear usage guidance: omit 'item' for all banks, pass 'item' for a single bank, and mentions bulk support with item_ids. However, it could explicitly state when not to use this tool (e.g., compared to force_sync or list_connections), but it still offers good 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 readonly, idempotent, non-destructive. Description adds concrete response structure (interestRates, charges, etc.) and batch shape ({ results, errors }), which is useful 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?

Two sentences front-load purpose and endpoint, then detail response fields, then usage guidance, then parameter instruction. 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?

No output schema exists, but description enumerates all key response components (interestRates, charges, etc.) and usage context. Single parameter is fully addressed.

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

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

Schema has 0% coverage and no descriptions. Description adds that loan_ids is an array (1-50) and implies batch behavior, providing necessary meaning.

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

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

The description clearly states the tool returns full loan contract detail by ID, specifies the endpoint, and positions it as a deep-dive tool after openfinance_list_loans, distinguishing it from siblings.

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 advises using after openfinance_list_loans for deep-dive on a specific contract, and mentions batch limits (1-50 loan_ids).

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds critical behavioral context: the credit balance caveat, provider incident block effects on reliability, identity notice for duplicate accounts, and bulk support via item_ids.

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 well-structured into logical paragraphs, starting with the main return, then usage details, warnings, and bulk support. Each sentence adds value, though it could be slightly more concise 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 no output schema, the description thoroughly covers return fields, usage modes, edge cases (provider incidents, identity notices), and bulk support. It addresses potential pitfalls like credit balance interpretation, making it complete for the complexity of the tool.

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

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

With 0% schema description coverage, the description compensates by explaining the 'item' and 'item_ids' parameters in detail (e.g., omitting 'item' lists all accounts). However, 'item_id' is not explicitly described, and 'type' is only mentioned in the return context, not as a parameter filter.

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

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

The description clearly states it returns accounts for a bank connection, listing the types (BANK and CREDIT) and the data fields returned. It distinguishes itself from sibling tools like openfinance_list_credit_card_bills by explicitly noting that for credit card bills, a different tool should be used.

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

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

It provides explicit guidance on when to omit or pass the 'item' parameter and warns about the connector-dependent meaning of credit balance, advising against treating it as the month's bill. It also directs to openfinance_list_credit_card_bills for standardized billing amounts.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds caching behavior and that response is single aggregated without batch ids, going 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 concise sentences front-load main action and add key details without redundancy.

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

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

Despite no output schema, description fully enumerates response fields (id, description, descriptionTranslated, parentId, parentDescription) and caching behavior, sufficient for a simple list 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; schema coverage 100%, so baseline is 4. Description adds no parameter info needed.

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

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

Description clearly states it returns Pluggy's transaction category taxonomy, cached per session. It distinguishes itself from siblings by focusing on categories, which is unique among sibling tool names.

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

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

Provides context: id used by openfinance_update_transaction_category and preference for descriptionTranslated for pt-BR users. Could explicitly state when to call before updating, but implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context beyond annotations (e.g., reconnect_url behavior, update mode, no slot consumption) 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?

Two sentences, front-loaded with the core purpose and output fields. No wasted words; every sentence serves a purpose.

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

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

For a simple list tool with no parameters and no output schema, the description is complete. It covers purpose, output fields, and special behavior of the reconnect URL. No gaps.

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

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

Input schema has no parameters, so the baseline is 4. The description adds value by explaining the output fields and special URLs (reconnect_url, add_connection_url), which is more than just schema coverage; it helps the agent understand the return data.

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

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

The description clearly states 'Returns the saved bank connections' with specific output fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). This is a specific verb+resource, and it distinguishes itself from sibling tools like openfinance_list_accounts or openfinance_get_item_status by focusing on 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?

It provides explicit guidance on when to use the reconnect_url ('when a connection needs re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data)') and states it does not consume a slot or require disconnecting first. While it doesn't contrast with all siblings, the context is clear enough for an AI agent.

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?

Details the absence of a 'paid' field, the derived 'payment_status' logic, cross-bill payment matching, connector asymmetry, and bill grouping reliability. Annotations already indicate read-only and idempotent, but the description adds crucial behavioral nuance 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 quite lengthy and dense, mixing field definitions, usage caveats, and warnings in a single paragraph. While content-rich, it would benefit from better structure (e.g., separated sections) and tighter wording.

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 the domain (Brazilian Open Finance) and the absence of an output schema, the description comprehensively explains return fields, derived values, edge cases (e.g., PAST_DUE_UNCONFIRMED), and error handling. It covers nearly all necessary context for correct 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 description thoroughly explains 'account_id' and 'include_open_bill' but fails to document 'page' and 'page_size' parameters. 'account_ids' is briefly mentioned for bulk support. With 0% schema coverage, the description should cover all parameters but misses pagination.

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

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

The description clearly states the tool returns closed credit card bills for a CREDIT-type account, listing key fields and derived attributes. It distinguishes from the sibling tool 'openfinance_get_credit_card_bill' by focusing on listing multiple 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?

Explicit guidance on when to use (e.g., to get closed bills) and when not to (e.g., for itemized transactions). Provides alternatives like 'openfinance_list_transactions' for transactions and explains the opt-in nature of 'include_open_bill'. Also warns about connector-specific limitations and interpretation of payments.

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), the description details error behavior (returns warning instead of throwing) and the data integrity mechanism for suspect zeroing, adding high transparency.

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

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

The description is front-loaded with the main purpose and adds valuable detail on error handling and data integrity. Slightly verbose but each sentence adds value; could be more structured.

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

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

Covers return structure, data integrity, and bulk support, but lacks parameter explanations and pagination details. With no output schema, more on return fields would help.

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 should explain parameters. It only mentions item_ids for bulk support, leaving 'item', 'page', 'type', 'page_size' unexplained despite listing investment types in the overview.

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

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

The description clearly states 'Returns the investment portfolio for a connection' with specific asset types (FIIs, stocks, ETFs, etc.), distinguishing it from sibling tools like openfinance_list_investment_transactions. The verb 'returns' and resource 'investment portfolio' are 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 implicitly guides when to use (to get portfolio overview) and includes behavioral notes on error handling and bulk support. However, it lacks explicit comparisons to siblings or 'when not to use' scenarios.

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=true, idempotentHint=true, destructiveHint=false) already indicate a safe read operation. The description adds behavioral context by detailing the returned transaction types, field names (e.g., agreedRate, brokerageNumber, expenses with sub-items), and bulk support. This enriches understanding beyond annotations without contradiction.

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

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

The description is brief and well-structured: first paragraph defines functionality and output, second paragraph provides usage guidance. No redundant sentences; every sentence adds value. It's front-loaded with the core purpose, making it easy for an agent to quickly understand.

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

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

While the description covers the return data well and provides usage context, it lacks explanation of pagination parameters (page, page_size) and the overall response structure, especially since no output schema exists. For a tool with 4 parameters and no output schema, this is a moderate gap but manageable given the simplicity of the tool.

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

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

Schema coverage is 0% (no property descriptions). The description only partially compensates: it mentions investment_id implicitly (required) and investment_ids for bulk, but ignores page and page_size parameters entirely. For a listing tool, pagination handling is critical; omitting these leaves a significant gap 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 uses a specific verb 'Returns' and resource 'movement history for a specific investment position', listing transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER) and fields (quantity, value, amount, etc.). It clearly distinguishes from sibling tools like openfinance_list_investments and openfinance_list_transactions by specifying it's for a specific investment and includes detailed financial data.

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

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

The description explicitly states 'Use after openfinance_list_investments to get the investment_id', providing a clear prerequisite. It also mentions bulk support with investment_ids. However, it lacks explicit when-not-to-use guidance or alternatives for similar transaction listings, though the sibling context makes this somewhat implicit.

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?

Adds behavioral details beyond readOnlyHint: sequential query per connection, rate-limit spacing, and return format {results, errors}. Annotations already declare safety, but description enriches with execution and response behavior.

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, and each sentence adds 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?

Describes input behavior, execution semantics, and output format comprehensively. Without an output schema, it provides sufficient context for the agent to understand returns and behavior.

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

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

With 0% schema coverage, the description fully explains the `items` parameter: it is an array of connection selectors (uuid, connector_id, or connector_name), and omitting it lists all connections. Adds critical meaning the schema lacks.

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, with the endpoint. It distinguishes from siblings like openfinance_get_loan_detail by focusing on listing multiple loans.

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

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

Provides clear guidance on when to pass `items` for specific connections or omit for all, and notes sequential querying with rate-limit spacing. Does not explicitly state when not to use or compare with alternatives, but context is strong.

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

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

Annotations already indicate read-only and idempotent, but the description adds significant behavioral context: pagination behavior (auto vs manual, truncation at 5000), error handling (returns warning object instead of throwing), provider incident handling, credit card metadata reliability warnings, and bulk execution support. This goes well 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 very long and packs a lot of detail, but it is well-structured with paragraphs and logical flow. It front-loads the main purpose, then covers nuances. However, some sections are redundant (e.g., repeated warnings about billId). A slightly more concise version would be ideal, but it's not wordy without reason.

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 and high complexity (8 params, 1 required), the description covers all aspects: parameter semantics, pagination, error handling, data quality, cross-tool references, and guidance for edge cases (e.g., credit card sync failures). It is fully self-contained and leaves no obvious gaps for an AI agent to operate correctly.

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

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

With 0% schema description coverage, the description fully explains each parameter: from/to as ISO YYYY-MM-DD dates, search_queries as case-insensitive substring OR match, detail enum with detailed explanations of compact/rich/raw, pagination parameters with defaults and interactions, and bulk account_ids. This compensates entirely for the lack of schema descriptions.

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

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

The description clearly states it returns transactions for BANK or CREDIT accounts, and distinguishes itself from siblings like openfinance_list_credit_card_bills by noting that it's the only way to get itemized credit card transactions and that bill totals should come from the other tool. It also references openfinance_get_account_balance for balance information.

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

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

The description provides explicit guidance on when to use the tool (listing transactions) and when not to (e.g., for bill totals, use openfinance_list_credit_card_bills). It also covers pagination modes, filtering, and data quality warnings, making it clear how to operate the tool correctly.

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=true and idempotentHint=true. The description adds substantial behavioral details beyond annotations: it explains the consolidation logic, truncation at 5000/account with a flag, provider incident block, and the effect of different granularity/detail options. 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 long but well-structured, starting with the core purpose, then detailing options and special cases. Every sentence adds value, though it could be slightly more concise. The length is justified by the tool's complexity.

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

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

Given the absence of an output schema, the description compensates by describing the output structure (compact summary with fields like entradas/saídas, por_mes, top despesas, by_account) and special cases (truncation, provider incident). It fully covers the tool's behavior and usage.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It explains all major parameters (item, from, to, granularity, detail, type, item_ids) with their values, defaults, and behavior. The top_n parameter is implied but not explicitly named, yet the overall coverage is thorough and highly informative.

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

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

The description clearly states that the tool performs consolidated cash-flow analysis for a bank connection in one call, resolving accounts internally. It explicitly distinguishes itself from sibling tools by noting that it eliminates the need to call openfinance_list_accounts first.

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

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

The description provides clear context on when to use the tool (e.g., for 'fluxo de caixa', 'maiores gastos') and explains the options for granularity and detail. It does not explicitly state when not to use it, but the context from sibling tools and the detailed usage scenarios compensate.

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 safety profile is clear. The description adds details about returned indicators, degraded components, incidents, and the 'your_banks_affected' field, providing useful behavioral context beyond annotations.

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

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

The description is concise and well-structured: it leads with the main purpose, then explains when to use it, and finally lists what it returns. Every sentence adds value with no unnecessary words.

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

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

Given the tool has no parameters and no output schema, the description provides all necessary context: purpose, usage guidelines, and output contents. It is complete for an agent to decide when and how to invoke the tool.

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

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

The tool has zero parameters, so baseline is 4. The description correctly 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 clearly states it checks the live operational status of the Open Finance provider, using a specific verb and resource. It explicitly distinguishes from sibling tool openfinance_get_item_status, making the purpose unambiguous.

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

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

The description provides clear context for when to use the tool: when data appears incomplete or stale despite a connection showing updated. It differentiates provider-side issues from connection problems. However, it does not explicitly state when not to use it or mention alternative tools beyond one sibling.

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 significant context beyond the annotations (readOnlyHint, idempotentHint, destructiveHint). It explains that the tool is read-only, idempotent, and non-destructive. It also details the caveat warning for credential connectors, plan filtering, and the fact that keywords are required. No contradictions with annotations.

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

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

The description is reasonably concise for the amount of information it conveys. It is front-loaded with core functionality and then adds caveats and plan details. Every sentence serves a purpose; no redundant phrasing.

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 the tool (plan logic, caveat warnings, connector search) and the absence of an output schema, the description thoroughly explains the return values and behavior. It covers what the tool returns, when to use it, and special cases like non-Open-Finance connectors and plan restrictions.

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

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

With 0% schema description coverage, the description fully explains both parameters: 'keywords' is required, expects an array of strings with examples, and 'include_accounts' controls whether accounts are returned. This adds essential semantic meaning beyond the raw schema.

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

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

The description explicitly states the tool searches bank connectors by name, and details the returned fields (connector id, access type, audience, linked connections, connect_url). It clearly distinguishes from sibling tools like 'connect' or 'list_accounts' by specifying its use case and scope.

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

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

The description provides clear guidance: call before connecting, keywords are required (otherwise a hint is returned), and plan behavior is explained. It also mentions the caveat warning for non-Open-Finance connectors. However, it does not explicitly state when NOT to use the tool, though it is implied.

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

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

Annotations indicate non-destructive mutation, and the description adds critical details: the tool overrides automatic categorization and creates a learning rule, plus batch error handling behavior. No annotation contradictions.

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

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

The description is fairly concise given the complexity, front-loading the core purpose. However, it could be slightly shorter by omitting some detail about the batch response shape.

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 is present, but the description provides the return structure and error handling behavior. Side effects and prerequisites are fully covered, making it 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?

Schema has 0% description coverage; the description compensates by detailing the 'items' format, and explaining the origin and purpose of both transaction_id and category_id, adding substantial meaning.

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

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

The description clearly states the tool corrects transaction categories via PATCH, and distinguishes itself from siblings by referencing specific companion tools for ID lookup.

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

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

It explains when to use (fix miscategorizations) and describes the side effect of creating a Category Rule, guiding effective use. Does not explicitly state when not to use, but context is clear.

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

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

Annotations declare idempotentHint=true, but reporting a bug is typically not idempotent (same report may create duplicate tickets). The description does not clarify this behavioral aspect or address side effects. Without annotation contradiction, description adds no value beyond annotations.

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

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

The description is a single, adequately concise sentence that front-loads the purpose and includes a usage instruction. However, it could be better structured with separate sections for 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 low schema coverage and lack of output schema, the description is insufficient. It does not explain return values, error handling, or how the bug report is processed, leaving significant gaps for the agent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'conversation' parameter's purpose but provides no details for 'message' or 'context'. Parameter semantics are only partially 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 clearly states the purpose: reporting bugs, missing features, or sending feedback. It is specific and distinguishes itself from sibling tools which are mainly 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?

There is no guidance on when to use this tool versus alternatives. The only usage hint is to include the conversation array for reproduction. No exclusions or context for choosing this tool over others is provided.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description only needs to confirm the read-only nature. It does so by stating it 'shows' versions, which aligns with annotations. No contradictions.

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

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

Description is a single short sentence that is front-loaded. No unnecessary words or redundant 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?

For a parameterless tool with no output schema, the description adequately explains its purpose. It tells the agent what the tool does and what it returns (versions). No additional context needed.

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

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

No parameters exist, so schema coverage is 100%. The description does not need to elaborate on parameters. Baseline for zero parameters is 4.

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

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

The description clearly states the tool shows current MCP platform and adapter versions. It uses a specific verb and resource, and distinguishes itself from sibling tools like authenticate or openfinance tools which are action-oriented.

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

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

While not explicit about when-not-to-use, the description implies it is for retrieving version information. Given the single purpose and lack of alternatives for this specific info, the usage 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 declare readOnlyHint, idempotentHint, and destructiveHint false, so safety profile is covered. The description adds valuable behavioral context by detailing what the returned state includes (MCP statuses, accounts, tool counts), which goes beyond the structured annotations. No contradictions or hidden side effects are disclosed.

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

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

The description is a single, well-structured sentence that front-loads the main action ('Returns the current toolkit state') and then lists the specific elements. No filler or redundant information is present.

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 parameters and no output schema, the description sufficiently covers what an agent needs to know: what the tool does and what information it returns. The enumerated return contents make the tool's behavior predictable and complete for this simple scope.

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 coverage is 100%. With no parameters to document, the baseline is 4, and the description appropriately avoids adding any parameter-related detail that is not needed.

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

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

The description uses a specific verb 'Returns' and clearly specifies the resource 'current toolkit state' while enumerating exactly what is included (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools like connect or marketplace, which serve different purposes.

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?

There is no guidance on when to use this tool versus alternatives, nor any exclusion criteria. The description implies usage for checking overall status but does not explicitly state a preferred context or mention when a different tool would be more appropriate.

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