SafraPay MCP

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

The description adds value beyond annotations by explaining the two modes (no args returns link, token arg authenticates). It aligns with idempotentHint and destructiveHint false, and does not contradict annotations. It gives a clear behavioral overview.

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 (2 sentences), front-loaded with essential info, and avoids redundancy. It efficiently covers purpose, audience, and usage patterns without 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 simple tool with one parameter and no output schema, the description is nearly complete. It explains the authentication flow, permanent vs session tokens, and calling conventions. Minor omissions (e.g., error handling) do not significantly detract.

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

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

Despite 0% schema description coverage, the description thoroughly explains the 'token' parameter: it's a JWT access token, and it describes how to obtain and use it. This compensates for the lack of schema documentation.

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 users for MCP.AI IDE agents, explaining login and token handling. It distinguishes itself from sibling tools like 'connect' and 'marketplace' by focusing solely on authentication.

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

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

The description provides explicit context: logging in via browser, copying token, adding to config for permanent connection, or pasting for session login. It also specifies calling with no arguments to get the link. It does not explicitly state when not to use it, but the usage scenarios are clear.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true. The description adds value by explaining the return payload in two scenarios, which goes beyond the annotations.

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

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

Two sentences, no wasted words. Front-loaded with the purpose, then provides specific detail. Excellent conciseness.

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

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

Given no parameters and no output schema, the description covers the main scenarios. Could clarify 'all providers' scope, but is generally complete for a status check tool.

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

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

No parameters exist, and schema coverage is 100%. The description does not need to add parameter info; baseline 4 is appropriate.

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

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

The description clearly states that the tool returns connection status and URLs, distinguishing between fully connected and missing credentials states. It is specific and distinct from sibling tools like 'authenticate'.

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

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

The description implies when to use (to check connection status) but does not explicitly state when not to use or provide alternatives among siblings. Simple but lacking comparative 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?

Discloses key behaviors: invoke runs tools even when not installed, returns connect/checkout links on needed auth/credits, install/uninstall/subscribe/cancel require owner/admin, and search/describe flag installation status. Annotations already indicate mutation (readOnlyHint=false) so the description adds valuable context without contradiction.

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

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

The description is long but front-loaded with the core flow and key distinctions. However, some redundancy exists (e.g., repeated explanations of install vs invoke) and the length could be trimmed while preserving clarity.

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

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

Covers all actions and edge cases (connect links, checkout, ownership requirements) for a complex 15-parameter tool with no output schema. The missing parameter descriptions are the main gap, but the overall workflow is well explained.

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

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

Schema has 15 parameters with 0% description coverage, but the description only explains the 'action' parameter implicitly and mentions a few others (query, mcp_id, tool_id, arguments) in context. Many parameters like limit, immediate, tier_slug, conversation, request_name, cancel_reason are not explained at all, making it hard for the agent to construct valid invocations.

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 is the official mcp.ai marketplace, enumerates its core actions (search, describe, invoke, install, etc.), and distinguishes it from external registries and sibling tools like openfinance_* by positioning it as the first tool to use for capability 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 use this tool first before external registries, and provides detailed guidance on when to use invoke (one-off) vs install (permanent), handling of credentials/wallet, and explains other actions like list_tools, subscribe, cancel, report_bug, request_mcp.

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 and readOnlyHint=false. The description adds value by stating the consequence (data deleted) and the return of a re-connection URL, exceeding annotation info.

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, direct and without unnecessary words. Every sentence adds essential information: action, consequence, 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?

Given the tool has one parameter, no output schema, and destructive annotations, the description covers behavior and returns but lacks parameter documentation. It is adequate but has a clear gap in explaining the 'item' parameter.

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

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

With 0% schema description coverage and only one parameter 'item', the description does not explain what 'item' refers to. It should specify it's a bank identifier. The description fails to compensate for missing schema documentation.

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 revokes consent and deletes connection data for a specific bank, using specific verbs and resource. It distinguishes from siblings like 'openfinance_list_connections' by focusing on disconnection 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?

It explains the effect (data no longer available) and provides a re-connection URL, indicating when to use and what to expect. Lacks explicit 'when not to use' or alternatives, but context is clear.

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

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

Discloses key behaviors beyond annotations: waits up to 60s, polls for completion, returns detailed response fields (status, executionStatus, lastUpdatedAt, synced, needs_action with reconnect_url), and timeout handling. Annotations only show readOnlyHint=false, so description fully compensates.

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 but well-structured: main action first, then usage, parameters, response fields, and edge cases. Every sentence adds value, though slightly verbose; could be broken into shorter sentences for 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 the tool's complexity (2 params, no output schema, many siblings), the description covers behavior, parameter semantics, response details, error modes (needs_action, timed_out), and alternatives. Fully equips an agent to use the tool correctly.

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

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

With 0% schema description coverage, the description fully explains both parameters: wait as boolean for fire-and-forget, items as array of selectors (item_id, connector_id, connector_name, custom_label), and omitting items syncs all. This adds complete 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 the tool forces a bank to re-sync connections and waits for completion. It uses specific verbs ('Forces', 'WAITS') and resources ('connections', 'items'), and distinguishes from siblings like openfinance_get_item_status for re-checking timed-out syncs.

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), when not to use (alternative for rechecking timed-out syncs), and how to use (omit items for all connections). Provides clear context for when to set wait:false for fire-and-forget.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds rich detail: CREDIT accounts may return structured warning, degradation with realtime: false and warning, and response shape with errors. Adds significant value beyond annotations.

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

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

Front-loaded with purpose and endpoint. Each sentence adds essential info: constraints, edge cases, response shape. No fluff, 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?

Covers all needed details: parameter constraints, multiple edge cases, response structure with results and errors array. No output schema, so description fully compensates. Complete for a 1-param tool.

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

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

Schema has 0% description coverage, so description must compensate. It adds array size constraint (1–50) and implies its purpose. Also describes output shape indirectly. Good but could mention id format.

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

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

Clearly states it returns real-time balance per account id with endpoint reference. Distinct from sibling tools like openfinance_list_accounts or openfinance_get_accounts_detail.

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

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

Explicitly says to pass account_ids as an array (1–50). Describes behavior for CREDIT accounts and upstream unavailability, providing clear context for correct usage. No explicit alternatives but still helpful.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds critical transparency about the provider_incident block, warning that credit limits and balances may be unreliable during provider incidents. This goes beyond annotations to guide safe interpretation of results.

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 three sentences: first states the purpose and HTTP method, second specifies parameter usage with batch limit, third explains an edge case. All sentences are necessary and front-loaded with the most important information.

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

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

The description covers the return shape ({ results, errors }), parameter usage, and an important edge case (provider_incident). It lacks details on the full structure of account objects, but given the absence of an output schema, it provides sufficient context for safe usage.

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

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

The schema has one parameter (account_ids) with no description. The description adds the array size constraint (1-50) and clarifies that these are account IDs for which detailed objects are returned, providing essential meaning beyond the bare schema.

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

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

The description clearly states the tool returns full account objects with extended creditData per ID, and specifies the HTTP method GET /accounts/:id. It differentiates from siblings like openfinance_list_accounts (list all accounts) and openfinance_get_account_balance (balance only) by focusing on detailed, batch retrieval for specific 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 specifies the batch size limit (1-50) and the batch response shape, providing clear usage context. However, it does not explicitly mention when to prefer this tool over alternatives like list_accounts or get_account_balance, though the purpose implicitly distinguishes them.

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

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

Adds substantial behavioral detail beyond annotations: notes Pluggy does not return paid/status field, explains payments[] reflects previous bill payment, warns about sparse billId on transactions, and mentions batch shape. No annotation contradiction.

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

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

Description is long but well-structured: main purpose first, then details. Every sentence adds value, though some could be condensed. Front-loaded effectively.

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

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

For a tool with no output schema, the description explains return shape, fields, caveats, and cross-tool relationships. Completely covers what the agent needs 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?

Only one parameter (bill_ids) with 0% schema description coverage. The description explains its purpose and how to obtain bill IDs (via list tool), adding value beyond bare schema.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by ID, listing specific fields (financeCharges, payments) and explicitly distinguishes from sibling tool openfinance_list_transactions which gets itemized transactions.

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

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

Provides explicit guidance: use openfinance_list_credit_card_bills first to discover ids, warns against summing transactions by billId, explains payments[] semantics and recommends openfinance_list_credit_card_bills for paid status. Clear when to use and when not to.

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 context beyond annotations: the reconnect_url reopens widget in UPDATE mode without disconnecting or consuming a slot. Annotations already indicate read-only, idempotent, and non-destructive. No contradictions.

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

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

The description is concise: three sentences that front-load the primary purpose, then cover usage variations. No extraneous 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?

All necessary information is present: return fields, single vs. all usage, bulk support, reconnect_url behavior. With no output schema and annotations covering safety, this is complete for an information tool.

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

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

Schema coverage is 0% but the description explains the parameter usage well: omit `item` for all, pass `item` for single, and use item_ids for bulk. This adds sufficient meaning, though the distinction between `item` and `item_id` is not clarified.

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

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

The description clearly states the tool returns the current status of a bank connection with specific fields (status, executionStatus, connector metadata, reconnect_url). It distinguishes between single bank and all banks, and mentions bulk support, which differentiates it from siblings like openfinance_list_connections.

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

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

The description provides clear usage scenarios: omit `item` for all banks, pass `item` for single bank, and accept item_ids for bulk. It explains the reconnect_url purpose. However, it does not explicitly state when to use this tool over sibling tools, such as openfinance_list_connections.

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

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

Annotations already mark as readOnly and idempotent; description adds that it returns a batch shape with results and errors, and constraints on loan_ids (1-50). 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?

Concise single sentence listing fields, followed by usage hint and parameter/return information. Front-loaded with 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 single parameter, no output schema, description lists many fields and return shape. Context with sibling list tool is provided, making it complete for a detail retrieval tool.

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

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

Schema has 0% description coverage; description adds that loan_ids is an array of 1-50 strings, but does not explain format or provenance beyond that.

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, specifies endpoint, and lists fields. It explicitly distinguishes from sibling tool openfinance_list_loans by indicating usage after listing.

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 use after openfinance_list_loans for deep-dive on a specific contract. Does not provide when-not-to-use but strong context for correct invocation.

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 significant behavioral context: balance meaning is connector-dependent, provider_incident may cause unreliable data, identity_notice may cause duplicate accounts, and bulk support via item_ids. 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 quite long but front-loads the main purpose and then covers nuances. It could be more structured (e.g., bullet points), but given the complexity of the tool, the level of detail is appropriate and every sentence adds value.

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

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

For a tool with 4 parameters and no output schema, the description covers all important aspects: return fields, usage nuances, edge cases (provider_incident, identity_notice), and alternatives (using other tool for bills). It is very complete for a complex financial tool.

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

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

Schema coverage is 0%, so description carries full burden. It explains the purpose of item (omit or pass), type (BANK/CREDIT), and item_ids (batch execution). Item_id is not explicitly explained but is implied as a singular variant. Overall adds good 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 'Returns accounts for a bank connection' and distinguishes between BANK and CREDIT types. It explains the difference between listing all accounts (omit item) vs targeting a single bank (pass item), effectively differentiating it from sibling tools like openfinance_list_credit_card_bills.

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

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

Explicitly states when to omit item vs pass item, and when to use openfinance_list_credit_card_bills for standardized open-bill amounts. Also warns about provider_incident and identity_notice, providing clear context for proper usage and 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it is cached for the adapter session and is a single aggregated response, providing extra 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?

Four sentences, clear and front-loaded. No unnecessary words. Every sentence adds value.

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

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

Given no parameters and no output schema, the description thoroughly covers the output structure, caching, and use of fields. Complete for a read-only list tool.

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

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

No parameters in schema (100% coverage trivially). Description adds meaning by explaining the output fields (id, description, etc.), which compensates for no 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?

Description clearly states it returns Pluggy's transaction category taxonomy, cached for the adapter session, and explains the fields. This is specific and distinguishes it from sibling list 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?

Mentions that the id is used by openfinance_update_transaction_category and notes preference for descriptionTranslated for pt-BR users. Does not explicitly state when not to use or alternatives, but context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining the behavior of reconnect_url (no slot consumption, no disconnect needed). It does not detail other behavioral traits beyond that, but the context is sufficient.

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 front-loads the primary purpose and then details the URLs. It is concise with no redundant sentences, though it could benefit from breaking into shorter sentences for 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?

Despite no output schema, the description fully covers the returned fields (connector_id, item_id, bank name, URLs) and explains the behavior of the URLs. This is complete for a list endpoint with no nested objects or complex outputs.

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 in the input schema, so the description has nothing to add. Baseline is set to 4 for zero-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 it returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes itself from sibling tools by highlighting the reconnect and add connection URLs, which are unique to this tool.

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

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

Explicitly explains when to use the reconnect_url (for re-authentication needs like MFA connectors, LOGIN_ERROR, stale data) and clarifies that it does not consume a connection slot or require disconnecting. This provides clear guidance for the 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?

Discloses payment semantics, derived payment_status, bill grouping reliability, connector asymmetry, and warning behavior. Consistent with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

Very long and detailed, but well-structured with headers. Every sentence adds value, but not concise; could be front-loaded with 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?

Comprehensively explains all output fields, edge cases, warnings, and behavioral nuances. No output schema, so description carries full burden and meets 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?

Adds meaning for account_id, account_ids (bulk), and include_open_bill (opt-in, derived). However, page and page_size are not described, though schema coverage is 0%. Partially compensates for missing schema descriptions.

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

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

Clearly states it returns closed credit card bills for a CREDIT-type account, listing specific fields and distinguishing from siblings like openfinance_get_credit_card_bill and 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?

Explicitly tells when to use (closed bills), when to opt-in (include_open_bill), and when to use alternatives (for purchases use openfinance_list_transactions). Provides guidance on cross-checking account echo and handling connector asymmetry.

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, destructively false), the description adds critical behavior: error handling (returning warning instead of throwing 403), data integrity checks with data_integrity_warning and suspect_zeroed flag, and instructs the agent on how to treat zero balances. 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 well-structured with clear sections for purpose, error handling, and data integrity, but it is somewhat lengthy. The main purpose is front-loaded, though the bulk support note at the end could be placed earlier.

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 lacking an output schema, the description thoroughly explains the return structure ({total, results, warning}), row fields, and special handling of data integrity issues. It covers error cases and provides clear instructions for the agent.

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

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

Schema description coverage is 0%, but the description only briefly mentions item_ids for bulk support and does not explain other parameters (item, page, page_size, type). The parameter semantics are largely left undocumented.

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 the investment portfolio for a connection, listing specific asset types (FIIs, stocks, etc.). It distinguishes itself from the sibling tool openfinance_list_investment_transactions by focusing on portfolio summary rather than individual transactions.

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

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

The description implies usage when portfolio data is needed for a connection with INVESTMENTS enabled, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives among siblings.

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 read-only and idempotent behavior. Description adds value by stating bulk support via investment_ids and listing transaction types and fields, enhancing behavioral awareness 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?

Concise two-paragraph structure. First paragraph describes output and fields clearly; second paragraph gives usage guidance and bulk capability. No unnecessary words, well front-loaded.

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

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

Covers return fields and usage context well, but lacks details on pagination parameters (page, page_size) and no output schema exists. For a list operation with pagination, this is a gap.

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 description must clarify parameters. It explains investment_id and investment_ids but omits page and page_size parameters, leaving pagination details undocumented.

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 movement history for investment positions, listing specific transaction types (BUY, SELL, etc.) and fields. It distinguishes from sibling tool openfinance_list_investments by noting the sequence of use.

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

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

Explicitly advises using after openfinance_list_investments to obtain investment_id. Provides clear context for when to use, though does not include explicit when-not-to or alternative tools beyond the sibling reference.

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

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

Adds value beyond annotations by disclosing rate-limit spacing, per-connection result/error structure, and the effect of omitting `items`. Annotations already indicate read-only and idempotent behavior, consistent with description.

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 plus a short clause, each sentence earns its place. Front-loaded with purpose, no redundancy, efficient and 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?

Covers all necessary context: purpose, parameter semantics, behavior (rate-limit, sequential), and return structure. No output schema exists, but description adequately explains return format. Complete 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?

With 0% schema description coverage, the description fully compensates by explaining that `items` are connection selectors (item_id, connector_id, or connector_name) and describes behavior when omitted. Adds significant meaning beyond 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?

Describes the tool as listing loan contracts per bank connection with a clear verb ('lists') and resource ('loan contracts'). Distinguishes from siblings like openfinance_get_loan_detail by specifying scope (per connection) and conditions.

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 usage: pass `items` array for specific connections or omit for all, and notes sequential querying with rate-limit spacing. Does not explicitly state when not to use, but offers sufficient context.

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

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

Annotations already declare readOnly and idempotent hints. Description adds extensive behavioral context: auto-pagination with truncation, error handling returns structured objects instead of exceptions, provider_incident block, per-connector inconsistencies, and that billId is a hint not authoritative. 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 lengthy but every sentence adds essential value given the tool's complexity. It is well-organized: basic purpose, credit card specifics, filtering, pagination, error handling, detail levels, account echo, and provider incidents. While not extremely concise, it avoids fluff and prioritizes important 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 all aspects: purpose, usage guidelines, parameter semantics, behavioral traits, error handling, and cross-sibling references. With 8 parameters, no output schema, and no schema description coverage, the description is fully complete and gaps are nonexistent.

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 compensate. It thoroughly explains each parameter: date format (ISO YYYY-MM-DD), search_queries behavior (case/accent-insensitive substring, OR semantics), pagination options (auto vs manual with defaults and limits), detail levels (compact/rich/raw) with precise field additions and caveats, and the account echo block. Full compensation.

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 transactions for bank accounts (BANK or CREDIT type). Distinguishes from siblings like openfinance_list_credit_card_bills by noting it is the only way to get itemized credit card transactions. Specific verb 'list' and resource 'transactions'.

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

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

Provides explicit guidance on when to use alternatives (e.g., for standardized open bill totals use openfinance_list_credit_card_bills), warns about per-connector variations (Nubank sparse billId), explains pagination modes, detail levels, and cross-checking account echo. Covers when/not and why.

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 directly consistent with a read-only analysis tool), description adds critical behaviors: 5000/account cap with truncated flag, provider_incident causing incomplete data, and the note that reconnecting won't fix it. This provides essential transparency for reliability.

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 lengthy but front-loaded with main purpose. Uses structured sentences with clear separations for details. Every sentence adds value, though it could be slightly more compact without losing clarity.

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

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

With no output schema, description outlines key return elements (totals, monthly evolution, top expenses, per-account breakdown, truncation, provider_incident). It covers main use cases and expected data, providing sufficient context for an agent to understand tool outputs.

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

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

Schema has 0% description coverage, so the description carries full burden. It explains item as connector_id/name/item_id, from/to as ISO dates, granularity defaults and effects, detail sub-options, type filter, and bulk item_ids. top_n is implied via output. Most parameters are meaningfully described.

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 provides consolidated cash-flow analysis for a whole bank connection, aggregating transactions across accounts. It explicitly distinguishes from sibling tools by noting it eliminates the need to call openfinance_list_accounts or carry account IDs, making its unique value apparent.

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

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

Description gives explicit use cases like 'fluxo de caixa' and 'maiores gastos/recebimentos', and explains when to use granularity and detail options. It mentions bulk support but lacks explicit comparison to alternatives like openfinance_list_transactions, though context is implied.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by detailing the return content: global indicator, degraded components, open incidents, and flags incidents affecting your banks. Discloses behavioral traits beyond annotations, though lacks info on rate limits or auth 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?

Description is a single paragraph but is well-structured with logical flow: what it does, when to use, what it returns. Could be slightly more concise or broken into shorter sentences, but remains clear and 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?

Despite no output schema, description fully explains the return value (global indicator, degraded components, open incidents, your_banks_affected). For a tool with zero parameters and a clear use case, this provides complete context for an AI agent to select and invoke it correctly.

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

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

Tool has zero parameters, so schema coverage is trivially 100%. Description adds no parameter info because none exist. Per guidelines, 0 params = baseline 4.

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

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

Clearly states it checks the live operational status of the Open Finance provider, using specific verb 'checks' and resource 'provider status'. Distinguishes itself from sibling tool 'openfinance_get_item_status' by noting it is provider health, separate from your connection.

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

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

Explicitly explains when to use: when data looks incomplete/stale even though connection shows updated, accounts/transactions missing, bank not returning everything. Also describes what it reveals (upstream outage, specific incidents) and how it helps differentiate provider-side problems from connection issues.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining non-Open-Finance connectors carry a caveat warning about manual reconnection, and that the tool honors the user's plan (PF vs PJ). 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 relatively long but well-structured and front-loaded with the core purpose. Each sentence adds essential guidance; however, it could be slightly more concise without losing clarity.

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

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

The description covers all necessary context: required parameters, optional behavior, return fields, caveats, plan handling, and sequencing (call before connecting). No output schema exists, but the description sufficiently explains what the tool returns.

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

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

Schema has no descriptions for parameters, but the description clearly explains 'keywords' is required and expects an array of strings (with examples), and 'include_accounts' when true returns accounts. This compensates for the 0% schema coverage.

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

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

The description clearly states the tool searches bank connectors by name (keywords) and returns specific fields like connector id, access type, audience, linked connections, and connect URL. It distinguishes from sibling tools that list all connections or perform other operations.

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

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

Explicitly instructs to call this before connecting to provide a one-click link. Specifies that keywords are required, and if omitted, returns a hint instead of dumping the catalog. Advises surfacing caveat warnings and preferring Open Finance connectors for automation.

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 critical behaviors: it overrides automatic categorization, teaches Pluggy by creating a Category Rule, and explains batch error handling (per-item errors don't fail the whole batch).

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 somewhat lengthy but each sentence adds value. It front-loads the core action, then explains the important side effect, then batch details. Minor redundancy could be trimmed, but overall 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 the tool's complexity (side effects, batch processing) and no output schema, the description covers input structure, side-effect implications, and response format. It also references sibling tools for context, making it complete 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?

With 0% schema description coverage, the description fully explains the items parameter: it's an array of objects with transaction_id and category_id, and specifies where each ID comes from. It also details the batch response shape (updated, results, errors).

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 'Corrects', the resource 'category of one or more transactions', and specifies the HTTP method and path. It distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_categories by explaining where to obtain 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?

Guidance is provided on when to use (fix miscategorized transactions, improve future categorization) and how to obtain IDs from sibling tools. No explicit when-not is given, but the side effect of creating a Category Rule is clear, implying careful 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?

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that the conversation array should be included for reproduction, which is useful but doesn't contradict annotations. It provides moderate additional 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?

Two sentences convey the purpose and a key usage detail with no redundancy. Every word is meaningful and front-loaded.

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

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

Given the simple scenario (reporting feedback) and annotations covering idempotency and non-destructiveness, the description is mostly complete. It could mention expected output (e.g., confirmation), but this is not critical for tool 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 coverage is 0%, so the description must compensate. It explains that 'conversation' is for reproduction, but does not clarify the 'message' or 'context' parameters beyond their basic types. Some added value, but incomplete.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It specifies the primary action (reporting) and the scope (bugs, features, feedback), distinguishing it from siblings like openfinance 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 implies usage for reporting issues but lacks explicit guidance on when not to use it or alternatives. No comparison to sibling tools is provided, leaving the agent to infer context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds no extra behavioral context. It doesn't disclose output format or any side effects, leaving a gap 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?

A single, clear sentence. No redundant information, front-loaded with the action and resource. Every word 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 parameterless tool with comprehensive annotations, the description is nearly complete. It could mention that results are returned as JSON, but the current text is sufficient for an agent to understand the tool's purpose and invoke 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?

Schema has zero parameters with 100% coverage, so description need not add parameter info. Baseline 4 is appropriate; no additional param semantics required.

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

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

The description clearly states the verb 'show' and the resource 'versions'. It defines the tool's scope ('MCP platform and adapter versions') and distinguishes it from siblings, as no other tool provides version info.

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 vs alternatives. However, its simplicity and self-explanatory nature make usage obvious; still, a note on context (e.g., 'use to check system state') would improve 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds context about the specific state returned (installed MCPs, connection status, catalog tool counts), which is useful but does not disclose behavioral traits beyond what annotations provide.

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

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

The description is a single sentence that efficiently conveys the tool's purpose and output. No wasted words, front-loaded with key 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?

Despite no output schema, the description lists the return content (MCPs, status, catalog tool counts), which is sufficient for a simple info tool. With strong annotations and no parameters, everything needed is provided.

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

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

With zero parameters, schema coverage is 100%. The description does not need to add parameter meaning, and baseline is 4. No additional detail is required.

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

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

The description clearly states the tool returns the current toolkit state, including installed MCPs, connection status, and catalog tool counts. It uniquely identifies this as a status/info tool, distinguishing it from sibling tools like authenticate or openfinance_* operations.

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

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

No explicit guidance on when to use this tool vs alternatives. However, its purpose as a general state checker is self-evident, and with zero parameters, usage is straightforward. Implied usage is to retrieve toolkit information.

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