BTGPactual MCP

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

Discloses behavior: with no args returns a link, with token authenticates. Annotations indicate idempotent and non-destructive, which are consistent. Adds context about token handling beyond annotations.

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

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

Single paragraph with efficient, front-loaded information. Every sentence serves a purpose: identity, usage methods, and parameter explanation. No fluff.

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

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

Given no output schema, the description does not specify return values. However, the core usage is clearly covered. For a simple authentication tool with one optional parameter, it is largely complete.

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

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

Schema has 0% description coverage, but the description fully explains the 'token' parameter: optional, used for session login. Also clarifies omitted token triggers link generation. Adds significant 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 is for authentication in MCP.AI for IDE agents, distinguishing between permanent and session-based login. It provides specific verb+resource context and is distinct from sibling tools like 'connect'.

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

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

Explicitly describes when to use each method: for permanent connection, add token to config; for session-only, paste as parameter. Also specifies calling with no args to get the link. No ambiguity.

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, idempotent, and non-destructive. The description adds value by detailing the return states (authenticated:true with empty pending[] vs. connect URLs), providing context beyond the annotations 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 concise with two sentences, front-loading the main purpose. Every sentence adds meaningful information 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 adequately explains return values for two key states. However, it lacks details on other possible states or error handling, leaving slight gaps. Still sufficient for a simple status check.

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

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

The input schema has zero parameters, so the baseline is 4. No parameter information is needed or provided 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 'Returns connection status and URLs' and elaborates on two specific scenarios (all connected vs. credentials missing), making the purpose unambiguous. It effectively distinguishes from sibling tools like 'authenticate' which initiates 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?

Usage is implied: the tool is for checking connection status before deciding to authenticate. However, there is no explicit when-to-use or when-not-to-use guidance, nor are alternatives mentioned.

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 only provide booleans (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false). The description adds crucial non-obvious behavior: invoke runs tools one-off without installing or bloating the tool list, returns connect/checkout links when credentials/payment are needed, writes require owner/admin, and published prompt links open without login. 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 front-loaded with the core purpose and flow, and every sentence carries a distinct piece of guidance (one-off invoke, install permanence, permission requirements, prompt library). It lacks visual structure such as bullets or sections, making the dense multi-action behavior harder to scan, but it does not waste words.

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

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

Given the tool's complexity (14 actions, 23 params, no output schema), the description covers most behavioral surfaces: search/describe/invoke flow, one-off vs. permanent install, billing verbs, reporting, requesting new MCPs, prompt library, installed flags, and auth/payment retry behavior. Gaps remain around response formats and exact input combinations for each action, so it is not fully complete.

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

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

With 0% schema description coverage and 23 parameters, the description needed to map action values to their required parameters, but it only mentions action and tool_id in passing. It does not clarify mcp_id, arguments, limit, query, tier_slug, prompt_* fields, cancel_reason, or how these combine with each action. The action-enum behavior is covered, but the rest of the parameter surface remains opaque.

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 opening sentence clearly names the resource ('official mcp.ai marketplace') and its dual role: catalog of every MCP/tool and the way to run them. It distinguishes itself from sibling openfinance/authenticate tools by positioning as the in-platform catalog and execution layer, and it enumerates the full action vocabulary.

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 maps a core flow (search → describe → invoke), tells when to prefer invoke over install ('prefer invoke for a single/occasional use'), and names alternatives for billing (subscribe/cancel), feedback (report_bug), new-build requests (request_mcp), and prompt-library operations. It also states that writes require workspace owner/admin, giving clear when-to-use vs. when-not 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 mark destructiveHint=true. The description adds that data is deleted and unavailable, and returns a re-connect URL. This is consistent but does not disclose additional behavioral traits like whether the action is reversible or requires specific permissions beyond what annotations imply.

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, each with a clear purpose. Front-loaded with the core action, followed by consequences and return value. No superfluous 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 destructive nature and lack of output schema, the description covers the main effect and return value. However, it omits prerequisites (e.g., existing connection), error conditions, and does not explain the 'item' parameter, leaving room for ambiguity.

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 single parameter 'item' is not described in the schema (0% coverage). The description mentions 'a specific bank' but does not explicitly map 'item' to a bank identifier, leaving the parameter's meaning ambiguous.

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 action (revokes consent and deletes connection data) and the specific resource (bank connection). It also mentions the return of an add_connection_url for re-connection, distinguishing this tool from sibling tools like openfinance_list_connections or openfinance_force_sync.

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

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

No explicit guidance on when to use or avoid this tool versus alternatives. The description implies it is for disconnecting a bank but lacks context about prerequisites or when not to use it (e.g., if data is needed later).

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?

Details the polling behavior, timeout (~60s), return fields (status, executionStatus, etc.), and special cases like needs_action with reconnect_url. No contradiction with annotations, as readOnlyHint=false and destructiveHint=false align with the described mutation without destruction.

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 thorough and well-structured, with the core action front-loaded. However, it is somewhat lengthy; a slightly more concise version could improve readability without losing information.

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

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

Given no output schema, the description thoroughly covers return values, error states (needs_action, timed_out), and how to handle them. It also notes the reconnect_url usage, 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?

Schema has no descriptions (0% coverage), but the description fully explains the 'items' parameter (array of selectors) and 'wait' parameter (fire-and-forget flag), adding crucial meaning beyond the schema structure.

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

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

Clearly states the tool forces a bank sync immediately and waits for completion. Differentiates from alternatives by noting it doesn't disconnect/reconnect and mentions using openfinance_get_item_status for timed-out checks.

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 when to use (stale balance/transactions) and provides usage options like omitting items to sync all and setting wait:false for fire-and-forget. Also directs to openfinance_get_item_status for rechecking timed-out syncs.

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 context beyond them: snapshot freshness semantics, the meaning of updateDateTime/updatedAt, specific error codes (BALANCE_FETCH_ERROR, BALANCE_CONSENT_ERROR) with structured warnings, the consent-recovery path, and row-degradation behavior on upstream 5xx errors. This is exactly the kind of behavioral nuance an agent cannot infer from annotations alone.

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 distinct operational content: purpose, freshness semantics, remediation workflow, parameter bounds, credit-account error modes, and degradation behavior. It is front-loaded with the core purpose and organized so that an agent can scan to the relevant clause. 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?

Given there is no output schema, the description does a good job of revealing partial return shape (rows contain updateDateTime/updatedAt, error rows carry a structured warning, degraded rows appear instead of throwing). The main remaining gap is the successful response payload for a normal row (exact balance field name and currency), which an agent would likely need to discover empirically. For a simple single-parameter read tool with rich error handling, this is nearly complete.

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

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

Schema description coverage is 0%, so the description carries the full burden for the single parameter. It adds the critical constraint 'Pass account_ids as an array (1–50)', which is the most operationally important detail beyond the schema's bare 'array of strings'. However, it does not state where the account IDs come from (e.g., openfinance_list_accounts) or provide an example, so the guidance is strong but not exhaustive.

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 the latest available balance per account id (GET /accounts/:id/balance).' It explicitly clarifies that this is a snapshot anchored to the last upstream sync, not a live read, which sharply distinguishes it from sibling tools like openfinance_list_transactions and openfinance_force_sync. An agent can immediately know what this tool does and what its key limitation is.

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

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

The description gives explicit when-to-use and when-to-escalate guidance: if a recent movement is missing or the balance disagrees with the sum of openfinance_list_transactions, the agent is told to run openfinance_force_sync and then re-read. It also names the conditions under which the tool returns structured warnings instead of throwing, so the caller can handle CREDIT-account error cases appropriately.

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

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

Beyond the annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds critical behavioral context: the batch shape with { results, errors }, the potential 'provider_incident' block, and a warning not to present unreliable values. This fully discloses behavior and limitations.

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 with 3 sentences. It front-loads the core purpose and adds important warnings. However, the structure could be improved by separating the batch shape detail from the warning.

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

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

Given the tool's complexity (batch, provider incidents) and absence of output schema, the description covers key aspects: batch shape, error handling, and unreliable data warnings. However, it lacks explicit return format details and does not describe the output structure beyond mentioning blocks.

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 description adds minimal parameter detail: only that account_ids is an array (1–50). It does not explain the format of IDs or any constraints beyond length. This is insufficient for a parameter that requires specific values.

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. This distinguishes it from sibling tools like 'openfinance_list_accounts', which likely returns a summary list. The verb 'Returns' and resource 'account objects' are specific.

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 pass 'account_ids' as an array (1–50). It implies use for detailed account retrieval. However, it does not explicitly mention when not to use this tool or suggest alternatives like 'openfinance_list_accounts' for listing.

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?

Even with readOnlyHint annotations, the description adds substantial real-world behavior: the bill payload has no transactions, transactions must be optioned in, transaction_basis may be exact or estimated, open-bill transactions are unreliable, totalAmount is authoritative, and Pluggy does not return a paid field. These are exactly the hidden behaviors an agent needs to know before calling.

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

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

The description is dense and well-structured, front-loading the core fields before moving to opt-in transactions, matching basis, caveats, and alternatives. Its length is justified by the domain complexity, though there is minor redundancy (openingfinance_list_transactions is recommended twice, and closed-bill reliability is repeated).

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 does a strong job of explaining return value shape, matching behavior, batch errors, and payment semantics. The only material gap is the undocumented transactions_detail parameter and its effect on response detail, which prevents perfect completeness.

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

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

Schema coverage is 0%, so the description carries the load. It explains bill_ids, account_id, and include_transactions, including how they interact. However, the transactions_detail enum (compact/rich/raw) is never explained, leaving that param ambiguous.

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 states a precise verb and resource: 'Returns bill-level detail for one or more credit card bills by id (GET /bills/:id)' and follows with the actual returned fields. It clearly distinguishes this from sibling list and transaction tools by scoping it to bill-level detail rather than account transactions.

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

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

The description explicitly tells the agent when to use this tool, what to use first ('openfinance_list_credit_card_bills to discover ids'), and when to prefer alternatives: 'prefer openfinance_list_transactions' for transactions, and 'prefer openfinance_list_credit_card_bills' for paid status. It also prevents misuse by warning that payments[] does not prove payment.

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 and destructiveHint=false. The description adds crucial behavioral context beyond this: the reconnect_url reopens the widget in UPDATE mode without disconnecting or consuming a connection slot, and bulk support is disclosed. This provides transparency about side effects and usage bounds.

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 but thorough, covering key points in three sentences. It front-loads the main purpose and then provides usage details. A slight reduction in length could improve conciseness, but it remains clear and structured.

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

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

Given the tool's complexity (single vs bulk, reconnect_url), the description covers the necessary aspects: return fields, usage modes, and bulk support. No output schema exists, but the description explains what is returned. Annotations handle safety. It is complete enough for effective agent 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?

The input schema has 0% coverage, with three parameters (item, item_id, item_ids) having no descriptions. The description fully compensates by explaining that omitting `item` returns all banks, passing `item` filters to one, and `item_ids` enables bulk execution. This adds essential semantic meaning.

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 current status of a bank connection with specific fields (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, connector metadata, and reconnect_url. It distinguishes from sibling tools like openfinance_list_connections by focusing on status and reconnect functionality.

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 guidance: omit `item` for all banks, pass `item` for single bank, and mentions bulk support with `item_ids`. However, it does not explicitly contrast with alternative tools like openfinance_list_connections or openfinance_get_account_balance, leaving some implicit choice.

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 batch response shape { results, errors } and array size constraint, which are beyond annotations.

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

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

Two sentences efficiently cover purpose, response fields, usage order, and parameter constraint. Front-loaded with key action; no redundancy.

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

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

For a read-only endpoint with no output schema, description adequately explains return fields and batch shape. Lacks error details but sufficient given annotations.

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 compensates by specifying array size (1-50) and indicating loan_ids are strings, giving meaning beyond type definition.

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

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

Describes returning full loan contract detail by ID with explicit field listing. Distinguishes from sibling openfinance_list_loans by stating 'Use after openfinance_list_loans to deep-dive.'

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?

States to use after openfinance_list_loans for deep-dive, and specifies passing loan_ids as array (1-50). Does not explicitly exclude misuse but provides clear workflow 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 readOnlyHint, idempotentHint, and non-destructive; the description adds substantial behavior beyond that: CREDIT balance is connector-dependent ('do NOT treat `balance` as "this month's bill"'), `balance_notice` requires reading the amount from another tool instead of reporting zero, bankData derived fields can carry stale/phantom values after first connection, provider_incident makes balances unreliable, and identity_notice requires dedupe by account number before summing. 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?

Nearly every sentence earns its place because each caveat prevents a real user-facing error, but the description is a dense ~500-word wall of text. Key invocation guidance (OMIT vs. pass `item`) is buried after the name-vs-brand note, and related warnings (balance semantics, balance_notice, provider_incident, identity_notice) are spread across separate long passages. The content justifies the length; the structure and front-loading do not.

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

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

Given no output schema and 0% parameter coverage, the description is remarkably complete: it documents the return fields, the notices (balance_notice, provider_incident, identity_notice), the dedupe rule, field-lag behavior, and routes to the right sibling tools. Remaining gaps are small but real: the role of the `item_id` input parameter, whether `type` combines with `item`/`item_ids`, and the relationship between `item_id` and `item_ids` are never stated.

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

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

With 0% schema coverage, the description carries full burden and compensates well for most parameters: `item` (single bank vs. aggregated-all), `type` (BANK = checking/savings, CREDIT = credit card), and `item_ids` (bulk/batched execution). However, the singular `item_id` input parameter is never explained as an input — it only appears as a response row tag — leaving the item vs. item_id distinction ambiguous.

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 opening sentence names a specific verb-operation and resource: 'Returns accounts for a bank connection: BANK (checking/savings) and CREDIT (credit card) with balance, number, type, subtype, bankData, and creditData.' It differentiates from siblings by explicitly routing credit-card bill amounts to openfinance_list_credit_card_bills, and the annotation title 'List Bank Accounts' aligns with the description. An agent can distinguish this from the 24 siblings without opening schemas.

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

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

The description gives explicit when-to-use guidance for each mode: 'OMIT `item` to list accounts across ALL linked banks at once... use this when the user asks for "my accounts/cards" without naming a bank. Pass `item` to target a single bank.' It also names alternatives with conditions: use openfinance_list_credit_card_bills for standardized open-bill amounts, and openfinance_force_sync to reconcile lagging fields. It even tells the agent when NOT to present values (provider_incident).

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds valuable context: caching behavior, single aggregated response (no batch ids), and structure details (id, description, parent). 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?

Two sentences with no fluff. First sentence states main purpose clearly; second sentence details response structure and caching. Excellent front-loading.

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 zero parameters and no output schema, the description fully covers what the agent needs: purpose, cached nature, response structure, and link to update tool. No gaps.

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 – baseline 4. Description does not need to add parameter info since schema coverage is 100% and empty. No issues.

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 Pluggy's transaction category taxonomy, cached for the session. Mentions the API endpoint (GET /categories) and links to the update tool. However, does not explicitly differentiate from other list tools in the sibling list.

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?

Implied usage: use to get categories before updating transaction categories. Notes preference for descriptionTranslated for pt-BR users but lacks explicit when-to-use vs alternatives or when-not-to-use guidance.

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

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

Goes beyond annotations (readOnlyHint, destructiveHint, idempotentHint) by detailing the behavior of reconnect_url (does not consume a slot, no need to disconnect) and explaining the add_connection_url. 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?

Single paragraph that is informative but slightly lengthy. Could be front-loaded with the primary purpose, but every sentence adds value. 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?

Completely covers the tool's behavior and return details despite having no output schema. Explains both URLs and their usage, making it self-sufficient for an 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?

No parameters, so baseline is 4. Description adds meaning about what the tool returns, which is essential given no output schema. It explains the return fields and their context.

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 the saved bank connections for this install' and lists specific fields (connector_id, item_id, etc.), making the purpose unambiguous. It distinguishes from sibling list tools by focusing on connections.

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

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

Provides guidance on when to use the reconnect_url (for re-authentication, MFA connectors, etc.), but does not explicitly differentiate from sibling tools like openfinance_list_accounts or openfinance_get_item_status. Some implicit context is given.

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

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

The description thoroughly explains behavioral traits: payment cycle semantics, derived payment_status logic, connector asymmetry for open bills, bill grouping reliability, and handling of cross-bill payments. It adds substantial context beyond annotations, which only declare readOnlyHint and 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 very verbose and dense, covering many edge cases and details. While informative, it could be more concise and structured (e.g., bullet points). The front-loading is adequate but the overall length hurts 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 (Brazilian Open Finance semantics, derived fields, connector asymmetry), the description is remarkably complete. It covers return fields, edge cases, warnings, and cross-tool references. No output schema exists, so the description fills the gap 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?

Schema coverage is 0%. The description adds meaning for include_open_bill and implicitly for account_id, but provides no explanation for page or page_size parameters. It compensates partially but not fully for the lack of schema description.

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 closed credit card bills for a CREDIT-type account, listing specific fields and derived data. It clearly distinguishes from siblings like openfinance_get_credit_card_bill and openfinance_list_transactions by name and 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?

Provides clear when-to-use context (closed bills, opt-in for open bill) and explicitly directs users to openfinance_list_transactions for itemized charges. However, it could more explicitly state when not to use this tool versus each sibling tool (e.g., for open bills, use with include_open_bill).

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, idempotentHint, and non-destructive. The description goes beyond by detailing the data integrity cross-check for zeroing positions, explaining the `data_integrity_warning` and `integrity:'suspect_zeroed'` flag, and advising against treating those as real zeros. This is critical behavioral context.

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

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

The description is front-loaded with the primary purpose and return format. It includes necessary details about data integrity, but the length is reasonable given the complexity. Minor redundancy could be trimmed.

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 provides a clear picture of return fields (balance, amount, rates, dueDate, issuer) and error handling. It covers edge cases like upstream errors and mass zeroing, making it sufficiently complete for a read-only, idempotent portfolio 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 should compensate but only mentions `item_ids` for bulk support. It does not explain parameters like `item`, `page`, `type`, or `page_size` in meaningful detail, leaving the agent to infer their purposes.

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 the tool returns investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). It clearly differentiates from sibling tools like openfinance_list_investment_transactions and openfinance_get_account_balance by focusing on portfolio summary.

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

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

The description advises that the tool returns a graceful response instead of throwing when INVESTMENTS isn't enabled, and mentions bulk support via item_ids. However, it does not explicitly state when to use this tool versus alternatives, though the context makes it clear it's for portfolio overview.

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 return fields and bulk capability beyond annotations. However, does not mention pagination behavior (page, page_size parameters) which is relevant for usage.

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, efficient and clear. Front-loaded with main action, then usage, then bulk. Minor room for improvement in structure.

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 main functionality, input, and output fields well given no output schema. Lacks pagination details, but overall adequate 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?

Adds meaning for investment_id (usage context) and investment_ids (bulk), but page and page_size parameters remain unexplained. With 0% schema coverage, the description partially 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 explicitly states it returns movement history for investment positions, lists transaction types (BUY, SELL, etc.), and distinguishes from siblings by referencing openfinance_list_investments for obtaining investment_id.

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

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

Provides clear context: use after openfinance_list_investments to get investment_id. Also mentions bulk support for batched execution, guiding when to use multiple IDs.

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 sequential query behavior for multiple connections and the return structure ({ results, errors }), providing useful 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?

Three sentences, critical information front-loaded, no unnecessary words. Highly efficient.

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

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

For a simple list tool with one optional param and comprehensive annotations, the description covers essential usage, behavior, and return shape completely.

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 description explains the `items` parameter as connection selectors (item_id, connector_id, or connector_name) and the effect of omission. It adds significant meaning, though format details are slightly vague.

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 'Lists loan contracts per bank connection' with the GET endpoint, and distinguishes listing for specific connections vs all 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?

It explains when to use the `items` parameter vs omitting it for all banks, and mentions sequential querying with rate-limit spacing. However, it does not explicitly exclude alternatives or list sibling tools.

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

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

Annotations already mark the tool read-only and idempotent, and the description adds substantial behavioral context: auto-pagination up to a 5000 ceiling, scheduled rows and their ordering semantics, per-connector differences in PENDING/POSTED coverage, 'billForecastDate' caveats, and the non-cons of billId sparse data. It also documents the error shape ({ total:0, results:[], warning, error }) and the optional account echo block.

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 organized into helpful sections and front-loads the core behavior, but it is very long and repeats several caveats (e.g., the billId 'do not sum by it' warning and the 5000/truncated trend/truncation guidance appear more than once). A more succinct, single source of truth for each repeated concept would keep the same behavioral value with better conciseness.

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

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

Given no output schema and high domain complexity, the description covers each important behavioral dimension: result coverage, scheduling, pagination, per-connector variance, error handling, troubleshooting, and integration with sibling tools. An agent has what it needs to correctly invoke the tool and interpret the returned values, and the only other has minor edge features like the account_ids bulk parameter not explicitly documented.

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 no field descriptions, so the tool description carries almost the entire explanatory burden. It thoroughly explains from/to formats, search_queries semantics, detail enum values ('compact', 'rich', 'raw'), and the page/page_size auto vs manual pagination contract. The main gap is the account_id/account_ids (especially account_ids) parameter is never explicitly walked through, though 'specified bank account' and the account echo imply account_id.

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 names the exact verb ('Returns transactions'), resource ('bank account'), and account types (BANK/CREDIT), and marks credit card transaction itemization as the ONLY way to get it, differentiating this tool from openfinance_list_credit_card_bills and other siblings. It is unambiguous and specific enough for an agent to know what this tool is for.

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 routing rules: use openfinance_list_credit_card_bills for a standardized open-bill or total debt period, use openfinance_list_accounts for card statement closing/due dates, and use openfinance_get_item_status or openfinance_force_sync when a credit transaction total is zero and the sync failed. This exceeds the minimum by providing both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds critical behavioral details: truncation at 5000/account with truncated flag, provider_incident block for data quality issues, and behavior when item is omitted (analyze all linked banks). 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 comprehensive but somewhat verbose; it repeats some details (e.g., granularity options appear multiple times). However, it is well-front-loaded with the core purpose and remains clear.

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

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

Given 9 parameters and no output schema, the description thoroughly explains return format (compact summary fields, monthly evolution, top expenses/revenues, per-account breakdown), behavior for different granularity/detail combos, and edge cases like provider incidents and truncation. It provides complete context for 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?

With 0% schema description coverage, the description fully compensates by explaining item (multiple formats), from/to (ISO dates), granularity (monthly vs raw), detail (compact/rich/raw), type (BANK/CREDIT), and top_n implicitly via top_despesas/recebimentos. Bulk support via item_ids is also 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 it provides consolidated cash-flow analysis for a whole bank connection over a period in one call, resolving accounts internally. It distinguishes from sibling tools like openfinance_list_accounts and openfinance_list_transactions by eliminating the need for separate calls.

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 when to use this tool and when not, e.g., 'so you do NOT need to call openfinance_list_accounts first'. Provides concrete use cases like 'análise anual/mensal', 'fluxo de caixa', and explains granularity and detail options.

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 context beyond annotations by describing return data (global indicator, degraded components, incidents, your_banks_affected). Annotations already declare readOnly and idempotent, so description enriches without contradiction.

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

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

Concise (~100 words), front-loaded with purpose, every sentence serves a purpose. Structured logically: what, when, what returns.

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 zero parameters and no output schema, description covers all needed context: purpose, usage scenario, and return value details. Annotations cover safety profile.

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

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

No parameters exist, so description adds no param-specific info. Per guidelines, 0 params yields baseline 4. No additional param meaning 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?

Clearly states the verb 'checks' and resource 'LIVE operational status of the Open Finance provider'. Explicitly differentiates from sibling tool openfinance_get_item_status by emphasizing provider vs connection health.

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 scenario: when data looks incomplete/stale despite a connection showing UPDATED. Contrasts with the sibling tool and explains diagnostic value.

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 and idempotentHint=true. The description adds context about returning a connect_url, honoring the user's plan, and caveat warnings, which goes beyond the annotations 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 a dense paragraph, packing a lot of information. It could be more structured (e.g., bullet points), but it is clear and front-loaded with the main action. 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 2 params, no output schema, and good annotations, the description is exceptionally complete: it covers purpose, usage, plan behavior, caveats, and when to call. No gaps remain.

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

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

With 0% schema description coverage, the description fully explains both parameters: keywords (array of strings, required, example given) and include_accounts (boolean, triggers account retrieval). Provides behavior details not in schema.

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

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

The description clearly states it searches bank connectors by name and returns connector id, access type, audience, linked connections, and a ready connect_url. It distinguishes from sibling tools like 'connect' and 'marketplace' by focusing on search and pre-selection.

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 call 'BEFORE connecting', explains that keywords[] is REQUIRED (returns hint otherwise), and describes plan behavior (PF vs PJ). Guides on surfacing caveat warnings to prefer Open Finance connectors.

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 critical behavioral traits: overrides automatic categorization, creates a Category Rule for future similar transactions (teaches Pluggy), and describes batch error handling (per-item errors don't fail the whole batch). Annotations (readOnlyHint=false, destructiveHint=false) are consistent; 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 comprehensive but slightly verbose. It could be slightly more concise (e.g., splitting into bullet points). However, it front-loads the essential purpose and action, 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?

Given a simple input schema (one parameter, no output schema), the description covers the return shape, error handling, and side effects. No gaps remain for a correct invocation. The context is complete.

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

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

The input schema has 0% description coverage, but the description thoroughly explains the `items` parameter: it's an array of objects with transaction_id and category_id, and specifies where to obtain these IDs (from list_transactions and list_categories). Fully compensates for missing schema descriptions.

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

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

The description clearly states the action (corrects category of transactions), specifies the HTTP method and endpoint (PATCH /transactions/:id), and distinguishes itself by referencing sibling tools (openfinance_list_transactions, openfinance_list_categories) as sources for inputs. No 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 explains when to use: to fix miscategorized transactions and improve future categorization. It provides guidance on sourcing transaction_id and category_id from related tools. While it doesn't explicitly state when not to use, the context is sufficient for appropriate 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 already indicate idempotentHint=true (safe to retry) and readOnlyHint=false (write operation). The description adds that the conversation array should be included for reproduction, which is helpful context. It does not mention side effects, authentication needs, or confirmation responses, but it does not contradict annotations.

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

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

The description is extremely concise: two sentences that directly convey the tool's purpose and a key usage hint. No redundant or extraneous information; every word serves a purpose.

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

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

Given the tool's simplicity (one required parameter, no output schema), the description is largely sufficient. It explains how to use the key 'conversation' parameter. However, it could mention the response behavior (e.g., confirmation or error handling) to be fully complete.

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

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

The input schema has 0% description coverage, placing the burden on the tool description. The description explains the 'conversation' parameter (for reproduction) but does not clarify 'context' or elaborate on 'message' beyond the tool's general purpose. This adds some meaning but is incomplete.

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

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

The description clearly states the tool's purpose: reporting bugs, missing features, or sending feedback. It uses specific verbs ('Report', 'send') and a clear resource. Among the sibling tools, none serve the same function, so it is well-distinguished.

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 a specific usage instruction: 'Include the conversation array with recent messages for reproduction.' This clarifies a key requirement. However, it does not explicitly state when not to use this tool or compare it to alternatives, though no direct alternatives exist 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 readOnlyHint=true and idempotentHint=true, confirming safe, side-effect-free behavior. The description adds specificity about what is shown (platform and adapter versions), which is consistent and informative.

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?

One short sentence that is clear and front-loaded. No unnecessary words.

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

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

For a simple read-only version tool with no parameters, the description is complete. It states what is shown (versions) and nothing else is needed.

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 parameters and 100% schema coverage, the description does not need to add parameter info. Baseline score of 4 applies as it adds no semantics 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 verb 'Show' and the resource 'current MCP platform and adapter versions.' It distinguishes from all sibling tools, none of which provide version information.

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 does not explicitly state when to use this tool versus alternatives, but it is logically implied for checking version info. No usage guidance beyond the basic purpose is given.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by detailing what the return includes (installed MCPs, connection status, account links, catalog tool counts) but does not reveal additional behavioral traits like pagination, caching, or authentication requirements. This matches the baseline for annotation-backed tools.

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

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

The description is a single, front-loaded sentence that begins with the core purpose ('Returns the current toolkit state') and then lists the exact contents. Every phrase adds value, with no redundant or vague language.

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 no-parameter, read-only info tool without an output schema, the description is complete enough. It covers the essential return categories (installed MCPs, connection status, accounts, catalog tool counts) and gives the agent a clear expectation of what the tool provides. There is no need for additional context about pagination or errors given the tool's simplicity.

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

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

The tool has zero parameters, so schema coverage is trivially 100%. The description correctly adds no parameter-specific information because there are none, and the baseline for zero-parameter tools is 4. No further semantic clarification 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 clearly states the tool returns the current toolkit state, enumerating specific elements (installed MCPs, connection status, accounts, catalog tool counts). The verb 'returns' is specific and the resource is well-defined, distinguishing it from sibling tools that focus on finance operations or authentication.

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

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

The description provides clear context for when to use this tool — to get an overview of the toolkit state, including MCP connectivity and account status. It does not explicitly name alternatives or exclusions, but the unique focus on 'toolkit state' makes the usage scenario apparent without needing to reference sibling tools.

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