BTGPactual MCP

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

Annotations indicate idempotentHint=true and destructiveHint=false, and the description explains that calling with no args returns a login link, while calling with a token performs authentication. This adds contextual behavior beyond annotations, such as the two possible outcomes. 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 efficient, front-loading the purpose and then detailing two usage scenarios. Every sentence is informative, though slightly verbose with 'MCP.AI for IDE agents (Cursor, etc.):' which 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?

Given no output schema and a simple tool, the description covers the main behaviors but lacks details on error handling, token validation outcomes, or what the returned link looks like. It is adequate but not fully comprehensive.

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

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

The schema has 0% description coverage, but the description compensates by clarifying that the 'token' parameter is for pasting a JWT for session login, and that omitting it returns a link. It adds meaning beyond the schema's type/format.

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

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

The description clearly identifies the tool as an authentication mechanism for MCP.AI IDE agents, specifying the action (log in, copy token, paste or configure) and the resource (access token). It distinguishes from siblings like 'connect' and 'marketplace' by focusing 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 guidance on when to use each method: permanent via config header or session-only by pasting the token. It also explains the alternative of adding to config as the 'best' approach, though it doesn't explicitly list when not to use the tool.

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

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

Annotations already indicate safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds valuable context about response contents (authenticated, pending, URLs), which goes beyond annotations and helps the agent understand what to expect.

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

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

Two concise sentences that are front-loaded with the core purpose and then expand with conditional behavior. No superfluous 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?

Given zero parameters, presence of annotations, and no output schema, the description fully informs the agent about the tool's behavior and expected return values without needing further elaboration.

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

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

No parameters exist, so schema coverage is 100% by default. The description does not need to add parameter details, and the baseline score of 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 the tool returns connection status and URLs, distinguishing it from sibling tools like authenticate or openfinance_list_connections by focusing on a consolidated status view with authenticated flag and pending array.

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 check if all providers are connected or to get URLs when credentials are missing. It does not explicitly state when not to use, but the context of sibling tools implies it's for top-level status checking.

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: describes that invoke can run tools without installation, may return connect links for authentication or checkout links for payment, and that write actions require workspace owner/admin. This adds significant behavioral context not present in annotations.

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

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

The description is verbose but informative, front-loading the core purpose. It could benefit from more structured formatting (e.g., bullet points) for readability, but every sentence adds value.

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

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

For a complex tool with 15 parameters and no output schema, the description covers behavior, flow, edge cases (auth, payment), and permission requirements. It is largely complete but lacks parameter details.

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

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

With 0% schema coverage, the description partially compensates by explaining the action enum and hinting at parameter purposes (query for search, mcp_id for describe, etc.). However, many parameters (limit, immediate, conversation, etc.) remain unexplained, leaving gaps.

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

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

The description clearly states it is the official mcp.ai marketplace for discovering and running MCPs/tools. It outlines the core flow (search, describe, invoke) and distinguishes itself from sibling tools by being the primary registry and resolver.

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 any external registry. Provides clear when-to-use for each action (search, describe, invoke, install, etc.) and when to prefer invoke over install. Also covers credential and payment handling.

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 aligns with the destructiveHint annotation, explicitly stating data deletion. It also adds value by disclosing the return of a re-connection URL, which is not indicated by annotations. No contradictions.

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

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

The description is concise with two sentences, no redundant information, and provides essential information upfront.

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 one undocumented parameter, the description is incomplete. It does not specify what the parameter 'item' should be, undermining usability despite covering the basic behavior.

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

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

The sole parameter 'item' is not described in the description. Despite 0% schema coverage, the description fails to explain what 'item' represents (e.g., bank identifier). This is a critical omission that prevents correct usage.

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

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

The description clearly states the action (revokes consent and deletes connection data) and the resource (specific bank). It distinguishes from sibling tools by specifying a unique operation: disconnecting a bank and returning a re-connection URL.

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 the tool is used when a bank connection needs to be revoked. It provides context on the consequence (data no longer available) and a follow-up action (re-connection URL). However, it does not explicitly exclude cases or mention alternatives.

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

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

Rich behavioral details beyond annotations: explains it uses PATCH, polls up to ~60s, returns fields like status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out. Describes the behavior when wait is true vs false. Annotations only provide hints; description adds substantial 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?

Description is a single paragraph but front-loaded with the core action. All sentences add value. Slightly long but acceptable; could be more structured with bullet points, but still concise enough.

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

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

No output schema exists, so description fully explains the return object ({ results, errors }) and key fields. Covers both parameters, behavior variations, and error indicators (needs_action, timed_out). Complete for a tool of this complexity.

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

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

Input schema has 0% description coverage, so description fully compensates. For 'items', explains it accepts item_id, connector_id, or connector_name, and that omitting syncs all. For 'wait', explains fire-and-forget behavior. Adds complete 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 clearly states the tool's purpose: to force re-sync of bank connections and wait for completion. It distinguishes this from disconnecting/reconnecting and from checking status (via sibling tools like openfinance_get_item_status). The verb 'forces' and resource 'connections' 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?

Provides explicit when-to-use guidance: 'Use this when a balance or transaction list looks stale'. Also explains when to omit items vs specify selectors, and when to set wait: false for fire-and-forget. Lacks explicit when-not-to-use, but context is clear enough.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds critical behavior: credit accounts may return warning instead of error, and upstream unavailability degrades to last-synced balance with 'realtime: false'. 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 concise (three sentences) with front-loaded purpose, structured parameter info, and error handling details. Every sentence adds value without redundancy.

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

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

The description covers response shape, error conditions, and degradation behavior. However, it could elaborate on the structure of each result item. Given no output schema, it is comprehensive but not exhaustive.

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

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

With 0% schema description coverage, the description fully compensates by explaining the 'account_ids' parameter is an array of 1-50 strings, providing essential context absent from 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 returns real-time balance payload per account ID, specifying the HTTP endpoint. It distinguishes from sibling tools like openfinance_list_accounts and openfinance_get_accounts_detail by focusing on balance retrieval.

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

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

The description provides clear context on when to use the tool for balance queries but does not explicitly state when not to use or compare with alternatives. It covers parameter constraints and edge cases, offering good guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral context: batch response shape ({results, errors}), array limit of 1-50, and the provider_incident block warning about unreliable limits/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 compact, using three sentences to convey purpose, parameter constraint, batch shape, and a warning. Every sentence adds value. Could be slightly more streamlined but is 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?

Given the absence of an output schema, the description adequately covers the response shape and a critical edge case (provider_incident). The 1-50 array limit and batch error handling are included. For a read-only tool with annotations, this is sufficiently 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 one parameter (account_ids) with 0% description coverage. The description adds meaning by specifying it must be an array of strings with a size limit of 1-50. This compensates well for the schema's lack of descriptions.

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

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

The description clearly states the tool returns full account objects with extended creditData for given account IDs. It specifies the batch operation with an array and explicitly mentions the endpoint pattern. This distinguishes it from sibling tools like openfinance_list_accounts and openfinance_get_account_balance.

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 use for detailed account info beyond the list. It does not explicitly contrast with siblings or state when not to use it. However, the specific mention of extended creditData and batch shape helps an agent decide to use this over simpler 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 it as read-only, idempotent, non-destructive. The description adds vital behavior: returns batch { results, errors } shape, notes that Pluggy does not return paid/status field, and explains the subtle payment cycle behavior (payments[] may be previous bill's payment). No contradiction with annotations.

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

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

Description is detailed but well-structured with clear sections: main purpose, alternative tools, parameter guidance, important notes. Every sentence serves a purpose. Slightly verbose but justified given complexity.

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

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

Despite no output schema, the description adequately explains response fields (financeCharges, payments with subfields) and batch shape. Covers edge cases: Pluggy missing status, payment cycle interpretation, and sparse billId hints. Comprehensive for a financial bill detail 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?

Only one parameter `bill_ids` with 0% schema description coverage, so description carries full burden. It explicitly says 'Pass bill_ids as an array' and directs to openfinance_list_credit_card_bills to discover ids. This adds meaningful usage context 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 returns 'bill-level detail for one or more credit card bills by id' with specific fields (financeCharges, payments). It distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_credit_card_bills by explicitly stating what it does not return (transactions) and directing to those alternatives.

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

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

Provides explicit guidance: use when needing bill details, not for transactions; recommends using openfinance_list_credit_card_bills first to discover ids; warns against reconstructing bill totals from transactions; explains the payments[] caveat for Brazilian Open Finance. Clear when to use and when not, with alternative tool names.

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. Description adds detail about return shape for bulk ({ count, items }) and mentions executionStatus and connector metadata, enriching behavioral understanding 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?

Two sentences with no wasted words. Front-loads the purpose (returns status) and then provides usage guidance. Every sentence is necessary and 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?

Despite no output schema, the description outlines the return contents (status, executionStatus, connector metadata) and the shape for all banks ({ count, items }). For a simple read-only tool, this is sufficient for an agent to understand what to expect.

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

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

Input schema has 0% description coverage, but the description fully explains the semantics of the `item` parameter: omitting returns all banks (with count and items), passing it returns a single bank's status. This adds meaning beyond the basic schema definition.

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

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

Clearly states it returns the status of a bank connection with example statuses (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, and connector metadata. Differentiates between all banks (omit item) and single bank (pass item), distinguishing it from sibling tools like openfinance_list_connections.

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

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

Provides explicit instructions on when to omit vs. pass the `item` parameter for bulk vs. single status. Does not explicitly mention alternatives or when not to use, but the context is clear given the sibling tools (e.g., openfinance_force_sync for syncing).

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds detail about the batch response and endpoint, but 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?

Single paragraph, front-loaded with endpoint, efficiently lists fields and usage notes. 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 1-parameter tool with no output schema, description covers fields, constraints, and usage context. Sufficient for an AI agent to understand and invoke correctly.

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

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

Schema coverage is 0%, but description adds meaning by stating loan_ids is an array with size constraint (1-50) and response shape. Does not specify ID format but still adds value.

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 full loan contract detail by ID, lists specific fields, and distinguishes from sibling openfinance_list_loans by saying to use after it for deep-diving.

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 use after openfinance_list_loans, gives parameter constraints (array of 1-50 loan_ids), and describes response batch shape.

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?

Disclosures beyond annotations include connector-dependent credit balance meaning, provider_incident block for unreliable data, and the distinction between account name and bank brand. Annotations show readOnlyHint, idempotentHint, destructiveHint, which are consistent.

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 each sentence adds value: core purpose, naming nuance, usage options, credit warning, provider incident. It is front-loaded and well-structured, though slightly verbose for a single tool.

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

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

No output schema exists, so description must cover return values. It lists all fields (balance, type, bank, etc.), explains aggregation when item omitted, and addresses edge cases like provider incidents and credit balance interpretation. Very 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 coverage is 0%, so description must explain parameters. It thoroughly explains 'item' usage but does not explicitly describe the 'type' parameter (enum) or its effect when omitted. The description implies filtering by type but could be more precise.

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 accounts for a bank connection, specifying types (BANK/CREDIT) and data fields. It differentiates from siblings like openfinance_list_connections and openfinance_get_accounts_detail by explaining how to list all banks vs a single bank.

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

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

Provides explicit guidance on when to omit 'item' (all banks) vs pass 'item' (single bank), warns against misinterpreting credit balance, and directs to openfinance_list_credit_card_bills for standardized amounts. Also explains provider_incident handling.

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 result is cached for the session, and it is a single aggregated response with no batch ids. Annotations already mark it as 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 three sentences long, front-loaded with the main purpose, and every sentence adds value. No redundancy or wasted words.

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

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

For a simple list tool with no parameters, the description is comprehensive. It explains caching, output fields, and the connection to the update transaction category tool. Lacks explicit mention of when to retrieve categories (e.g., before updating transactions) but still adequate.

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

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

With no parameters and 100% schema description coverage, the baseline is 3. The description compensates by detailing the output structure, including the purpose of each field and the Portuguese translation note.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy, cached for the session, with explicit field details (id, description, descriptionTranslated, parentId, parentDescription). It distinguishes from sibling tools by being the only category listing tool.

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

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

The description indicates that the id is used by openfinance_update_transaction_category, providing a clear usage context. However, it does not explicitly state when not to use this tool or mention alternative tools.

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

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

Annotations already convey read-only and idempotent behavior. The description adds context about returned fields and the add_connection_url, which is beyond annotations but not contradictory.

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 sentence, no fluff. All information is relevant 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 no parameters and no output schema, the description sufficiently explains what the tool returns. Could mention if there is pagination or errors, but for a simple list, it's complete enough.

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 (0 params, 100% schema coverage). Description adds value by listing the fields returned, helping the agent understand output without an output schema.

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

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

The description clearly states the tool returns saved bank connections and lists specific fields (connector_id, item_id, bank name, add_connection_url). It distinguishes itself from siblings like openfinance_list_accounts 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?

Implicitly clear when to use: when needing to list saved bank connections. Not explicitly compared to alternatives, but the purpose is straightforward.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond these by explaining payment status derivation, connector asymmetry, open bill availability, and derived fields. There is no contradiction with annotations.

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

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

The description is long but front-loaded with essential information. Every sentence adds value, covering purpose, caveats, and usage nuances. It could be slightly more concise, but it maintains readability and 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?

Given the tool's complexity (5 parameters, no output schema, many edge cases), the description is remarkably complete. It covers payment status, open bill logic, connector asymmetry, bill grouping reliability, and cross-identification of accounts. No gaps identified for 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?

Schema description coverage is 0%, so the description must compensate. It thoroughly explains include_open_bill, account_id, and account_ids, but page and page_size are not explained (though they are common pagination parameters). Overall, the description adds significant meaning to the parameters.

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

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

The description begins with a clear statement: 'Returns CLOSED credit card bills for a CREDIT-type account' and enumerates the returned fields. It distinguishes this tool from sibling tools like openfinance_list_transactions by noting that this tool provides bill-level summaries, not 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 provides explicit when-to-use and when-not-to-use guidance, including the IMPORTANT warning about payment semantics, when to opt into include_open_bill, and a caution against attributing bills to the wrong bank. It also advises to use openfinance_list_transactions for itemized purchases.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds valuable context about fallback responses on errors and lists returned fields, enhancing transparency beyond annotations.

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

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

Two sentences, no wasted words. The first sentence states purpose and scope, the second adds details on return fields and error handling. Fully front-loaded and 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?

Given 4 parameters (all optional), no output schema, and no parameter documentation, the description is moderately complete. It explains return structure and error handling but ignores pagination and connection identification (e.g., '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?

Schema description coverage is 0%, and the description does not explain any parameters. It lists asset types that map to the 'type' enum, but fails to clarify 'item', 'page', or 'page_size', leaving the agent to infer from schema alone.

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

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

The description clearly states it returns investment portfolio for a connection, listing specific asset types and fields. It distinguishes from siblings like openfinance_list_accounts or openfinance_list_transactions by specifying 'investment portfolio'. However, it does not explicitly contrast with siblings.

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 investment holdings but does not specify when to use this tool versus alternatives like openfinance_list_transactions. It mentions error handling (returns warning instead of throwing) which provides some 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 concrete behavioral details like data returned and bulk support, which are beyond annotations. No contradictions.

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

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

Three sentences, each serving a distinct purpose: main functionality, prerequisite, and bulk support. No redundancy, 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?

Given no output schema, the description adequately describes return fields and transaction types. Provides prerequisite and bulk support. Slightly incomplete on pagination (page/page_size) but acceptable.

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 explains investment_id and investment_ids (bulk support) but does not describe page and page_size. Core parameters are covered, but not all, so partial 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?

The description clearly states it returns movement history for an investment position, enumerating transaction types (BUY, SELL, TAX, etc.) and listing return fields. It also instructs to use after openfinance_list_investments, differentiating it from that sibling.

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

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

Explicitly says to use after openfinance_list_investments to get investment_id and mentions bulk support for batched execution. Lacks explicit exclusion of when not to use, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral details like sequential querying with rate-limit spacing and the return structure, exceeding annotation coverage.

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

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

The description is two sentences, front-loads the purpose, and contains no superfluous information, making it 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?

Given the single parameter, no output schema, and annotations covering safety, the description sufficiently explains input, behavior, and output shape, leaving no critical 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?

Despite 0% schema description coverage, the description fully explains the 'items' parameter's purpose, allowed types (uuid, connector_id, connector_name), and the effect of omitting it, compensating for the lack of schema descriptions.

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

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

The description clearly states it lists loan contracts per bank connection, specifies the endpoint, and distinguishes from sibling tools by focusing on loans versus accounts or 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?

It provides explicit guidance on when to include or omit the 'items' parameter, but does not mention when not to use the tool or alternative tools for similar tasks.

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, and destructiveHint=false. The description adds substantial behavioral context beyond annotations, including pagination auto-paginate vs manual, detail levels (compact/rich/raw) with their token costs and coverage variability, error handling returning structured errors, and provider incident handling. 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 very long (multiple paragraphs) and contains some redundancy (e.g., creditCardMetadata.billId warnings appear twice). While well-structured with clear sections (pagination, detail levels, etc.), it could be tightened without losing essential information. Not efficient in word count.

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 complex tool with 8 parameters, no output schema, and many sibling tools, the description is remarkably complete. It covers handling of zero results, pagination limits and truncation, error responses, provider incidents, connection health checks, and bulk support. No critical gaps are apparent.

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

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

Schema description coverage is 0%, so the description must compensate fully, which it does. It explains all 8 parameters, including date format (ISO YYYY-MM-DD), search_queries behavior (case- and accent-insensitive, OR semantics, 5000 limit), pagination parameters (page and page_size with max 500), detail enum values (compact/rich/raw) with detailed explanations, and account_ids for bulk. Adds meaning far 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 transactions for a bank account (BANK or CREDIT type)' and distinguishes its unique role for CREDIT accounts as the only way to get itemized transactions. It also contrasts with sibling tools like openfinance_list_credit_card_bills, making the purpose specific and unambiguous.

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

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

Provides extensive guidance: when to use this tool (e.g., for credit card itemization), when not to (e.g., do not reconstruct billing totals), and explicitly names alternatives (openfinance_list_credit_card_bills for standardized totals, openfinance_list_accounts for closing/due dates, openfinance_get_item_status for connection health). Clearly states exclusions and context-dependent usage.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds value by explaining the compact vs raw output structure, truncation flag, provider incident block, and enrichment with merchantInfo/creditCardMetadata. 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 fairly long but front-loads core purpose and key behaviors. Each sentence adds valuable information, though some redundancy exists (e.g., mentioning 'compact summary' multiple times). Bolded terms aid 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 7 parameters, no output schema, and high complexity, the description covers all aspects: use cases, parameters, output structure (compact vs raw, per-account breakdown, top expenses), limitations (truncation), and special cases (provider incident). Little else 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?

Schema has 0% description coverage, so description carries full burden. It explains each parameter: item accepts multiple identifier forms, from/to are ISO dates, granularity and detail enum meanings, type filters account types, top_n for largest entries. Provides enough context for an agent to set parameters correctly.

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 performs consolidated cash-flow analysis for a bank connection in one call, resolving accounts internally. It names specific use cases ('análise anual/mensal', 'fluxo de caixa') and distinguishes from sibling tools like openfinance_list_transactions by eliminating the need to call openfinance_list_accounts.

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

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

Explicitly tells when to use this tool vs alternatives: 'you do NOT need to call openfinance_list_accounts first'. Provides conditions for parameters (e.g., pass item for one bank, omit for all; use granularity:'raw' when itemized rows needed; detail levels). Also mentions truncation at 5000 transactions per account.

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, idempotent, non-destructive. Description adds detail that it checks a public status page and returns global indicator, degraded components, open incidents, and flags affecting connected banks. No contradictions; fully transparent about behavior 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: first explains purpose and distinguishes from sibling; second gives usage guidance; third lists return value. No filler, each sentence earns its place. Front-loaded with key action.

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

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

For a zero-parameter tool with no output schema, the description covers purpose, usage scenario, return structure, and differentiation from sibling tools. There is no missing information needed for correct invocation.

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

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

Input schema has 0 parameters (schema coverage 100%), baseline is 4. Description adds no parameter info because none are needed. It does not waste space explaining absent 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 checks the LIVE operational status of the Open Finance provider's public status page, and explicitly distinguishes itself from 'openfinance_get_item_status' by specifying it is the provider's health, not the connection's. Verb is 'Checks', resource 'provider status', scope 'provider vs 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 says when to use: 'whenever data looks incomplete or stale even though a connection shows UPDATED...' and explains it helps differentiate provider-side problems from connection issues. Provides clear context and alternative (openfinance_get_item_status).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds useful behavioral details: returns connect_url, honors user's plan, caveat warnings, and never dumps the whole catalog. However, there is a minor discrepancy where description says keywords is REQUIRED but schema does not mark it required.

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 multi-sentence description with each sentence adding value. Front-loaded with purpose, structured logically, 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?

Describes return fields in detail (connector id, access, audience, existing connections, accounts, connect_url, caveat). Missing output schema but description compensates well. Lacks mention of error handling or result limits but adequate for search 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 explains both parameters: keywords (required, search by name, examples) and include_accounts (boolean, returns accounts when true). Lacks default values but sufficient for agent understanding.

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

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

The description clearly states the tool searches bank connectors by name, returns specific fields including a connect_url, and distinguishes itself from sibling tools like connect or list tools by explicitly instructing to call it before connecting.

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

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

Provides explicit when-to-use guidance: 'Call this BEFORE connecting', requires keywords[] or returns a hint, and advises preferring Open Finance connectors for automation based on caveat information.

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 provides essential behavioral context beyond annotations: it explains that recategorizing automatically creates a Category Rule for future similar transactions (case-insensitive exact match), and describes batch error handling (per-item errors do not fail the whole batch). This is significant and not covered by 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, starting with the main action and then providing details. It is moderately long but every sentence adds value. Minor reduction for slightly verbose explanation of the side effect, 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 no output schema, the description provides a complete output shape and explains batch behavior and side effects. It could mention prerequisites like authentication, but the sibling 'authenticate' tool exists. Adequate for a write 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 the purpose of each field: transaction_id comes from openfinance_list_transactions, category_id from openfinance_list_categories. It also describes the response structure with updated, results, and errors arrays, which is not present in the input 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 action ('Corrects the category of one or more transactions') and specifies the HTTP method and endpoint (PATCH /transactions/:id). It also distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_categories by focusing on updating categories.

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

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

The description explicitly tells when to use this tool ('fix miscategorized transactions') and where to obtain the required IDs (from openfinance_list_transactions and openfinance_list_categories). However, it does not explicitly state when not to use it or mention alternative tools, but the context is clear.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description does not contradict them and adds the importance of including conversation for reproduction. However, it does not disclose what happens upon submission (e.g., ticket creation, email), rate limits, or authentication requirements.

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

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

The description is concise (two sentences) and front-loaded with the purpose. No unnecessary words, but could be slightly more formal.

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?

Lacks output schema, and the description does not explain return values or success/failure behavior. For a simple feedback tool with 3 parameters, it is minimally complete but missing parameter semantics limits its usefulness.

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%. The description only mentions 'conversation array' but fails to explain the other parameters ('context', 'message'), their purpose, or expected formats. This is a significant gap for a 3-parameter tool.

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 the tool's purpose: 'Report a bug, missing feature, or send feedback.' It specifies the verb and resource, distinguishing it from sibling tools that focus on authentication or finance 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?

The description provides guidance: 'Include the conversation array with recent messages for reproduction.' This helps the agent understand the required input context. However, it does not explicitly mention when not to use the tool or provide alternatives for similar actions.

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, which clearly communicate safety and idempotency. The description adds the specific output context ('MCP platform and adapter versions') but does not disclose additional 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 directly states the tool's function with no extraneous words. It is front-loaded and 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 tool with no parameters and a well-defined output (versions), the description is complete. It adequately informs the agent about what the tool returns, and the lack of an output schema is acceptable given the 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 no parameters and schema coverage is 100%. The description does not need to add parameter information beyond the schema, as there are none. 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 uses the specific verb 'show' and clearly identifies the resource as 'the current MCP platform and adapter versions', making the tool's purpose unambiguous. It distinguishes itself from siblings like 'toolkit_info' by focusing specifically on 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 provides no guidance on when to use this tool versus alternatives, such as 'toolkit_info' or other informational tools. An explicit recommendation or exclusion would improve clarity.

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 as safe. The description adds value by specifying the exact content returned, which is beyond annotations. No contradictions present.

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, clear sentence that front-loads the core purpose without any fluff. Every part of the sentence adds value, earning a perfect score.

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 the return value (installed MCPs, connection status, catalog tools count). However, it could be more detailed about format or return type, but for a zero-parameter tool it is reasonably complete.

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

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

With zero parameters, schema coverage is trivially 100%. The description adds the meaning of the return value, which is necessary because there is no output schema. It provides context beyond the schema, justifying a baseline of 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?

The description uses a specific verb 'Returns' and a clear resource 'toolkit state', listing exact data points (installed MCPs, connection status, catalog tools count). It distinctly separates this tool from siblings like 'authenticate' or 'connect'.

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

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

The description states what the tool returns but does not explicitly guide when to use it versus alternatives. There is no mention of exclusions or when-not to use it. Given sibling tools include many financial operations, guidance would be beneficial.

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