RecargaPay MCP

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

Beyond the annotations, the description reveals that a config header provides a 'permanent, non-expiring connection' while pasting a token gives 'session-only login'. This adds valuable behavioral context about persistence and authentication state.

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 and front-loads the main purpose. Some phrasing is slightly awkward ('MCP.AI for IDE agents (Cursor, etc.)'), but it contains no fluff and each sentence earns its place.

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

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

For a one-parameter authentication tool with no output schema, the description covers the essential flow: browser login, token acquisition, and the two ways to use the token. It could mention error handling or token expiration, but is sufficiently complete for the intended use.

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

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

With 0% schema description coverage, the description fully compensates by explaining the 'token' parameter is a JWT obtained from the browser, how to pass it, and that calling with no args returns the login link. This adds all necessary meaning beyond the schema.

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

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

The description clearly states the tool authenticates the MCP server for IDE agents by logging in via browser and copying the access token. It distinguishes this from the sibling 'connect' tool by focusing specifically on authentication, though it does not explicitly name alternatives.

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 instructions: call with no args to get the link, call with a token for session-only login, or add the token to server config for permanent login. This provides clear context but does not mention 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 goes beyond the read-only and idempotent annotations by detailing conditional return values: authenticated:true with empty pending[] when all providers are connected, and connect_url plus per-install URLs when credentials are missing. This adds useful behavioral context 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 two sentences, front-loaded with the core purpose, and each sentence adds distinct value. There is no redundancy or 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?

For a simple zero-parameter read-only tool, the description covers key return states and URLs. Without an output schema, it carries the burden of explaining return values, and while it does not enumerate every possible field, it provides sufficient context for the common scenarios.

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

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

The tool takes zero parameters, so the schema has no properties to annotate. Per the baseline rule for 0 parameters, a score of 4 is appropriate; the description does not need to add parameter explanations.

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 function with a specific verb and resource: "Returns connection status and URLs." It explains two distinct output scenarios, but it does not explicitly differentiate this tool from siblings like openfinance_list_connections, so it misses the highest bar.

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 and retrieving connect URLs, and it provides context based on connection state. However, it does not explicitly state when to use this tool versus alternatives (e.g., authenticate for initiating connections), nor does it provide exclusions.

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

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

The description goes well beyond annotations (readOnlyHint=false, destructiveHint=false) by revealing key behavioral traits: invoke works even when the MCP is not installed, runs one-off without bloating the toolkit, returns connect/checkout links for auth or payment, and states that writes require workspace owner/admin. This adds valuable context on side effects, permissions, and edge cases.

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 highly structured: it opens with a clear definition, then describes the core flow, the key invoke caveat, install vs invoke trade-offs, permission requirements, and finally the prompt library. Every sentence adds essential information, and the most critical guidance (KEY: invoke...) is front-loaded. The length is appropriate 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 massive scope (14 actions, 23 params, no output schema), the description is surprisingly thorough. It explains the main flows, auth/permission requirements, and the prompt library. However, it does not describe the return format for core actions like search (what does a search result look like?) or list_tools (what is 'callable right now'?), which would be valuable since there is no output schema. Still, it covers most critical contextual aspects.

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

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

With 23 parameters and 0% schema description coverage, the description carries a heavy burden. It explains the action enum (search, describe, invoke, install, etc.) and relates parameters like mcp_id, tool_id, arguments, prompt_vars, and prompt_slug to specific actions. However, it does not systematically document all params (e.g., limit, query, immediate, tier_slug, cancel_reason), leaving some ambiguity. Despite this, the core workflow params are well covered.

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 this tool is the official mcp.ai marketplace, a catalog of MCPs/tools and the way to run them. It uses specific verbs (search, describe, invoke, install, list_tools) and resources (MCPs, prompts, billing), effectively distinguishing it from sibling tools like openfinance_* or show_version.

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 each action: 'Core flow: action=search discovers MCPs by intent → describe returns one MCP's full profile ... so you pick the right tool_id → invoke RUNS that tool.' It also contrasts invoke vs install, stating 'prefer invoke for a single/occasional use' and 'Use install only to make an MCP PERMANENT'. This is clear, actionable usage guidance with 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 mark destructiveHint, and the description adds valuable context: it deletes connection data, makes bank data unavailable, and returns a re-connect URL. This goes beyond the annotation by specifying what gets destroyed and the return behavior.

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

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

The description is concise, using two sentences with no redundant information. It front-loads the primary action and then efficiently conveys consequences and return 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?

Although the tool appears simple, the description is incomplete due to the undefined 'item' parameter, which is critical for correct invocation. The return value is partially described (add_connection_url) but not the full response structure, and there is no guidance on prerequisites or side effects beyond what annotations already convey.

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 defines a single 'item' string parameter with no description, and the tool description does not clarify what 'item' refers to (e.g., bank ID, connection ID). With 0% schema coverage, the description completely fails to compensate, leaving the agent without essential invocation information.

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

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

The description uses a specific verb 'Revokes' and clearly identifies the resource 'Open Finance consent' for a specific bank, making it distinct from sibling tools like connect and authenticate. It also states the destructive consequence 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 its use for disconnecting a bank but does not explicitly state when to use it versus alternatives. No exclusions or comparisons with sibling tools like openfinance_list_connections are provided, though the mention of add_connection_url hints at reconnection.

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 fully discloses the behavioral profile: it PATCHes, polls up to ~60s, advances `lastUpdatedAt`, sets `synced`, reports `needs_action` with `reconnect_url`, and handles `timed_out`. Despite lacking annotations, it covers side effects, auth requirements, and operational nuances with no contradiction.

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

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

The description is long but every sentence earns its place, covering purpose, usage, parameters, return shape, error states, and timing. It is front-loaded with the core action and progressively adds necessary detail without fluff. Structure is logical and scannable.

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

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

Given the tool's complexity (sync, polling, auth failures, reconnect flow) and the absence of an output schema, the description is exceptionally complete. It explains results, errors, status fields, actionable `needs_action` states, timeout behavior, and fallback alternatives. No critical information is missing.

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

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

Schema coverage is 0% but the description fully compensates. It explains `items` as selectors (item_id, connector_id, connector_name, custom_label) and clarifies that omitting it syncs all connections. `wait` is described as controlling blocking vs fire-and-forget. This adds substantial meaning beyond the bare schema types.

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+resource: 'Forces the bank to re-sync one or more connections NOW and WAITS for it to finish.' It clearly distinguishes from siblings by explicitly stating 'WITHOUT disconnecting/reconnecting' and contrasting with stale reads. The scope (specific connections vs. all) is also clearly defined.

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

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

Explicit when-to-use guidance is provided: 'Use this when a balance or transaction list looks stale.' It also tells when not to use it (rather than disconnecting/reconnecting) and names an alternative for timeout handling ('re-check with openfinance_get_item_status'). The `wait: false` fire-and-forget option is also clearly explained.

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

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

Beyond the annotations (readOnly, idempotent), the description discloses important edge-case behavior: structured warnings for credit accounts, graceful degradation to last-synced balance with realtime:false, and the precise response shape. This gives the agent a full picture of potential outcomes without surprises.

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 adds value: core purpose, parameter constraint, and edge-case handling. It is well-structured and front-loaded, with no filler or repetition.

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 defines the response shape `{ results, errors }` and covers both warning and degradation scenarios. This makes the tool's behavior predictable and complete for an agent to invoke and interpret 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?

The schema only lists account_ids as an array of strings with no description. The description adds the array size limit (1–50) and clarifies that it works 'per account id,' providing meaningful semantics that compensate 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 opens with a clear, specific verb and resource: 'Returns real-time balance payload per account id' and includes the exact endpoint (GET /accounts/:id/balance). This distinguishes it from sibling tools focused on listing accounts or other open finance operations, and avoids any tautology.

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 operational guidance: pass account_ids as an array limited to 1–50, and explains expected behavior for credit accounts and upstream failures. It doesn't explicitly name alternative tools or state when not to use it, but the context is strong enough to guide selection.

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 a safe, read-only, idempotent operation. The description adds substantial behavioral context beyond annotations, including the batch result shape `{ results, errors }` and a critical warning about provider incidents affecting data reliability, with explicit instruction not to present those values as real. This is high-value 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 compact but information-dense, with each sentence serving a purpose: what it returns, how to call it, the response shape, and a critical reliability caveat. No filler or redundancy, and it is well-structured for quick parsing.

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 batch complexity and the potential incident warnings, the description is thorough. It covers the return structure, parameter constraints, and a quality caveat that would be otherwise absent with no output schema. It provides sufficient context for an agent to use the tool correctly and 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?

The schema only defines account_ids as an array of strings. The description enriches this by specifying the accepted range (1–50), the array requirement, and that it corresponds to account IDs per the endpoint, plus the batch response behavior. 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 uses a specific verb 'Returns' with a clear resource ('full account objects') and scope ('per id'), distinguishing it from list endpoints by emphasizing the extended creditData and the GET /accounts/:id endpoint. This effectively differentiates it from siblings like openfinance_list_accounts.

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 clearly explains how to use the tool ('Pass `account_ids` as an array (1–50)') and its batch behavior, giving a strong sense of when it applies. It does not explicitly name alternatives or exclusion criteria, but the 'per id' scope implies a contrast with list tools, making the context clear enough for an agent.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds valuable behavioral context: the batch shape ({ results, errors }), the Pluggy limitation (no paid/status field), the meaning of payments[] in Brazilian Open Finance, and the caution against reconstructing totals from transactions. This is rich context beyond annotations and contradicts nothing.

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?

Although the description is long, every sentence adds value: main purpose first, then limitations, parameter guidance, and domain-specific caveats. It is well-structured and front-loaded, with 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 no output schema, the description explains return fields and error shape. It covers critical usage caveats and provides enough context for correct invocation, including how to discover valid ids and how to interpret payments. It is complete for an agent to use the tool safely and effectively.

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 only says bill_ids is an array of strings. The description adds crucial semantics: it must be an array, ids should be discovered via openfinance_list_credit_card_bills, and it clarifies the parameter's role. With 0% schema coverage, this fully compensates.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by id, and lists the specific fields (financeCharges, payments[] with sub-fields). It explicitly distinguishes itself from openfinance_list_transactions by noting it does NOT return individual transactions, 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 provides explicit when-to-use and when-not-to-use guidance: use this for bill-level detail; use openfinance_list_transactions for itemized transactions. It also instructs to call openfinance_list_credit_card_bills first to discover ids, and warns about interpreting payments[] in Brazilian Open Finance, giving clear contextual direction.

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 significant behavioral context beyond annotations: the reconnect_url behavior (reopens widget in UPDATE mode, no disconnection, no slot consumption), the difference in response shape between omitting and passing `item`, and the bulk execution behavior. This is exactly the type of context an agent needs.

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: a first sentence states core functionality, followed by usage variations and bulk support. Every sentence adds value—no fluff or redundancy. It is information-dense but still easy to parse.

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?

This is a read-only, idempotent tool without an output schema, so the description must handle return-value explanation. It does mention key fields (status, executionStatus, connector metadata, reconnect_url) and the list response shape (`{ count, items }`), but it does not specify the exact response shape for a single item or clarify the `item_id` parameter. Slightly incomplete but mostly sufficient.

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 `item` (single vs. all) and `item_ids` (bulk), but does not explain `item_id` at all, nor its relationship to `item`. This leaves one of three parameters ambiguous, so compensation is only partial.

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 a specific verb ('Returns') with a specific resource ('bank connection') and enumerates the fields returned (status, executionStatus, connector metadata, reconnect_url). It distinguishes itself from sibling list tools by mentioning the reconnect functionality and bulk support, making the purpose unambiguous.

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

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

The description gives clear context for single vs. all banks ('Omit `item`... pass `item`') and mentions bulk support with `item_ids`. It does not explicitly name alternative tools or state when not to use it, but the usage scenarios are implied strongly enough to guide an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by disclosing the batch response shape ('{ results, errors }') and enumerating the returned fields. This goes beyond the annotations without contradicting them.

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

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

Three sentences deliver the core function, usage context, and parameter semantics without redundancy. The field enumeration is dense but directly relevant to what the agent needs to understand the return payload.

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 takes on the burden of explaining the complex return structure, listing key fields (interestRates, installments, CET, etc.). It also covers the batch shape and parameter constraints, making the tool well-specified for a read-only operation.

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 only defines loan_ids as an array of strings. The description adds the 1-50 count constraint and clarifies that these are loan contract IDs from a prior list, providing necessary context that the schema lacks (schema description coverage is 0%).

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 'Returns full loan contract detail by id' – a specific verb and resource. It also distinguishes from siblings by explicitly referencing openfinance_list_loans as the precursor, making the tool's unique role clear.

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

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

The description provides explicit usage guidance: 'Use after openfinance_list_loans to deep-dive on a specific contract.' It also specifies the parameter count limit ('Pass loan_ids as an array (1-50)'), leaving no ambiguity about when and how to use the 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, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context beyond that: the account `name` is the legal entity rather than the brand, CREDIT balance meaning is connector-dependent, provider_incident can make balances unreliable, and identity_notice requires deduplication by account number. No contradiction with annotations.

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

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

The description is long but dense and front-loaded; the first sentence captures the core return type, followed by necessary caveats and edge cases. Every paragraph covers a distinct and important aspect: naming, filtering, credit balance caveats, provider incidents, identity notices, and bulk support. 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?

With no output schema and no parameter descriptions in the input schema, the description carries the full contextual burden. It covers response shape, parameter behavior, edge cases, alternative tools, and special blocks like provider_incident and identity_notice. It is more than sufficient for an 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?

Input schema property descriptions are 0% covered, so the description must compensate. It richly explains `item` (omit vs pass), `item_ids` for bulk execution, and the meaning of `type` is partially tied to BANK/CREDIT in the return description. However, the singular `item_id` parameter is never explicitly addressed, and `type` filtering semantics are implied rather than directly stated.

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 accounts for a bank connection: BANK (checking/savings) and CREDIT (credit card) with balance, number, type, subtype, bankData, and creditData.' It clearly distinguishes itself from sibling tools by naming openfinance_list_credit_card_bills as the alternative for standardized bill amounts and by clarifying the bank/name distinction.

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 gives explicit when-to-use guidance: 'OMIT item to list accounts across ALL linked banks at once' and 'Pass item to target a single bank.' It also names an alternative tool for a related but different need, saying 'use openfinance_list_credit_card_bills' for a standardized open-bill amount and total debt, making the decision boundary 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 the readOnlyHint/idempotentHint annotations, the description discloses that the result is 'cached for the adapter session' and that it is a 'single aggregated response — no batch ids'. This adds behavioral context about caching and response shape, which annotations do not 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 two sentences, front-loaded with the primary action, and every sentence adds value: the first states purpose and caching; the second enumerates the response fields and their usage. 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?

With no output schema, the description fully covers the return structure, including field meanings, language preferences, parent relationships, and caching. It also links to a sibling tool via the categoryId, making the description self-sufficient for an AI agent.

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

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

The tool has zero parameters (schema coverage 100% trivially), so the baseline is 4. The description doesn't need to explain parameters; it instead enriches the output semantics by detailing fields like 'id', 'description', 'descriptionTranslated', etc.

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 'Pluggy's transaction category taxonomy (GET /categories)', which is a specific verb+resource. It is distinct from sibling tools like openfinance_list_transactions, which list transactions rather than categories.

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 context by noting that the 'id' is the categoryId used by openfinance_update_transaction_category, implying the taxonomy is a prerequisite for that tool. It doesn't explicitly state when to use it vs. alternatives, but no direct alternative exists in the sibling list, so this 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?

While annotations already declare readOnlyHint=true and destructiveHint=false, the description adds significant behavioral context: it explains the exact behavior of reconnect_url (reopens widget in UPDATE mode, refreshes data in place, does NOT consume a slot, no disconnect needed) and the add_connection_url purpose. This goes well beyond the annotations and provides valuable implementation detail without contradiction.

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

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

The description is two sentences, front-loaded with the core purpose, and includes no filler. The second sentence adds necessary detail about the reconnect_url's behavior and use cases. While slightly dense, every clause earns its place, and the structure is logical.

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 (0 parameters, no output schema), the description is exceptionally complete. It names the return fields, explains the meaning and behavior of the two URLs, and gives concrete conditions for using the reconnect URL. The annotations cover safety, and the description fully covers what a caller needs to know about the response and side effects.

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 the schema coverage is 100% (empty object), so there are no parameter semantics to add. Per the rubric, 0 params earns a baseline score of 4. The description does not need to explain parameters; it appropriately focuses on return values and behavior.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Returns the saved bank connections for this install.' It further lists the exact return fields (connector_id, item_id, bank name, reconnect_url, add_connection_url), distinguishing it from sibling tools that list accounts or transactions. The purpose is unambiguous and well-scoped.

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

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

The description explicitly explains when to use the reconnect_url: 'use it when a connection needs re-authentication (MFA connectors, LOGIN_ERROR, stale non-Open-Finance data).' It also clarifies that calling the reconnect URL does not consume a slot or require disconnecting first. However, it doesn't explicitly contrast this tool with sibling tools like openfinance_get_item_status or openfinance_force_sync, though the distinct purpose implies the right context.

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

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

Goes far beyond annotations by detailing non-standard Open Finance semantics: payment lifecycle mapping across cycles, derived payment_status with PAST_DUE_UNCONFIRMED caveats, connector asymmetry for open_bill, bill_grouping_reliability warning, and the warning instead of failure behavior. All consistent with readOnlyHint/idempotentHint.

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 structured with uppercase section headers (IMPORTANT, OPEN BILL & TOTAL DEBT, CONNECTOR ASYMMETRY), and each section adds essential caveats. Slightly verbose, but all sentences carry meaningful content and the structure aids navigation.

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 must fully specify returned data: it lists core fields, derived aggregates, payment_status values, open_bill structure, future_bills projection, account echo, and reliability warnings. It covers the complex Open Finance semantics thoroughly.

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

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

The description enriches the schema by explaining the non-obvious `include_open_bill` parameter (opt-in, default false) and `account_ids` for batch execution. The remaining parameters (`account_id`, `page`, `page_size`) are self-evident but lack explicit description; schema coverage is 0%, so some burden remains.

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 opens with a specific verb and resource: 'Returns CLOSED credit card bills for a CREDIT-type account' and enumerates the returned fields. It distinguishes from sibling tools by explicitly directing users to openfinance_list_transactions for itemized purchases/charges.

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 alternatives: 'To see itemized purchases/charges, use openfinance_list_transactions with the CREDIT account_id'. Also advises against using the CREDIT account's balance for pending debt, recommending derived open_bill/total_pending_debt instead, and clarifies when include_open_bill should be set.

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?

Descriptions goes far beyond annotations by disclosing error handling (returns { total:0, results:[], warning } on 403/upstream errors), a detailed data integrity cross-check that flags rows as suspect_zeroed, and bulk support via item_ids. These are meaningful behavioral traits not captured by readOnlyHint/idempotentHint/destructiveHint.

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

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

The description is long but front-loaded with a clear purpose and structured into logical sections (return fields, error behavior, data integrity, bulk support). While it could be trimmed, every sentence adds substantive value, and the data integrity callout is crucial.

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 covers return fields, error responses, and data integrity warnings well. It does not explicitly describe pagination or navigation behavior, but the presence of page and page_size parameters implies it, and the description is otherwise thorough for a list endpoint.

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% property descriptions, so the description must compensate. It only explains item_ids (bulk support) and leaves item, page, page_size, type, and item_id semantically unexplained. Enum values in the schema are self-explanatory, but most parameters rely on name inference alone.

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

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

The description explicitly states it returns the investment portfolio for a connection, enumerating asset types (FIIs, stocks, ETFs, fixed income, mutual funds, retirement, COE). This clearly differentiates it from sibling tools like openfinance_list_investment_transactions, which focus on transactions rather than holdings.

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 context: use for a broker/bank with INVESTMENTS product enabled, and even explains fallback behavior when the product is not enabled (returns warning instead of throwing). However, it does not explicitly name alternative tools or give when-not-to-use scenarios.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral context: lists the transaction types, example fields (quantity, value, netAmount, agreedRate, brokerageNumber, itemized expenses), and notes bulk execution. 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?

Two short paragraphs with no filler. The first sentence states purpose, the second details return fields, the third gives usage order, and the fourth covers bulk support. Every sentence earns its place.

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

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

With no output schema, the description enumerates the row fields and expense categories fairly thoroughly. However, it does not clarify pagination behavior or the exact structure of the 'expenses' object, leaving some ambiguity for a read-only tool.

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

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

The schema has 0% description coverage. The description explains investment_id (get from list_investments) and investment_ids (bulk), but completely omits page and page_size parameters. This is only partial compensation for the schema 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, enumerating transaction types (BUY/SELL/TAX/etc.) and specific fields. This clearly distinguishes it from sibling tools like openfinance_list_transactions and 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?

The description explicitly instructs to use the tool after openfinance_list_investments to obtain investment_id, and mentions bulk support via investment_ids. This provides clear context, but it does not explicitly exclude alternatives or state when not to use it.

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

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

The description adds behavioral details beyond the annotations: 'multiple connections are queried sequentially with rate-limit spacing' and 'Returns `{ results, errors }` per connection'. These traits (rate limiting, error handling, sequential processing) are not disclosed by the annotations (readOnlyHint, idempotentHint, etc.), providing valuable operational 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 two concise sentences. The first sentence states the purpose, the second explains parameter usage and return format. No wasted words; every 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?

Given the tool has only 1 optional parameter, no output schema, and annotations already cover safety and idempotency, the description is complete. It explains the two invocation modes (specific connections vs. all), the return shape, and rate-limit behavior. There is no missing information needed for an agent to use 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?

Schema description coverage is 0% and the schema only defines `items` as an array of strings. The description compensates fully by explaining that `items` is an array of connection selectors (item_id uuid, connector_id, or connector_name), one per connection, and describes the behavior when omitted. This gives complete meaning to the parameter 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 the tool's purpose: 'Lists loan contracts per bank connection (GET /loans)'. This is a specific verb ('Lists') and resource ('loan contracts per bank connection'), and it distinguishes the tool from sibling tools like openfinance_list_accounts or 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 explicit usage context: 'Pass `items` as an array of connection selectors' and 'OMIT `items` to list loans across ALL linked banks'. This tells the agent exactly how to invoke the tool for specific connections vs. all connections. However, it does not explicitly mention when not to use this tool or name alternatives, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and the description adds extensive context: per-connector inconsistency of billId, PENDING vs POSTED variability, auto-pagination vs manual, upstream error returning { total:0, results:[], warning, error }, provider_incident block, and account echo for multi-bank safety. 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 long but appropriately sized for the tool's complexity. It is front-loaded with the core purpose and credit-specific caveats, followed by pagination and detail levels. Minor redundancy exists (billId caveat repeated in the detail:'rich' section) but overall every section earns its place.

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

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

With no output schema, the description fully characterizes the response: account echo block, results array, truncated flag, warning/error fields, detail-level fields, and provider_incident. It also covers edge cases (0 transactions, credit card sync failure) and names sibling tools for follow-up, making it highly complete for an agent to invoke 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 explains every parameter in depth: from/to (ISO YYYY-MM-DD), search_queries (case/accent-insensitive substring, OR semantics), page/page_size (manual vs auto-pagination, defaults, max values), detail (compact/rich/raw with field details), and account_ids (bulk support). account_id is implied by 'Returns transactions for a bank account' and the account echo block.

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 opens with 'Returns transactions for a bank account (BANK or CREDIT type)', which is a specific verb+resource. It clearly distinguishes from siblings by noting it is 'the ONLY way to get itemized transactions' for credit cards and naming openfinance_list_credit_card_bills as the alternative for 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?

Provides explicit when-to-use and when-not-to-use guidance: 'For CREDIT (credit card) accounts, this is the ONLY way to get itemized transactions', 'To get a standardized open-bill total / total debt regardless, use openfinance_list_credit_card_bills', and 'For the card's statement closing/due dates use openfinance_list_accounts'. Also gives detailed guidance on when to use detail='compact' vs 'rich' vs 'raw'.

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 and idempotentHint, but the description adds substantial behavioral context: it fans out to all accounts internally, scans cap at 5000/account with a truncated flag, may include a provider_incident block, and supports batched execution. It also explains that if provider incident is present, data may be incomplete/wrong, which is valuable risk disclosure beyond the safety hints.

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 every sentence carries critical meaning, no fluff. It leads with the primary purpose, then usage, then parameter details, then caveats, and finally bulk support. The use of bold and short clauses improve readability. Despite its length, it is efficiently structured for a tool with this complexity.

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

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

Given the tool has no output schema, the description must explain return values, and it does so thoroughly: mentions total entradas/saídas/saldo_liquido, monthly evolution, top expenses/revenues, by_account breakdown, and raw rows with merchantInfo and creditCardMetadata. It also covers edge cases like truncation and provider incidents, and the ability to batch with item_ids, making it complete for agent decision-making.

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 9 parameters with no description coverage, but the description explains nearly all of them: item (connector_id, connector_name, or item_id) and omission semantics, from/to as ISO dates, granularity (monthly vs raw), detail (rich vs raw), type (BANK/CREDIT), and item_ids for batch. It even clarifies what returns are affected by these parameters (e.g., rich adds merchantInfo).

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 a consolidated cash-flow analysis for a whole bank connection, with a specific verb ('list'/'analyze') and resource ('transactions by item'). It differentiates from siblings by stating it resolves accounts internally and eliminates the need for prior account listing calls, and even mentions the alternative of omitting item to analyze all banks, which is a unique scope.

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

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

It explicitly states when to use the tool (e.g., 'análise anual/mensal', 'fluxo de caixa'), provides guidance on when to omit vs. provide item, describes difference between monthly and raw granularity, and even gives a 'heavy' warning for raw mode. It also names an alternative action ('do NOT need to call openfinance_list_accounts first'), which is a clear usage directive.

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 the safety profile is known. The description adds meaningful context about the return fields (global indicator, degraded components, open incidents, your_banks_affected) and the live nature of the check, going beyond the minimal read-only hint. 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 efficiently structured: it opens with the core purpose, provides a clear use case with examples, and finishes with return values. Every sentence contributes value without redundancy, making it appropriately sized for the 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?

Despite having no output schema, the description explicitly lists the return contents: global indicator, degraded components, open incidents, and your_banks_affected. Combined with strong annotations and clear usage guidance, the description fully equips the agent to use the tool correctly.

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

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

The input schema has no parameters, which makes parameter semantics trivial. The description doesn't need to explain any parameters, and the baseline score of 4 for zero-parameter tools applies.

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

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

The description clearly states the tool checks the LIVE operational status of the Open Finance provider, using a specific verb and resource. It explicitly distinguishes itself from the sibling tool `openfinance_get_item_status`, eliminating ambiguity.

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 conditions: 'Use it whenever data looks incomplete or stale even though a connection shows UPDATED' and explains how to differentiate provider-side problems from connection issues. It also names the alternative tool to use for connection-specific status.

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. The description adds substantial behavioral context: returns user-linked connections, hides PJ banks on PF plans, treats PJ plans as covering both, returns a hint if keywords are missing (never dumps the catalog), and surfaces caveat warnings for non-Open-Finance connectors.

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 with useful detail but somewhat long for two parameters. Every sentence carries information, but the flow could be tighter. Still, it is well-structured and front-loaded with the core 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 sparse schema and lack of output schema, the description is remarkably complete. It covers return values, edge cases (missing keywords, non-Open-Finance caveats), plan logic, and the intended workflow placement. Nothing essential is missing.

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

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

The schema provides only property names with no descriptions (0% coverage). The description fully compensates by explaining keywords[] with an example and its requirement, and include_accounts for including accounts. It also notes the behavior when keywords are omitted.

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 the available bank connectors by name' and lists the specific return fields (connector id, access, audience, links, connect_url). It is easily distinguished from siblings like 'connect' or 'marketplace' by focusing on search and pre-connect discovery.

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 instructs to 'Call this BEFORE connecting' to obtain a one-click link, and advises preferring Open Finance connectors for automation by surfacing caveats. It also clarifies plan-based visibility, giving the agent clear context on when to use this tool versus alternatives like 'connect'.

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 the annotations: it overrides Pluggy's automatic categorization, automatically creates a Category Rule, and affects future similar transactions. It also explains batch behavior with per-item errors, which is not visible in the annotations. There is no contradiction 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 well-structured and information-dense but not bloated. Each sentence serves a purpose: purpose, parameter format, side effects/usage, and return shape. It is front-loaded with the core action and efficiently packs critical 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?

The description is complete for a complex batch mutation tool with side effects. It covers the parameter structure, source of IDs, the side effect of creating rules, and the exact return shape, which is especially important given there is no output schema. It also references sibling tools for data sourcing, providing full context.

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

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

The schema only defines 'items' as an array without any field descriptions (0% coverage). The description compensates fully by detailing the item structure as { transaction_id, category_id } and specifying that transaction_id comes from openfinance_list_transactions and category_id from openfinance_list_categories, adding essential 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 clearly states the tool's action: 'Corrects the category of one or more transactions' and identifies the HTTP method (PATCH /transactions/:id). It is unambiguous and distinguishes the tool from sibling list/sync 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?

The description provides explicit usage instructions: it tells users to pass an array of { transaction_id, category_id }, explains where to source each ID, and states when to use it ('use this to fix miscategorized transactions'). It also explains the side effect of teaching Pluggy for future transactions, giving clear context for appropriate 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?

Annotations already indicate idempotent and non-destructive behavior. The description adds that this is a reporting action and mentions including conversation for reproduction, but does not disclose other behavioral traits like rate limits or what happens after submission. 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 two concise sentences, front-loaded with the primary purpose and followed by a specific instruction for a key parameter. Every word contributes, with no redundancy or unnecessary detail.

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

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

For a simple feedback tool with no output schema, the description covers the essential purpose and the most important parameter. The optional 'context' parameter is not explained, but its optional nature and default value reduce the impact of this omission.

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 compensates by explaining the 'conversation' parameter's role for reproduction and implying that 'message' contains the report text. However, the 'context' parameter is left unexplained, leaving a partial 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 clearly states the tool's purpose with a specific verb ('Report') and defines the resources: bug, missing feature, and feedback. It distinguishes itself from all sibling tools, which are focused on financial operations or authentication, making the unique purpose obvious.

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

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

The description provides clear context for when to use the tool: reporting bugs, missing features, or sending feedback. It does not explicitly mention when not to use it or alternatives, but the sibling tools are unrelated, so the intended use is unambiguous.

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, establishing a safe read-only profile. The description does not add behavioral context beyond that, such as return format or authentication requirements, though it does add resource scope.

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, front-loaded sentence conveys the action and target without any filler. The description is perfectly sized for the tool's simplicity.

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 version tool, the description is fully complete: it tells the agent exactly what information will be retrieved. No output schema exists, but the output (platform and adapter versions) is self-evident 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 the input schema is fully described (empty properties). Baseline 4 applies to no-parameter tools, and the description provides no additional parameter information because none 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 uses a specific verb 'Show' and names the exact resource ('current MCP platform and adapter versions'), making the tool's purpose unmistakable. It clearly differentiates from sibling tools like 'connect' or 'marketplace' that serve unrelated functions.

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

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

The description implies usage (when version information is needed) but does not explicitly state when to use this tool over alternatives or mention any exclusions. For a simple info tool this is acceptable, but it falls short of explicit guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds valuable context on the exact data returned, which is not available in the schema. It doesn't disclose additional behavioral traits like rate limits or authentication, but for a simple read-only state tool this is acceptable.

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 with no fluff. It concisely lists the contents of the returned state, making every word informative.

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

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

Given the tool's simplicity (no parameters, no output schema), the description fully explains what the tool returns and when it's relevant. It covers the essential information an agent needs to invoke and interpret the result.

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

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

The tool has 0 parameters, so the schema is vacuous. Per guidelines, baseline is 4 for no parameters. The description doesn't need to add parameter semantics, and none are expected.

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 with a specific verb ('Returns') and resource ('current toolkit state'), and enumerates the exact contents (installed MCPs, connection status, accounts, catalog tool counts). This distinguishes it from sibling tools that focus on individual operations like authentication or listing accounts.

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

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

The description provides clear context for when to use the tool: whenever an overview of the toolkit state is needed. It does not explicitly mention alternatives or exclusion criteria, but the purpose is so specific that the use case is immediately understood. This meets the 'clear context, no exclusions' level.

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