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?

Annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds substantial context beyond that: the snapshot-vs-live semantics, the sync anchor meaning of updatedAt, credit-specific error warnings, and the degradation fallback with realtime:false. This fully discloses behavioral traits an agent would otherwise have to infer or discover at runtime.

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 but every sentence earns its place: purpose, freshness caveat, sync guidance, parameter constraint, error modes, degradation behavior, and response shape. It is front-loaded with the core action and scopes successive caveats logically, making it easy for an agent to extract the essential facts quickly.

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 a single parameter, no output schema, and no nested structure, the description covers all needed ground: it states the response shape, error array format, edge-case warnings, and the relationship to force_sync. The agent has enough information to decide when to call it, what parameters to pass, and what to expect in return.

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

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

The schema has a single required account_ids array of strings with no descriptions (0% coverage), so the description carries the burden. It adds the key constraint 'Pass account_ids as an array (1–50)' and clarifies it works per account ID. It could have explained where the IDs come from (e.g., from openfinance_list_accounts) or their format, but the provided guidance is sufficient for safe invocation.

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 opens with a specific verb ('Returns') and resource ('latest available balance per account id'), and makes the tool's scope explicit by naming the exact endpoint. It clearly distinguishes itself from siblings like openfinance_list_accounts (which lists accounts) and openfinance_force_sync (which syncs data), so an agent can pick it without guessing.

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 when-to-use guidance: use it for the freshest balance the provider can serve, and if the balance is stale or disagrees with transactions, run openfinance_force_sync then re-read. It also tells the agent when not to expect live data and how to handle credit-account and provider-outage edge cases, which effectively routes to alternatives when needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, 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 far beyond the readOnlyHint annotation by explaining that transactions are not included by default, that transactions_basis may only yield estimates, that totalAmount should be trusted over a manually summed transaction total, and that payments[] describes the prior bill—not the current bill. The content is consistent with 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 long but dense, with clear topic sections and no dead sentences. The return fields come first, then the conditional transaction opt-in, then the matching semantics and billing caveat. The formatting makes the dense information navigable.

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 tool with no output schema, the description does a full open job: it covers the fields, batch shape, transaction shifting, status limitations, and the actual billing-cycle meaning of payments[]. An agent has enough information to choose workflows correctly and to interpret results safely.

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 carries the burden of explaining most parameters: bill_ids is to be used as an array, include_transactions is the opt-in trigger, and account_id is needed because bills lack an account reference. The one gap is transactions_detail and its compact/rich/raw enum, which is never explained.

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 with a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id,' and enumerates the returned fields. It clearly distinguishes itself from the sibling listing tool by focusing on detail 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?

The description explicitly tells the agent to use openfinance_list_credit_card_bills first to discover bill ids, and to prefer that sibling for the paid/status field. It also routes transaction-level needs to openfinance_list_transactions, giving both usage context and exclusion timing.

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?

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description goes well beyond them by disclosing connector-dependent credit balances, stale/phantom `bankData` values that lag after connection, provider incidents that make values unreliable, and identity_notice deduplication rules. These are exactly the behavioral nuances an agent cannot infer from the schema or 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 organized into logical blocks: core return fields, bank vs legal-entity naming, item filtering, credit balance caveats, notices, and bulk support. Nearly every sentence adds needed operational context, though it is dense enough that a few points could be condensed without losing 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 only bare parameter names, the description is highly complete: it explains what fields appear, how `bank` and `name` differ, how to aggregate across banks, how to handle connector-dependent credit balances, what `balance_notice` means, how to handle provider incidents, and how identity_notice affects deduplication. It leaves no critical gap for an agent to call 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 carries the full parameter burden and largely succeeds: it explains `item` vs omitting it, implies `type` via BANK/CREDIT account types, and introduces `item_ids` for bulk execution. However, the singular `item_id` input parameter is not explicitly distinguished from `item`; it only appears as a row tag in the response, leaving a small semantic 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 opens with a specific verb and resource: returns BANK and CREDIT accounts for a bank connection, listing the exact fields returned. It also distinguishes itself from openfinance_list_credit_card_bills by clarifying which tool provides standardized bill amounts, so an agent can differentiate it from a key sibling.

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 conditional usage instructions: omit `item` to aggregate across all banks, pass `item` to target a single bank, and use openfinance_list_credit_card_bills for standardized open-bill/total-debt values. It also tells the agent not to rely on `balance` when `balance_notice` is present, which is concrete when-to-use-this-tool 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. 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?

Animations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds substantial extra behavior: scheduled future-dated rows, date-descending ordering, automatic pagination versus manual pagination, aggregation limits with truncated responses, error-return behavior instead of exceptions, provider incidents, and per-connector inconsistencies around billId and PENDING status. None of this is available in the annotations and there is no contradiction with them.

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

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

The description is front-loaded with the core purpose and uses clearly separated paragraphs, but it is unusually long. There is some redundancy, especially around the billId warning, which appears both in the main credit card section and again in the detail-'rich' explanation, making the text less concise than it could be. Every part earns a place, but a leaner edit would make it more maintainable 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?

The tool is complex, has 8 parameters, no output schema, and no parameter descriptions, yet this definition comprehensively covers input semantics, pagination modes, returned shapes, warnings, incident conditions, health checks, and bulk support. It even explains what fields appear in the output like account echo, scheduled_count, notice, and truncated, which fully compensates for the lack of an explicit 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?

The schema provides no descriptions for its parameters, but the description thoroughly explains every meaningful parameter: from/to as ISO YYYY-MM-DD filters, page/page_size switching between automatic and manual pagination, detail with compact/rich/raw semantics and token implications, search_queries for case/accent-insensitive substring matching with OR semantics, account_ids for bulk execution, and what the account_id means in the response echo. This fully compensates for the 0% schema description coverage.

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

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

The description clearly states its verb and resource: 'Returns transactions for a bank account (BANK or CREDIT type),' and immediately distinguishes it from related tools by calling it the ONLY way to get itemized transactions for credit card accounts. This prevents confusion with sibling tools like openfinance_get_credit_card_bill and openfinance_list_credit_card_bills.

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

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

The description explicitly names when to use this tool versus alternatives: use it for itemized credit transactions, use openfinance_list_credit_card_bills for a standardized open-bill/pending-debt total, use openfinance_list_accounts for closing/due dates, and use openfinance_get_item_status for investigating zero credit results. It also provides a clear 'when-not-to' by warning not to reconstruct bill totals from this tool's output.

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.