PicPay MCP

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

Beyond annotations (idempotentHint, destructiveHint, readOnlyHint), the description reveals that the tool can either persist the token (if config is set) or use it only for the session, and that calling without args returns a login link. It does not contradict annotations: idempotentHint is consistent as calling with the same token multiple times results in same state. It does not disclose error handling or security implications, but overall adds useful behavioral context.

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

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

The description is a single paragraph that is information-dense but logically organized: it starts with the target audience and primary use case (permanent token), then the session variant, then explicit function call syntax. Every sentence adds value. Could be slightly more concise, but it's well-structured.

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

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

Given that the tool has only one optional parameter and no output schema, the description covers the essential usage scenarios: permanent config, session login, and obtaining the login link. It explains the authentication flow effectively. However, it omits details like what the response looks like (e.g., success message) or how to handle errors, but for the tool's simplicity, it is reasonably 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 defines 'token' as an optional string with no description. The description compensates fully by explaining that the token is a JWT, and specifies the two call patterns: with token for session login, without token to get link. This adds essential meaning that the schema lacks.

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

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

The description clearly states that the tool is for authentication: it allows the user to either configure a permanent token via server config or pass a token for session login, or get a link to log in. It uses specific verbs like 'log in', 'copy', 'add', 'paste', which precisely describe the action. It distinguishes itself from sibling tools by focusing on token-based authentication for the MCP server.

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 instructions on when to use each variant: for permanent connection, add to config; for session, call with token; to get login link, call with no args. It does not directly compare with siblings like 'connect', but within the tool's purpose, it gives clear 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, and destructiveHint=false. The description adds valuable behavioral context by describing the response in two states (authenticated:true vs connect_url), which goes beyond what annotations provide.

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

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

Two concise sentences. First sentence front-loads the primary purpose. Second sentence elaborates with scenario details. No wasted words.

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

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

For a simple read-only tool with no parameters and no output schema, the description covers the main behavior and key response states. It could be slightly more complete by noting that it does not modify state, but annotations already hint at that.

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

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

The tool has zero parameters, so schema coverage is 100%. The description adds no parameter information, which is appropriate. Baseline score of 4 for 0-parameter 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 the tool returns connection status and URLs, and explains the response for two scenarios (all connected vs missing credentials). It uses a specific verb (returns) and resource (connection status and URLs), distinguishing itself from siblings like authenticate or openfinance_list_connections.

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

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

The description implies usage for checking connection status but does not explicitly state when to use this tool versus alternatives like authenticate or openfinance_list_connections. No when-not or alternative guidance is provided.

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

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

The description goes far beyond the minimal annotations, disclosing key behavioral traits: invoke works even when an MCP is not installed and runs it one-off without bloating the toolkit; credentials trigger a connect link; empty wallet triggers a checkout/top-up link; writes require workspace owner/admin. It also explains the installed_in_toolkit vs installed_in_workspace flags and the one-off install behind invoke. This rich context is not present in 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 a single dense paragraph, but it is information-dense with no fluff — every sentence adds value. It could be better structured with bullet points, but given the tool's 14 actions and prompt library scope, the length is justified. It is front-loaded with the core definition and flow.

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

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

The description covers the complete tool landscape: core flow, installation vs invocation, auth and billing edge cases, workspace owner permissions, installed flags, prompt library, and when to use request_mcp. Despite having no output schema, it gives enough context for an agent to select and invoke the right action, including error-handling behavior (connect/checkout links and retry).

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 parameters. It maps the action enum to specific behaviors (search, describe, invoke, install, subscribe, etc.) and explains the role of tool_id and arguments in the invoke flow ('pick the right tool_id → invoke RUNS that tool'). It also covers prompt-related params via get_prompt and publish_prompt. However, some params like limit, immediate, conversation, and prompt_targets are not explicitly explained, leaving a small 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 clear definition: 'The official mcp.ai marketplace — the in-platform catalog of every MCP/tool, AND the way to run them.' It specifies the scope (cataloging and running MCPs) and distinguishes itself from sibling tools like openfinance_* which are specific financial MCPs. The core flow (search → describe → invoke) is explicitly stated, making the tool's purpose unmistakable.

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

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

The description provides explicit when-to-use guidance: 'use install only to make an MCP PERMANENT... prefer invoke for a single/occasional use.' It also contrasts subscribe/cancel for billing, report_bug for feedback, and request_mcp for new MCP requests. The description clearly states when to choose the prompt library actions (search_prompts/get_prompt/publish_prompt) versus MCP actions, and even covers the fallback when nothing fits.

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 the bank's data will no longer be available and that a re-connect URL is returned, which is useful behavioral context beyond what annotations provide.

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

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

Three concise sentences that front-load the primary action. Every sentence adds value 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?

Covers the core purpose, effect, and return value. However, it lacks explanation of the parameter format and any prerequisites. For a straightforward tool with one parameter, it is adequate but not fully 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 sole parameter "item" is not described in the schema or the tool description. The description mentions "specific bank" but does not clarify what the string value should represent (e.g., ID, name, token). With 0% schema coverage, this is a significant gap.

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

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

Clearly states the action: revokes consent and deletes connection data for a specific bank. The verb "disconnect" combined with the description makes the purpose unmistakable, and no sibling tool performs a similar function.

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. The sibling set includes related tools (e.g., connect, list_connections), but the description does not compare or indicate prerequisites such as having an existing 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 are not contradictory. The description reveals polling behavior (~60s timeout), mutation (PATCH), return structures (status, executionStatus, synced), and reauthentication handling (needs_action with reconnect_url). It adds significant context beyond 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 well-structured: main action, use case, parameter details, return fields, edge cases. It is slightly long but every sentence adds value. Could be tightened slightly but still effective.

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

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

Given no output schema, the description fully explains input parameters and return fields (results, errors, status, executionStatus, lastUpdatedAt, synced, needs_action, reconnect_url, timed_out). It covers error handling, timeout, and fallback. Complete for a tool of this 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 coverage is 0%, so description must carry the burden. It thoroughly explains the `items` parameter (array of selectors like item_id, connector_name, custom_label) and the `wait` parameter (default behavior and fire-and-forget). Adds meaning that the schema alone does not convey.

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 bank re-sync and waits for completion. It distinguishes from siblings like openfinance_get_item_status by framing it as a refresh tool and noting the alternative check. The verb 'forces' and resource 'connections' are specific, and the scope (one or all) is explicit.

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 (stale balance/transactions) and what not to do (no disconnect/reconnect). Provides alternatives like openfinance_get_item_status for timed_out cases. Describes optional fire-and-forget behavior with wait: false, giving clear use-case 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?

Beyond annotations indicating idempotent, read-only, non-destructive, the description adds critical behaviors: CREDIT accounts may return a warning instead of error, and temporary upstream unavailability degrades gracefully with realtime: false and a warning. Response shape is also given.

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 dense paragraph that efficiently covers purpose, constraints, error behaviors, and response shape. It front-loads the key action and endpoint. Slightly lacking in structure but not 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?

Given no output schema, the description explains the response shape and error scenarios. It does not mention pagination or filtering, but the tool only takes account_ids, so it is fairly complete for its scope.

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

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

With 0% schema description coverage, the description compensates by explaining account_ids as an array (1–50). It adds value beyond the schema's basic type definition, though it could clarify the format of each string (presumably account 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 tool returns a real-time balance payload per account ID, references the exact endpoint (GET /accounts/:id/balance), and distinguishes from siblings like openfinance_list_accounts by focusing on balance retrieval.

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 usage details (pass account_ids as array of 1–50) and error handling, but does not explicitly state when to use this tool vs alternatives or exclude specific scenarios.

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

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

Annotations already declare readOnly and idempotent. Description adds batch response shape ({ results, errors }) and crucial caveat about provider_incident making values unreliable, exceeding annotation coverage.

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 focused sentences: first describes main action and parameter, second adds important behavioral note. No filler, but could be slightly streamlined 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?

Covers return shape, parameter usage, and key reliability caveat. For a simple read tool with no output schema, this provides sufficient context. Minor gaps: no mention of error format or rate limits, but annotations cover safety.

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

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

Schema has 0% description coverage; description adds that account_ids must be an array of 1–50 IDs, giving practical constraint beyond schema type definition.

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

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

Clearly states the verb 'Returns' and resource 'full account objects including extended creditData' per ID. Distinguishes from sister tools like openfinance_list_accounts by specifying deeper detail retrieval.

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?

Instructs to pass account_ids as an array (1–50) and warns about provider_incident block, but does not explicitly state when to use this tool vs alternatives like list_accounts or get_account_balance.

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

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

Annotations mark it as read-only, idempotent, non-destructive. Description adds critical behavioral context: batch shape {results, errors}, missing paid/status field from Pluggy, payments[] meaning (usually previous bill payment), and sparse creditCardMetadata.billId on some connectors. No contradiction with annotations.

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

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

Description is detailed but well-structured: starts with return value, then what not to expect, then usage instructions, then warnings. Each sentence serves a purpose, though slightly lengthy. Could be trimmed slightly 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?

Given complexity (credit card billing nuances, connector inconsistencies, payment timing), the description covers all necessary aspects: batch shape, missing paid field, payment interpretation, and cross-bill matching for payment_status. No output schema but explains return fields sufficiently.

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

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

Only parameter bill_ids has 0% schema description coverage. Description compensates by stating it's an array and guiding users to discover IDs via openfinance_list_credit_card_bills. Provides sufficient meaning beyond the schema.

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

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

Clearly states it returns bill-level detail for credit card bills by ID, listing specific fields (financeCharges, payments). Distinguishes itself from sibling tools like openfinance_list_transactions (which returns itemized transactions) and openfinance_list_credit_card_bills (which discovers IDs).

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 this tool vs alternatives: 'Does NOT return individual transactions — to get itemized credit card transactions... use openfinance_list_transactions'. Advises to first use openfinance_list_credit_card_bills to discover IDs. Warns against reconstructing totals from 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?

The description adds valuable behavioral context beyond annotations: the reconnect_url reopens the widget in UPDATE mode without disconnecting or consuming a connection slot. It also explains bulk execution. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent with the read-only nature of returning status.

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 paragraph that efficiently conveys key information. It is front-loaded with the main return fields and usage scenarios. A more structured format (e.g., bullet points) could improve scanability but is not essential.

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

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

The description covers the return formats for both single and all banks, including fields like executionStatus and reconnect_url. Although there is no output schema, the explanation is sufficient for correct usage. Sibling tools provide more detailed data, so this tool's scope is well-defined.

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

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

Schema coverage is 0%, so the description must explain parameters. It explains the effect of omitting `item` and passing `item`, and mentions `item_ids` for bulk. However, the difference between `item` and `item_id` is not clarified, leaving ambiguity about which identifier to use.

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

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

The description clearly states the tool returns the current status of a bank connection, including specific fields like executionStatus, connector metadata, and reconnect_url. It distinguishes between getting status for all banks (omit `item`) and a single bank (pass `item`), which differentiates it from sibling tools like `openfinance_list_connections`.

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

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

Clear guidance is provided on when to omit `item` (all banks) vs pass it (single bank), and bulk support via `item_ids` is mentioned. However, no explicit comparison to alternative tools (e.g., `openfinance_list_connections` vs this status tool) is given.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds value by specifying the batch return shape `{ results, errors }` and the limit of 50 loan_ids, enhancing transparency beyond annotations.

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

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

Single, information-dense sentence front-loads purpose, lists key fields, usage hint, parameter spec, and return shape with zero 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?

No output schema exists, so description explains return fields and batch shape adequately. Covers main aspects for a tool that retrieves loan detail by ID, though could mention error handling slightly more.

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 and only one required param `loan_ids`. Description compensates by stating it accepts an array of 1-50 strings, providing syntax and constraints not in the schema.

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

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

Description clearly states it returns full loan contract detail by ID, lists specific fields, and distinguishes from sibling openfinance_list_loans by saying 'Use after... 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?

Explicitly advises to use after openfinance_list_loans, and mentions batch processing with `loan_ids` array (1-50). No explicit when-not or 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?

Beyond annotations (readOnlyHint, idempotentHint), the description discloses important behaviors: omitting 'item' aggregates across connections, credit balance meaning is connector-dependent, provider incidents may yield unreliable values, identity notices require deduplication. No contradiction with annotations.

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

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

The description is very long and covers many details. While front-loaded with the main purpose, the subsequent paragraphs could be more concise. Every sentence provides value, but the overall length reduces readability.

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 comprehensively explains return fields (balance, number, type, subtype, bankData, etc.) and handles edge cases (provider incidents, identity notices, credit balance nuance). Missing pagination or sorting details, but overall sufficient for a 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?

Despite 0% schema coverage, the description explains 'item' and 'type' well (filtering and why type enum values mean). However, 'item_id' is not explained at all, and the relationship between 'item', 'item_id', and 'item_ids' is unclear. Bulk support is mentioned but the role of 'item_id' individually is missing.

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 defines the tool's purpose: listing accounts (BANK and CREDIT) for bank connections. It specifies the returned fields and distinguishes between listing all accounts (by omitting 'item') vs. listing for a single bank (by passing 'item'). This aligns well with the tool name and sibling tools.

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

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

Provides explicit guidance on when to omit 'item' (for all accounts) vs. pass 'item' (for a single bank), mentions alternative tool (openfinance_list_credit_card_bills) for standardized bill info, and warns about credit balance interpretation. Also explains bulk support via 'item_ids' and edge cases like provider incidents and identity notices.

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 it read-only and idempotent. The description adds caching behavior, field semantics, and clarifies there is no pagination or batching ('Single aggregated response — no batch ids'). Adds significant behavioral context beyond annotations.

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

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

A single, well-structured paragraph. Each sentence contributes meaning: first sentence states purpose and caching, second describes fields, third confirms no batching. No redundancy or unnecessary details.

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

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

For a parameterless tool with no output schema, the description completely covers what the response contains, including field usage and language preference. No gaps remain.

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

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

No parameters, so schema coverage is 100%. Description does not need to explain parameters but compensates by documenting the return structure fully, which is especially valuable since there is no output 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?

Describes clearly that it returns Pluggy's transaction category taxonomy, specifying the source and the exact fields in each entry (id, description, etc.). It also explicitly links the id to its use in openfinance_update_transaction_category, distinguishing it from sibling tools.

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

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

Provides implicit usage guidance by noting it's cached (so avoid repeated calls), mentions that descriptionTranslated is preferred for pt-BR users, and clarifies there are no batch capabilities. Lacks explicit comparison to other list tools like openfinance_list_accounts, but the context is clear enough.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context by stating the reconnect_url behavior (does not consume connection slot, no disconnect needed) and what data is returned.

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 with zero wasted words. Primary purpose is stated first, followed by key behavioral detail about the reconnect_url. Highly efficient.

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

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

For a zero-parameter, no-output-schema tool with rich annotations, the description covers the return fields and explains a critical special field. Could be slightly more explicit about output structure (e.g., array), but adequate.

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

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

No parameters exist, so baseline is 4. The description does not need to add parameter info and does not contradict 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 uses the specific verb 'returns' and resource 'saved bank connections' and lists the fields included. It distinguishes from sibling tools like openfinance_disconnect_bank by explaining the reconnect_url field's purpose.

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

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

The tool's purpose is straightforward—listing connections. The description explains the reconnect_url's use case for re-authentication, but does not explicitly contrast with other list tools or state when not to use this tool.

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

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

The description discloses behavioral nuances beyond annotations, such as how payments are attributed to bills, the derived payment_status logic, open_bill availability conditions, and bill grouping reliability warnings. Annotations already indicate readOnlyHint and idempotentHint, and the description aligns with them while adding critical 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?

The description is very long and verbose, containing multiple paragraphs and detailed explanations. While it is organized with sections, it could be more concise. The front-loaded purpose is clear, but the density of information may overwhelm the agent.

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

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

Given the complexity of the tool, zero schema coverage, and no output schema, the description provides exhaustive context: payment semantics, open bill derivation, connector asymmetry, bulk support via account_ids, and cross-references to other tools. It is complete enough for correct invocation.

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

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

With 0% schema description coverage, the description adds meaning for include_open_bill and account_ids, but fails to explain page and page_size parameters. account_id is implied but not explicitly defined. This partial coverage leaves gaps for pagination 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 "Returns CLOSED credit card bills for a CREDIT-type account" and lists the fields, making the purpose explicit. It distinguishes from sibling tools by mentioning that itemized transactions are handled by 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 provides extensive guidance: when to use include_open_bill (opt-in for open bill and total debt), warns about connector asymmetry, explains payment status derivation, and tells the agent to use a different tool for individual transactions. It also includes explicit instructions like "NEVER call such a bill 'vencida' categorically."

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 the tool read-only and idempotent. The description adds significant behavioral detail: graceful error handling (returns warning instead of throwing), and data integrity cross-checking for mass zeroing positions. 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 relatively verbose with two long paragraphs. It is front-loaded with the main purpose and has clear structure, but could be more concise without losing 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?

Given the complexity (6 parameters, no output schema, no parameter descriptions), the description covers return data and edge cases well but neglects parameter semantics. It is adequate for a read-only list tool but misses key context for proper invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It only mentions 'bulk support: accepts item_ids' and implicitly references 'connection' (likely the 'item' parameter). The other 4 parameters (page, type, item_id, page_size) are not explained, leaving the agent with little guidance.

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 investment portfolio details for a connection, listing asset types and fields. It distinguishes from siblings by its focus on portfolio holdings rather than transactions or accounts, though not explicitly.

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 (for portfolio data) but does not provide explicit when-not-to-use or alternative tool names. Usage guidance is implicit from context and tool name.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it returns movement history with specific transaction types and bulk support. No contradictions, and adds behavioral context beyond annotations.

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

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

Two concise, well-structured sentences. The first sentence front-loads the core purpose and output fields. The second adds usage context. No unnecessary words.

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

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

For a list tool with no output schema, the description provides detailed output fields and transaction types, along with bulk support. Missing details: pagination behavior (though page/page_size params exist) and any prerequisites beyond investment_id. Overall adequate.

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

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

Schema coverage is 0%, so description must carry the burden. It explains investment_id (obtained from another tool) and investment_ids for batch, but provides no explanation for page and page_size parameters. This leaves two parameters with no semantic guidance.

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 movement history for investment positions, lists specific transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER), and mentions fields like quantity, value, etc. It distinguishes from sibling tools by indicating it should be used after openfinance_list_investments.

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 to use after openfinance_list_investments to get the investment_id and supports batched execution via investment_ids. No explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds sequential query behavior, rate-limit awareness, and response format ({results, errors}), which are not in annotations.

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

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

Three sentences, front-loaded with purpose, no redundant words. Each sentence adds 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?

Covers parameter usage, response structure, and default behavior. Missing details on pagination or specific rate limits, but sufficient for basic understanding.

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

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

With 0% schema description coverage, description fully compensates by explaining 'items' format (uuid, connector_id, or connector_name), behavior per connection, and effect of omission.

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', resource 'loan contracts', and context 'per bank connection'. It distinguishes from sibling tools like openfinance_get_loan_detail by focusing on listing across 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?

Provides explicit instructions on using 'items' parameter for specific connections and omitting for all banks. Mentions sequential rate-limit spacing but lacks when-not-to-use or alternative suggestions.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description discloses numerous behavioral traits: credit card pending/posted behavior, billId sparsity, pagination auto vs manual, error handling (returns error instead of throwing), detail level trade-offs, account echo, provider incidents, and bulk support. It fully informs the agent of expected behaviors.

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

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

The description is quite long but well-structured, starting with core purpose and then addressing credit card specifics, pagination, detail levels, and other details. Each sentence adds value given the tool's complexity. Slightly verbose but effective; front-loaded with key purpose.

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

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

Given the tool's complexity, the description is remarkably complete. It covers credit card metadata caveats, pagination modes, error responses, detail options, account identification, provider incidents, and bulk support. No output schema exists, but the description outlines response structure (account echo, results, truncated, warning, error).

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

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

The input schema has 0% description coverage, but the description compensates fully by explaining all 8 parameters: account_id/account_ids, from/to (ISO YYYY-MM-DD), page/page_size (auto vs manual), detail (compact/rich/raw with trade-offs), and search_queries (case-insensitive substring match, OR semantics). It adds semantic meaning beyond the schema's property definitions.

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

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

The description clearly states the tool returns transactions for bank accounts (BANK or CREDIT type). It differentiates from siblings by noting that for CREDIT accounts, this is the only way to get itemized transactions and references openfinance_list_credit_card_bills for bill totals.

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

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

The description provides extensive guidance on when to use this tool (for transactions, especially credit card itemized), when not to (for bill totals, use openfinance_list_credit_card_bills), and alternatives for related tasks (e.g., openfinance_list_accounts for statement dates, openfinance_get_item_status if total is 0). It also explains pagination modes and filter usage.

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

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

Beyond the annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false), the description adds vital behavioral details: the tool caps at 5000 transactions per account and sets a truncated flag, may include a provider_incident block when data could be incomplete, and describes how granularity affects output (compact vs raw 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 relatively long but well-structured. It starts with the core purpose, then covers parameter details, use cases, and special behaviors. Every sentence adds value, though some Portuguese terms (e.g., 'entradas, saídas') might slightly reduce clarity for English speakers. Overall, it is efficient for the tool's complexity.

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

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

Given the tool has 9 optional parameters, no output schema, and is moderately complex, the description is remarkably thorough. It covers the output content for monthly granularity (totals, monthly evolution, top expenses, per-account breakdown), truncation behavior, provider incidents, and batch support. Only minor details like error handling beyond provider incidents are omitted, but overall it is complete for an agent to use correctly.

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

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

With 0% schema description coverage, the description carries full burden and excels. It explains the purpose and allowed values of key parameters: item accepts connector_id/name/item_id, from/to are ISO dates, granularity defaults to monthly but can be raw, detail enriches rows, type filters BANK/CREDIT, and item_ids enables bulk. This adds significant meaning beyond the raw schema.

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

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

The description clearly states this tool performs consolidated cash-flow analysis for a bank connection in one call, resolving accounts internally. It distinguishes itself from siblings like openfinance_list_transactions by removing the need to call accounts first. It also provides specific use cases (e.g., 'fluxo de caixa', 'maiores gastos'), making its purpose unambiguous.

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

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

The description explains when to use this tool (for consolidated analysis, avoiding multiple calls) and provides guidance on parameters like granularity and detail. It mentions limitations (5000/account cap, provider incidents) but does not explicitly name alternative tools or state when not to use it. Still, the context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds valuable behavioral context beyond annotations: it checks an external provider's status page, not local data, and returns specific fields like global indicator, degraded components, open incidents, and 'your_banks_affected'. 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 moderately long but every sentence contributes value. It front-loads the main action, then provides usage guidance, then lists return fields. It is well-structured and contains no superfluous words. It could be slightly more terse, but the content justifies its length.

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

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

Given that the tool has no parameters, the description carries the full burden of explaining the tool's purpose and output. It fully describes the return fields (global indicator, degraded components, open incidents, your_banks_affected) and provides troubleshooting context. It is entirely sufficient for an agent to understand when and why to use it.

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

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

The input schema has zero parameters, so there is no need for parameter descriptions. The baseline for 0 parameters is 4, and the description adequately explains what the tool returns, effectively documenting the output in lieu of an output schema. Since schema coverage is 100% (no params), no further parameter info is needed.

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

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

The description begins by explicitly stating the tool checks the LIVE operational status of the Open Finance provider's public status page. It clearly distinguishes this from the sibling tool 'openfinance_get_item_status', which checks the user's own connection. The verb 'checks' and the resource 'provider status' are specific and unambiguous.

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

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

The description provides explicit guidance on when to use this tool: 'whenever data looks incomplete or stale even though a connection shows UPDATED'. It gives concrete scenarios (accounts/transactions/balances missing) and explains what it reveals (upstream outage, known incident). It also contrasts with the sibling tool, making the usage context extremely clear.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds value: it returns connect_url, honors user plan, never dumps catalog, and surfaces caveats for credential connectors. 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?

Single dense paragraph with front-loaded main function. Some redundant phrasing but overall efficient. Could be slightly more structured (e.g., bullet points).

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 covers return fields, plan logic, caveats, and required input. Complete for a search tool with these parameters.

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

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

Schema coverage 0%, but description explains keywords[] (required, example) and include_accounts (triggers account inclusion). Lacks format details for keywords items, but sufficient for usage.

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 searches bank connectors by name, returns connector id, access type, audience, linked connections, and a connect URL. It distinguishes from siblings like openfinance_list_connections, as it is meant to be called before connecting.

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 says 'Call this BEFORE connecting' and that keywords[] is required. Provides context (e.g., honoring plan, surfacing warnings) but lacks explicit alternatives or when-not-to-use.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the tool overrides automatic categorization and teaches Pluggy by creating a Category Rule. It also details the batch response shape with per-item error handling, providing full behavioral transparency.

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

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

The description is a single paragraph that is front-loaded with purpose and covers parameter format, side effects, and response shape. It is efficient but could be slightly more concise; every sentence contributes 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, the description explicitly describes the batch response structure (`{ updated, results, errors }`) and explains partial error handling. It covers all necessary context for correct usage, including side effects and data sources.

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

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

With 0% schema description coverage, the description fully compensates by explaining that `items` is an array of { transaction_id, category_id } and specifies the source of each ID (from list_transactions and list_categories). This adds critical 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's purpose: 'Corrects the category of one or more transactions'. It uses a specific verb ('corrects') and resource ('transactions'), and distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_categories by specifying the update action.

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

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

The description provides clear context on when to use the tool: to fix miscategorized transactions and improve future categorization. It tells where to obtain required IDs (from list_transactions and list_categories) and explains the side effect of creating a Category Rule. However, it does not explicitly state when not to use the tool, leading to a score of 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?

Annotations already declare idempotentHint=true and destructiveHint=false, so the agent knows this is a non-destructive, potentially idempotent operation. The description adds that it includes conversation for reproduction, but does not disclose what happens after reporting (e.g., ticket creation, logging). Thus, it adds some but not substantial behavioral context.

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

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

The description is a single sentence that efficiently conveys purpose and usage guidance. It is front-loaded with the purpose and ends with the key guidance on conversation. 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 simplicity (3 parameters, no output schema, annotations present), the description is largely adequate. It covers the main purpose and provides a crucial usage hint. However, it does not mention authentication requirements or what happens after submission, which could be useful.

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. The description adds meaning to the 'conversation' parameter by specifying its role in reproduction. However, 'context' and 'message' parameters are not explained. This partially compensates but leaves gaps.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It specifies the action (report) and the resources (bug, missing feature, feedback). This distinguishes it from sibling tools which are primarily financial data operations or authentication.

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

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

The description provides clear context: 'Include the conversation array with recent messages for reproduction.' This gives explicit usage guidance. Although it does not explicitly state when not to use, the sibling tools are unrelated, so there is no ambiguity about when to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the exact information returned (platform and adapter versions), which is beyond what the annotations provide.

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

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

The description is a single sentence with 8 words, extremely concise and front-loaded. Every word is necessary and adds value, meeting the criterion that every sentence should earn its place.

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

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

For a simple version retrieval tool with no parameters, the description is complete. It fully explains what the tool does, and no output schema is needed as the return value is obvious from the description.

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 according to guidelines, a baseline of 4 is appropriate. The description correctly indicates no input is needed, and the schema coverage is 100%, so no additional parameter information 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 uses a specific verb 'Show' and clearly identifies the resource: 'MCP platform and adapter versions.' It effectively distinguishes from sibling tools which are all about authentication, finance operations, or other functionalities.

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 or not use this tool, but the context makes it obvious. The tool's purpose is self-explanatory, and there are no alternative version tools among siblings, so implicit usage is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful behavioral context by specifying exactly what will be returned (installed MCPs, connection status, accounts, catalog tool counts), which goes beyond the annotations. It does not contradict 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, well-structured sentence that front-loads the primary purpose and lists the key information it returns. Every phrase earns its place, with no redundancy or unnecessary filler.

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

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

With no output schema, the description provides a comprehensive overview of the return contents, covering the main aspects one would need. However, it omits minor details such as exact field names or error behavior, which for a simple info tool is acceptable but not fully exhaustive.

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

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

The tool takes zero parameters, so the description need not add parameter details. Per baseline for 0 params, score is 4. The description adds no parameter semantics because none exist.

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

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

The description clearly states the tool 'Returns the current toolkit state' and enumerates specific details (installed MCPs, connection status, accounts, catalog tool counts). This specific verb+resource structure distinguishes it from sibling tools such as openfinance_list_accounts or connect, which focus on specific actions or data.

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

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

The description implies usage for checking overall toolkit status but does not explicitly state when to use it versus alternatives (e.g., for detailed account info use openfinance_list_accounts). It provides clear context but no exclusions or alternative references.

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