Dock MCP

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

Annotations provide idempotentHint=true, readOnlyHint=false, destructiveHint=false. The description adds behavioral context: it explains the browser login flow, token lifetime options, and that calling without args returns a link. 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 clear and front-loaded but slightly verbose (e.g., 'MCP.AI for IDE agents (Cursor, etc.)'). Every sentence adds value, but it could be tightened without losing meaning.

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 one optional parameter, no output schema, and adequate annotations, the description covers all necessary information: purpose, usage, parameter semantics, and behavioral details. 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?

Schema has one optional parameter 'token' with no description (0% coverage). The description fully compensates by explaining its meaning: 'call with { token: '<jwt>' } after the user pastes, or with no args to get the link.'

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: authenticate by logging in via browser and obtaining/copying an access token, or pasting a token for session-only login. It distinguishes from siblings (e.g., connect, marketplace) by being the authentication tool.

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

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

The description provides explicit when-to-use guidance: it explains the two authentication methods (permanent via config, session-only via token) and instructs to call with token or without args. It also notes the best practice for permanent connection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds value by detailing the response structure (authenticated field, pending array, connect_urls). This goes beyond the annotations by describing the tool's output behavior in two conditions.

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 succinct sentences that front-load the core purpose ('Returns connection status and URLs'). Every word adds value, with no redundancy or wasted text.

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

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

Given no parameters, a read-only annotation, and no output schema, the description covers the essential behavior for a simple status check tool. It details both success and credential-missing outcomes. It could mention error handling or rate limits, but for its complexity, 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?

The tool has zero parameters and schema coverage is 100%, so baseline is 4. The description does not need to add parameter information because none exist. It correctly implies no input is required.

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 connection status and URLs. It explains the two distinct scenarios (all connected vs. missing credentials), making the tool's function unambiguous. While it doesn't explicitly distinguish from siblings like 'authenticate', the behavior is specific enough that purpose is 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 explains what happens in two states (all connected vs. missing credentials), but doesn't explicitly guide when to use this tool versus alternatives like 'authenticate' or other openfinance tools. The context signals suggest it's for checking connection status, but explicit usage guidance is absent.

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

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

The description discloses important behavioral traits beyond annotations: invoke works even when the MCP is not installed, does not bloat the tool list, returns connect/checkout links when auth/payment is needed, and writes require workspace owner/admin. It also explains the shareable prompt link behavior and installed_in_toolkit vs installed_in_workspace flags. No contradiction with annotations exists.

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 front-loaded with the main definition and core flow, then logically groups install vs invoke, permission requirements, and the prompt library. It is dense and mostly earns its length given the tool's complexity, though a bulleted or more segmented structure would improve scannability.

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 14-action, 23-parameter tool with no output schema, the description is unusually complete: it covers the main flows, auth/payment edge cases, permissions, and the prompt library. It stops short of specifying return shapes for every action and omits a few action-specific parameters, so it is not perfect, but it is far above the minimum viable level.

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 partially compensates by explaining the action enum values and the roles of mcp_id, tool_id, arguments, and prompt-related parameters in the core flow. However, many parameters like limit, immediate, cancel_reason, report_context, conversation, and prompt_targets are left undocumented, so an agent would still have to guess their 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 defines the tool as 'the official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them,' which clearly states its core purpose. It also distinguishes it from sibling openfinance tools by covering MCP discovery, description, and execution rather than financial data access. The search→describe→invoke core flow further specifies what the tool does.

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 gives explicit usage guidance, e.g., 'Use install only to make an MCP PERMANENT in the active toolkit' and 'prefer invoke for a single/occasional use.' It also explains when to use request_mcp, search_prompts, and publish_prompt, and how to handle credential/checkout retries, making alternative choices within the tool very 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 destructiveHint=true. The description adds that data is deleted and no longer available, and returns a reconnection URL. This adds some context beyond annotations but does not detail side effects or auth requirements.

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 concise sentences with no unnecessary words. The first sentence states the action and consequence, the second adds the return value. Information is front-loaded.

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

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

For a one-parameter destructive tool, the description covers the main effect and return value. However, the parameter 'item' is insufficiently described, and the add_connection_url is mentioned but not explained. Completeness is adequate but not thorough.

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 only mentions 'a specific bank' for the item parameter, leaving it ambiguous whether it is a bank ID, name, or connection ID. The description does not clarify the parameter's format or source.

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 specific verb and resource. It distinguishes from siblings like connect or force_sync by focusing on disconnection.

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, such as openfinance_force_sync or connect. The description does not provide when-not scenarios or prerequisites.

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

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

Describes polling behavior up to 60s, return format, error states (needs_action with reconnect_url), and fire-and-forget option. Annotations don't provide such detail, so description adds significant behavioral context without contradiction.

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

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

Description is thorough but well-structured with logical flow: action, usage, parameters, return, edge cases. Every sentence adds value, though length could be slightly trimmed for absolute 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, description thoroughly explains return structure (results, errors, status fields). Covers all necessary context for correct invocation and interpretation of results.

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

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

Schema has 0% description coverage, but description fully explains both parameters: 'items' as array of selectors (item_id, connector_name, etc.) or omit for all, and 'wait' as boolean for synchronous vs fire-and-forget. This fully compensates for missing schema descriptions.

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

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

The description clearly states the tool forces a re-sync of connections and waits for completion. It specifies the action (force sync), resource (connections), and distinguishes from sibling tools like openfinance_get_item_status.

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

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

Explicitly tells when to use (stale balances/transactions), when not (disconnect/reconnect not needed), and provides alternatives (check status with openfinance_get_item_status after timeout). Also explains parameter options like omitting items for all connections and using wait:false for fire-and-forget.

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 (readOnly, idempotent), it details specific failure modes: BALANCE_FETCH_ERROR for CREDIT accounts, and degradation to last-synced balance with warning for upstream issues. 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 concise and well-structured, though it packs multiple cases into one sentence. It could be slightly more organized but remains clear.

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

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

Even without an output schema, it fully documents the response shape and all edge cases (errors, degradation). The single required parameter is adequately explained.

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

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

With 0% schema description coverage, the description adds the array size constraint (1–50) and implies the array of strings, providing meaningful context beyond the schema.

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

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

The description clearly states it returns real-time balance for account IDs, specifies the GET endpoint, and distinguishes from sibling tools focused on listing accounts or details.

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

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

It explains how to pass account_ids (array of 1–50) and describes error handling. However, it does not explicitly tell when to use this tool versus alternatives like openfinance_get_accounts_detail.

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 significant value by disclosing the provider_incident block and warning that credit limits/balances may be unreliable, which goes beyond the 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?

The description is concise (few sentences), front-loaded with the purpose, and each sentence adds distinct information: what it returns, how to call it, batch shape, and reliability warning. 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?

With only one parameter and no output schema, the description explains the batch response shape and the special provider_incident block. It covers reliability warnings but does not detail the full account object structure. Adequate given the context, but an output schema would be more complete.

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

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

The input schema only specifies the type (array of strings) for account_ids. The description adds constraint of 1-50 items and batch shape, providing useful meaning beyond the schema, though no examples or allowed values are provided.

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 returning full account objects with extended creditData, specifies the HTTP method and path (GET /accounts/:id), and distinguishes it from list tools by focusing on detailed retrieval by ID.

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 states that account_ids must be an array of 1-50 items and describes the batch response shape ({ results, errors }). It provides a critical guideline to not use data when a provider_incident is present, but does not explicitly compare to alternatives like openfinance_list_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?

The description goes well beyond annotations by detailing behavioral traits: it does not return individual transactions, the payments[] array reflects payments registered during this bill's billing cycle (typically for the previous bill), it does not include a paid/status field, and the batch response shape is { results, errors }. It also notes that the billId hint in transactions is sparse/inconsistent. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

The description is relatively long but front-loads the core purpose. Every sentence adds essential information (purpose, limitations, usage guidance, warnings). It could potentially be trimmed slightly, but it remains focused and well-organized. Score 4 for appropriate 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 the tool's complexity (batch results, nuanced payment semantics, no output schema), the description covers all critical aspects: return fields, what is excluded, prerequisites, how to check payment status, and connector-specific inconsistencies. It is complete and leaves no major gaps for an agent to misuse 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%, so the description carries full burden. It explains that bill_ids is an array and instructs the agent to discover valid IDs via openfinance_list_credit_card_bills. While it does not describe the exact format of each ID, it provides actionable context for parameter usage. This adds significant value beyond the schema, justifying a score of 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 begins by stating it 'Returns bill-level detail for one or more credit card bills by id' and lists specific fields (financeCharges, payments[]). It clearly distinguishes the tool from sibling tools like openfinance_list_credit_card_bills (which discovers bill IDs) and openfinance_list_transactions (which returns individual 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 explicitly directs the agent to first use openfinance_list_credit_card_bills to discover bill IDs, warns against using this tool to get individual transactions (recommending openfinance_list_transactions instead), and advises checking payment status via openfinance_list_credit_card_bills. It provides clear when-to-use and when-not-to-use 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=true, idempotentHint=true, destructiveHint=false. The description adds valuable context about the reconnect_url behavior and the response structure ({ count, items } for all). 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 two sentences, front-loading the main purpose and parameter behavior. The first sentence is somewhat long but packs information efficiently without wasted words.

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

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

Given 3 optional parameters and no output schema, the description adequately covers the return elements and the bulk versus single distinction. Minor gap: the response format for a single bank is only implied, not explicitly stated.

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 use of `item` (single bank) and `item_ids` (bulk), but does not explain `item_id`, which is a separate parameter. This leaves a gap for one of the three 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 the status of one or all bank connections, including specific statuses, executionStatus, connector metadata, and reconnect_url. It differentiates between single and bulk retrieval, and the verb 'Returns' is specific to the resource 'status of a bank connection'. Among siblings, this is unique.

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

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

The description provides clear context on when to omit vs include the `item` parameter for single vs all banks, and mentions bulk support via `item_ids`. However, it does not explicitly state when not to use this tool or suggest alternatives among siblings like `openfinance_list_connections`.

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=true and idempotentHint=true, confirming no side effects. The description adds value by detailing the response fields, batch shape ({ results, errors }), and parameter limit, enriching the agent's understanding 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 compact, front-loaded with purpose, then usage guidance and parameter detail. 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 the tool's simplicity (1 param, no output schema), the description covers all needed aspects: purpose, usage context, parameter constraint, and output shape. It is fully adequate for an AI agent to select and invoke the tool correctly.

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

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

Schema has 0% parameter description coverage, so description must compensate. It does so by explaining 'Pass `loan_ids` as an array (1-50).' This adds length constraint and clarifies purpose, but could specify format of loan IDs.

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

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

The description clearly states the verb (returns), resource (full loan contract detail), and method (by id). It differentiates from the sibling tool openfinance_list_loans by specifying 'Use after openfinance_list_loans to deep-dive on a specific contract.'

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 provides explicit usage context: 'Use after openfinance_list_loans to deep-dive on a specific contract.' It also specifies parameter constraints (1-50 loan IDs) and output shape. Does not exclude alternative tools, 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?

Discloses multiple behavioral traits beyond annotations: connector-dependent credit balance, provider incident handling, identity notice for deduplication, and bulk support. 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, but slightly verbose. Every sentence adds value, but could be more concise given the detail.

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

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

Covers all necessary aspects: return fields, usage nuances, caveats, alternative tools, and bulk execution. Complete given the complexity and lack of output schema.

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

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

With 0% schema coverage, the description explains `item`, `type`, and `item_ids` thoroughly but omits explicit mention of the singular `item_id` parameter. Still compensates well overall.

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

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

The description clearly states the tool returns accounts (BANK and CREDIT) with detailed fields, and distinguishes from siblings like openfinance_list_credit_card_bills by specifying what each tool offers.

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

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

Provides explicit guidance on when to use the tool (list all banks vs. single bank) and when to use alternative tools (e.g., for standardized bill amounts), along with parameter usage details.

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. Description adds caching behavior, single aggregated response, and field structure, providing additional context without contradiction.

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

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

Concise, well-structured description. Front-loaded with main purpose, and each sentence adds meaningful information 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?

Given empty input schema and no output schema, the description covers the output fields, caching behavior, and relationship to the update tool, making it fully self-contained 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?

No parameters, so baseline is 4. Description adds value by detailing the output fields (id, description, descriptionTranslated, parentId, parentDescription) and noting that they are cached, which helps the agent understand the data format.

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

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

The description clearly states it returns Pluggy's transaction category taxonomy, cached for the session. It distinguishes from siblings by specifying it's a single aggregated response with no batch ids, and directly ties to the update tool by noting the `id` field 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?

Explicitly states when to use this tool (to get category taxonomy) and hints at usage via the `id` for update. Mentions preferring descriptionTranslated for pt-BR users. Lacks explicit when-not or alternatives, but context with siblings makes it clear.

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

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

Annotations already mark readOnlyHint, idempotentHint, destructiveHint. Description adds valuable context about reconnect_url behavior (UPDATE mode, non-destructive refresh) beyond annotations.

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

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

Single paragraph, reasonably concise. Every sentence adds value, though the reconnect_url explanation could be slightly more compact.

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

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

No output schema, but description fully explains return fields (connector_id, item_id, bank name, URLs) and behaviors. Complete for a parameterless 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 (0 params, 100% schema coverage). Baseline is 4. Description does not need to add parameter details.

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 with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). Distinguishes from sibling list tools by focusing exclusively 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?

Explicitly explains when to use the reconnect_url (for re-authentication, MFA connectors, LOGIN_ERROR, stale data) and notes it does not consume a slot. Does not contrast with other list tools but context is clear.

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

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

Adds extensive context beyond annotations: explains payment timing, derived payment_status logic, open_bill availability conditions, connector asymmetry, and reliability warnings. No contradiction with readOnlyHint annotation.

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

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

While thorough, the description is very long and could be more concise. It front-loads the main purpose but then provides extensive detail that might overwhelm, though each part 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?

Extremely complete: covers derived fields, payment logic, opt-in details, connector limits, reliability warnings, and result structure. No output schema, but description sufficiently explains what to expect.

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?

Given 0% schema coverage, the description compensates well: explains account_id (required), include_open_bill (opt-in with details), and account_ids (bulk support). However, does not explicitly describe page and page_size, though conventional for list endpoints.

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 sibling tools like openfinance_list_transactions for individual 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 guidance on when to use (for closed bills), when not to (for individual transactions), and alternatives (use openfinance_list_transactions). Also warns against misinterpreting payment status and advises on opt-in behavior.

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

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

Annotations already indicate readOnly and idempotent. The description adds valuable behavior details: how it handles 403 errors (returns zeroed response), and the cross-checking mechanism for suspect_zeroed rows. 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 front-loaded with the main purpose and efficiently covers error handling and data integrity. The data integrity section is detailed but essential for correct usage; overall it is well-structured and not overly verbose.

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

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

The description explains return structure and data integrity warnings, but missing parameter documentation leaves gaps. For a complex tool with no output schema, more detail on parameter meanings and result shape would improve completeness.

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

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

Schema description coverage is 0% with 6 parameters. The description only mentions item_ids for bulk support, leaving item, page, type, item_id, page_size unexplained. This fails to compensate 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 the tool returns the investment portfolio for a connection, listing specific asset types. It distinguishes from siblings like openfinance_list_investment_transactions by focusing on portfolio overview rather than transaction history.

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

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

The description implies when to use (to get investment portfolio) and provides specific guidance on handling data integrity warnings. However, it lacks explicit 'when not to use' or direct comparisons with alternative sibling tools.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds detail about return fields (quantity, value, expenses) and bulk support. No contradictions, but it could mention pagination behavior or error handling.

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

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

The description is a single focused paragraph, front-loading the core purpose and fields, then usage guidance. It is concise but could be slightly 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?

Given no output schema, the description explains many return fields and provides usage context. However, it omits pagination details (page, page_size) and lacks explicit response format or sorting behavior.

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

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

With 0% schema description coverage, the description must compensate. It explains investment_id (from list_investments) and investment_ids for bulk, but does not describe page or page_size parameters, leaving 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?

The description clearly states the tool returns movement history for a specific investment position, listing transaction types (BUY/SELL/etc.) and fields. It mentions using after openfinance_list_investments, distinguishing it from sibling tools like openfinance_list_transactions.

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

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

The description advises to use after openfinance_list_investments to get the investment_id, and mentions bulk support. However, it does not provide explicit when-not-to-use alternatives or compare with siblings like openfinance_list_transactions.

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

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

Discloses sequential querying and rate-limit spacing, plus the return structure `{ results, errors }`. Annotations already indicate readOnly and idempotent, so description adds non-obvious behavior 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?

Three highly informative sentences with no redundancy, front-loaded with the main action and endpoint.

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

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

Covers parameter usage, behavior for single vs. multiple connections, and return structure. No output schema exists, but description provides sufficient context for a list tool with one parameter.

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

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

With 0% schema description coverage, the description fully explains the only parameter `items`: it's an array of connection selectors (item_id uuid, connector_id, or connector_name), and how omitting it lists all banks.

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

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

The description clearly states the verb 'list' and resource 'loan contracts per bank connection', and distinguishes itself from sibling tools like openfinance_get_loan_detail by specifying scope (per connection or all).

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

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

Explicitly explains when to use `items` vs. omit it, and mentions rate-limit spacing for multiple connections. However, does not contrast with alternatives like openfinance_get_loan_detail for single loan retrieval.

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 discloses auto-pagination up to 5000 items, truncation, error return instead of throwing, provider_incident block, per-connector inconsistencies (Nubank sparsity), and bulk support. No contradictions with annotations.

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

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

The description is dense and well-structured, but somewhat long with some redundancy (e.g., creditCardMetadata warnings repeated). Front-loaded with purpose, then organized by topics (pagination, detail, etc.). Slightly overly verbose, but clear.

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

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

Given high complexity (8 parameters, many edge cases, no output schema), the description covers all critical aspects: pagination modes, search, detail levels, error behavior, provider incidents, bulk support, and cross-references sibling tools. Complete 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?

With 0% schema coverage, the description fully compensates: explains each parameter's purpose, format (ISO dates), behavior (auto vs manual pagination, defaults, max), detail levels (compact/rich/raw with detailed explanations), and search_queries (case-insensitive substring OR). Adds meaning well beyond schema.

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

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

The description explicitly states it returns transactions for bank accounts (BANK or CREDIT) and distinguishes from siblings like openfinance_list_credit_card_bills for bill totals, making the purpose crystal clear.

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 extensive guidance: when to use this vs. alternatives (e.g., for bill totals use other tool), pagination modes (auto vs manual), date filters, search_queries, detail levels, error handling, and when to check connection health. Explicitly states what not to do (e.g., don't sum by billId).

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read operation. The description adds important behavioral details: capping at 5000 transactions per account with a truncated flag, potential provider_incident block, internal account resolution, and bulk support. This provides useful 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 well-structured with clear sections and front-loaded purpose. It is thorough but somewhat verbose; some phrases could be tightened. However, every sentence adds value, so it earns a high score for conciseness given the amount of information conveyed.

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 (9 parameters, no output schema, multiple enums), the description covers all aspects: parameter usage, behavior (capping, incidents), granularity options, bulk support, and the structure of the compact summary. It is sufficiently complete for an agent to understand and 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 schema description coverage at 0%, the description carries full burden for parameter meaning. It explains each parameter: item (connector_id, connector_name, item_id), from/to (ISO dates), granularity (monthly vs raw), detail (compact, rich, raw), type (BANK or CREDIT), top_n (implied), and item_ids (bulk). The description adds significant semantic value 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 explains that this tool performs consolidated cash-flow analysis for a whole bank connection over a period in one call, distinguishing it from siblings like openfinance_list_transactions which may require multiple calls. It explicitly states you do not need to call openfinance_list_accounts first, providing specificity.

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 this tool, such as for 'fluxo de caixa', 'entradas e saídas', etc., and mentions when to choose granularity monthly vs raw. It advises against calling openfinance_list_accounts first. However, it does not explicitly state when alternatives like openfinance_list_transactions or other tools are more appropriate, so it's slightly less than perfect.

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 read-only and idempotent hints. Description adds valuable behavioral context: it queries a public status page, reveals upstream outages, and specifies return fields (global indicator, degraded components, incidents, your_banks_affected).

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 well-structured with the main action first, followed by use cases and return details. Slightly long but every sentence adds value.

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

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

Given no parameters, no output schema, and rich annotations, the description is fully complete: it explains the tool's purpose, usage scenarios, differentiation, and what information 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?

No parameters exist, so schema coverage is 100%. Description doesn't need to add parameter details, but its clarity about what the tool does compensates fully.

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 specific verb 'Checks' and resource 'provider status page', and distinguishes from sibling tool openfinance_get_item_status.

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

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

Explicitly tells when to use: when data looks incomplete or stale despite UPDATED connection, and contrasts with openfinance_get_item_status to differentiate provider-side vs connection issues.

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

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

Annotations already mark the tool as read-only and idempotent. The description adds crucial behavioral details: keywords are required (returns hint if missing), caveat for non-Open-Finance connectors, plan filtering, and that it returns a ready connect_url. This goes well beyond annotations.

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

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

The description is a single, moderately long paragraph, but every sentence adds value. It front-loads the core purpose, then details returns, caveats, and plan behavior. No fluff.

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

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

Given no output schema, the description thoroughly covers what is returned per match (id, access, audience, connections, accounts, connect_url) and explains edge cases (caveat, plan honors). It is complete enough 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?

Schema description coverage is 0%, but the description fully explains both parameters: keywords with examples and required behavior, and include_accounts with its effect. This adds complete 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 searches bank connectors by name, returns connector details, and provides a connect_url. It distinguishes from sibling tools like 'connect' by specifying it should be called before connecting to get a one-click link, making the purpose very 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 explicitly says 'Call this BEFORE connecting' and explains plan behavior (PF vs PJ). It implies this is the preliminary step before using 'connect', but does not explicitly list alternatives or when not to use, so it gets a 4.

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 the side effect of creating a Category Rule for the client, teaches the system, and explains per-item error handling. This goes beyond the annotations, which only set readOnlyHint=false and destructiveHint=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 a single, well-structured paragraph that front-loads the purpose, then provides usage details and side effects without unnecessary words.

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

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

Covers input format, side effects, and output shape comprehensively for a mutation tool with no output schema, given the complexity of batch updates and rule creation.

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

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

The schema has 0% description coverage, so the description fully compensates by explaining the array structure, required fields (transaction_id, category_id), and their sources (from list tools).

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

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

The description clearly states 'Corrects the category of one or more transactions (PATCH /transactions/:id)' and explains how to obtain the required IDs from sibling tools, distinguishing this from list and other mutation tools.

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

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

Provides clear guidance on when to use (to fix miscategorized transactions and improve future categorization) and explains the batch shape, but does not explicitly state when not to use or mention 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 provide idempotent and non-destructive hints. The description adds that the tool expects a conversation array for reproduction, but does not explain the effect (e.g., creates a ticket, notifies developers) or clarify the idempotency behavior. It is adequate but lacks depth.

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: the first states the purpose, the second provides a key usage instruction. No unnecessary words, front-loaded with essential 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 simple reporting tool with 3 parameters and no output schema, the description is functional but lacks details on what happens after reporting (e.g., response, ticket creation). It could be more complete given the lack of schema descriptions.

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 clarifies the role of the 'conversation' parameter ('recent messages for reproduction') but does not explain 'context' or 'message' beyond the overall purpose. This provides some added value but 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 states the tool reports bugs, missing features, or sends feedback. It is distinct from sibling tools which are primarily openfinance operations, so the purpose is 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 instructs to include the conversation array for reproduction, providing a specific usage context. However, it does not explicitly state when not to use this tool or mention alternative tools, but given the sibling list, the usage 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?

The description adds no behavioral context beyond what annotations already provide. Annotations include readOnlyHint and idempotentHint, which fully cover the safety profile. The description does not disclose any additional traits such as output format or potential side effects.

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

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

The description is a single sentence that is concise and front-loaded with the key action and subject. 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?

Given the tool's extreme simplicity (no parameters, no output schema), the description is complete enough for an agent to understand and invoke it 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?

There are no parameters, so the description does not need to add parameter info. Baseline score of 4 applies since schema coverage is 100% and no parameters 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 the tool retrieves MCP platform and adapter versions. It uses a specific verb ('Show') and resource ('versions'), and distinguishes easily from sibling tools that deal with 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 versus alternatives, but the tool's simplicity makes its usage self-evident. However, it does not mention any exclusion criteria or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing a safe read-only operation. The description adds value by detailing exactly what the returned state contains, going beyond the annotation labels 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 a single, front-loaded sentence that immediately states the action and resource, then efficiently lists all included content. Every word contributes meaning; no filler or 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?

For a zero-parameter, read-only informational tool with strong annotations, the description is complete. It specifies the return content (installed MCPs, statuses, accounts, catalog counts) and needs no further 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?

With zero parameters and an empty input schema, the baseline is 4. The description correctly focuses on output semantics rather than parameters, which is appropriate here.

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 a clearly defined resource ('current toolkit state') followed by precise enumerations: installed MCPs, connection status, connected accounts, and catalog tool counts. This distinguishes it from sibling tools like show_version or connect.

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

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

The description makes the tool's purpose evident: use it when you need an overview of the current toolkit state, including connections and accounts. It does not explicitly mention alternatives or exclusions, but the unique informational scope and zero parameters provide clear context.

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