Íon MCP

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

Annotations indicate idempotentHint=true, destructiveHint=false, readOnlyHint=false. The description clarifies behavioral outcomes: non-expiring vs session-only, and explains what happens when called with or without token. 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 a single sentence but efficiently covers key points. It front-loads the core action ('log in in the browser, copy the access token'). Every clause adds value, though it is slightly run-on.

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

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

Given the simple nature of the tool (one optional parameter, no output schema), the description covers the essential usage scenarios. It could mention the return value or error conditions, but overall it is sufficient for an AI agent to use the tool correctly.

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

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

The only parameter (token) is explained in detail: it is the JWT token obtained from browser login. The description clarifies the two usage patterns (with token, without token). Schema coverage is 0%, so the description fully compensates.

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

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

Clearly states the tool's purpose: authenticating a user by providing a token or getting a login link. It specifies the resource (authentication) and the action (log in, get token), and distinguishes from siblings like 'connect' or 'marketplace' which are different.

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 two modes: permanent via config and session-only via token. It tells the agent to call with no args to get the link or with token to log in. It also suggests the best practice. While it doesn't explicitly list alternatives, the context is clear for a singleton authentication tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing the response in two scenarios (all connected vs. missing credentials), which is behavior not captured in annotations. 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?

Two sentences, front-loaded with the core purpose, and each sentence provides distinct 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?

Given zero parameters and annotations covering safety, the description explains the key scenarios. However, it does not elaborate on possible additional response fields (e.g., authenticated status for individual providers), which might be inferred from the pending array. Still adequate for a simple status 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?

Tool has zero parameters, so schema coverage is trivially 100%. The description does not need to explain parameters, and it does not add unnecessary information. 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 specifies the tool returns connection status and URLs, with clear differentiation between fully connected state (authenticated:true, empty pending[]) and missing credentials (returns connect_url and per-install URLs). This distinguishes it from sibling tools like authenticate or openfinance_list_connections.

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

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

The description implies the tool is used to check connection status and retrieve URLs when credentials are missing. While it does not explicitly state when not to use or name alternatives, the context of siblings and the clear purpose make usage relatively 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?

The description discloses all key behaviors: write operations (install, uninstall, subscribe, cancel, invoke's one-off install) require owner/admin. It explains that invoke runs a tool without permanent addition, and that search/describe flags installation status. No contradiction with annotations (readOnlyHint=false is 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?

The description is comprehensive but lengthy and somewhat bloated. It front-loads the core purpose but then delves into many details in dense paragraphs. While every part is informative, the structure could be more succinct or broken into sections for easier parsing.

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

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

Given the tool's complexity (15 parameters, no output schema, multiple actions), the description is remarkably complete. It covers all actions, parameters implicitly, error handling (credentials, payment), ownership requirements, and distinguishes sibling tools. No gaps in essential context.

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

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

With 0% schema description coverage, the description must compensate. It does so by narratively explaining the usage of key parameters (action, query, mcp_id, tool_id, arguments) within the workflow. However, it lacks explicit, structured parameter definitions, leaving some inference required.

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

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

The description clearly identifies the tool as the official mcp.ai marketplace for discovering and running MCPs. It explicitly states to use this tool FIRST before external registries, and distinguishes from sibling tools by outlining the core workflow and when to use invoke vs install vs list_tools.

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

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

The description provides explicit guidance on when to use the tool (for capability searches, running MCPs) and when to use alternatives. It details the recommended flow (search -> describe -> invoke), explains when to prefer invoke over install, and covers edge cases like missing credentials or empty wallet.

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

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

Annotations already indicate destructiveHint=true, but the description adds details: revokes consent, deletes data, makes it unavailable, and returns a reconnection URL. This provides useful behavioral context beyond annotations.

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

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

Three succinct sentences covering action, consequence, and return value. No wasted words, front-loaded with main 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?

Covers purpose, behavioral effect, and return value adequately for a simple one-parameter tool without output schema. Missing parameter guidance, but otherwise 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 schema has one parameter 'item' with no description, and the tool description does not explain what 'item' refers to (e.g., bank identifier format). With 0% schema description coverage, the description should compensate but doesn't.

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 'revokes' and 'deletes' with specific resources 'Open Finance consent' and 'connection data'. It distinguishes itself from sibling tools like openfinance_list_connections by focusing on disconnection.

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 for disconnecting a bank, but no explicit guidance on when to use this vs alternatives like openfinance_force_sync. Could provide context for prerequisites or when reconnection is needed.

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 that it is a mutation (forces sync) but not destructive (no disconnect). Explains polling up to ~60s, response fields (status, executionStatus, lastUpdatedAt, synced), error conditions (needs_action like LOGIN_ERROR), and timeouts. Also mentions wait: false for fire-and-forget. This adds significant 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?

Description is informative and well-structured, front-loaded with the main action. While it is somewhat lengthy, every sentence adds value and there is no redundancy. Could be slightly more concise, but still effective.

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

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

Given the tool's complexity (2 params, no output schema), the description covers return values, timeout behavior, error conditions, and usage variations. It is complete for an AI agent to invoke correctly.

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

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

With 0% schema description coverage, the description compensates fully. It explains that 'wait' defaults to true (waits) and false is fire-and-forget. For 'items', it explains it as an array of selectors (item_id, connector_id, or connector_name) and that omitting it syncs all. This adds essential 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 it forces a bank to re-sync one or more connections and waits for it to finish, using PATCH and polling. It distinguishes from siblings by explaining the explicit action (force re-sync) and that it doesn't disconnect.

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

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

Explicitly states when to use: when a balance or transaction list looks stale, connection can read UPDATED yet be hours old. It explains pulling fresh data without disconnecting/reconnecting. It also mentions omitting items to sync all, and provides an alternative (openfinance_get_item_status) for timed_out cases.

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, idempotentHint), the description adds critical behavioral context: CREDIT accounts may return a structured warning instead of throwing an error, and the response shape includes errors array. This adds significant value.

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, front-loaded with the core operation, and contains no redundant information. 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?

With no output schema, the description explains the response format and error handling adequately. The single parameter is well-documented. All necessary context for a simple read tool is provided.

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

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

The schema has 0% coverage, leaving the parameter undocumented. The description explicitly states that 'account_ids' should be passed as an array with 1–50 items, which is essential information not present in the schema.

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

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

The description clearly states the verb ('returns'), resource ('real-time balance payload per account id'), and includes the HTTP endpoint. It distinguishes from siblings like 'list_accounts' by focusing on balance retrieval for specific account IDs.

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

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

The description provides guidance on handling errors for CREDIT accounts and the response shape, but it does not explicitly state when to use this tool versus alternatives or when not to use it. No comparison with siblings is provided.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds valuable behavioral info: provider_incident block and unreliable data during provider incidents. Exceeds annotation baseline.

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 and well-structured: main purpose first, then batch shape, then warning. Each sentence adds value; 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?

Explains return shape ({results, errors}) and special provider_incident block. Lacks full structure of account objects but plausible given tool name. Adequate 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 has 0% description coverage. Description compensates by specifying account_ids is an array of strings with size constraint 1-50, adding 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 it returns full account objects with extended creditData per ID, and specifies the batch shape and potential provider_incident block. It distinguishes from sibling tools like openfinance_list_accounts by focusing on per-ID detail.

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

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

Provides usage constraints: pass account_ids as an array of 1-50 items. Does not explicitly state when to use this over alternatives or when not to use it. Lacks comparison with sibling tools like openfinance_get_account_balance.

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

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

Adds significant context beyond annotations: explains batch shape { results, errors }, notes Pluggy does not return paid/status field, clarifies payments[] are from this billing cycle and typically for previous bill, and warns not to assume paid status. Annotations provide readOnlyHint but description adds vital usage nuances.

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 well-structured: starts with return info, then exclusions, usage instructions, batch shape, and behavioral caveats. Each sentence adds value; slightly verbose but necessary for a complex finance 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?

Given no output schema, description covers main output shape { results, errors } and key fields. It explains limitations and alternatives. Missing explicit detail on result object structure but sufficient for agent to use correctly.

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

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

Schema has single parameter bill_ids as array with 0% description coverage. Description compensates by stating to pass bill_ids as an array and suggests using openfinance_list_credit_card_bills first. Adds practical guidance but does not detail array item constraints.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by id, specifying fields like financeCharges and payments[]. It distinguishes from the sibling that lists bills and explicitly says what it does NOT return (individual transactions), directing to openfinance_list_transactions.

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

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

Provides explicit when-to-use: first use openfinance_list_credit_card_bills to discover ids, then this tool; for itemized transactions use openfinance_list_transactions. Includes caveat about checking paid status via another tool, and warns about payments[] semantics.

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 value by detailing the return data (status, executionStatus, connector metadata) and the two response modes.

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 superfluous words. Front-loaded with purpose, then parameter guidance.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all necessary context: purpose, parameter behavior, and response structure.

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 fully compensates: explains the effect of omitting vs. passing `item`, and describes the response shapes (`{ count, items }` for all). No ambiguity.

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 bank connection status, lists specific statuses, and distinguishes behavior based on the `item` parameter. It differentiates 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?

Explicitly explains when to omit `item` (all banks) and when to pass it (single bank), with return formats. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive. The description adds context about batch processing and the array limit, enhancing transparency 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?

Three sentences covering output, usage, and parameter specification. No redundant words, well front-loaded with the 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?

Despite lacking output schema, description enumerates key output fields and specifies the batch error handling shape, making it fairly complete for a single-parameter read-only tool.

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

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

Schema parameter 'loan_ids' has 0% coverage. Description adds 'Pass loan_ids as an array (1-50)', indicating type and length constraint, which compensates effectively.

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 full loan contract detail by id' and lists the returned fields, distinguishing it from sibling tools like openfinance_list_loans.

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 'Use after openfinance_list_loans to deep-dive on a specific contract' and provides constraints on the array size (1-50) and batch shape, though it doesn't explicitly mention when not to use.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, so safety profile is known. Description adds critical context: may include provider_incident block, unreliable balances during provider incidents, and the specific meaning of credit balance being connector-dependent. 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 well-structured. Key information is front-loaded (what the tool returns). Each sentence adds value, though some redundancy exists (e.g., repeating balance caution). No wasted sentences.

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

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

With no output schema and only schema coverage, the description provides extensive context on usage, caveats (provider incidents, balance meanings), and relationships to other parameters. It covers most aspects a user would need, except for missing explicit filter effect of 'type' 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 coverage is 0%, so description must explain parameters. The 'item' parameter is well explained (optional, for single bank). However, the 'type' parameter (enum BANK/CREDIT) is not explicitly described as filtering accounts; the description only mentions types in the response context. This is a gap.

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

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

The description clearly states the tool returns accounts for a bank connection, specifies sub-types (BANK/CREDIT), and lists returned fields like balance, number, type, subtype, bankData, creditData. It also distinguishes between account name and bank brand, and differentiates from sibling tools like openfinance_list_credit_card_bills.

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

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

Explicitly explains when to omit 'item' (to list all accounts) vs when to pass 'item' (for a single bank). Provides alternative tool for credit card bills when standardized amounts are needed. Also warns about connector-dependent credit balance meaning.

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

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

The description adds valuable behavioral context beyond annotations: it specifies that results are cached per adapter session and that the response is a single aggregated batch (no batch ids). Annotations already declare readOnlyHint and idempotentHint, which are consistent. No contradictions.

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

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

The description is concise—three sentences front-loaded with the core purpose. Every sentence adds value: source, caching, key fields, and usage hint. 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 the return value structure and behavior (caching, single aggregated response). It covers all aspects needed for an agent to understand what the tool does and what it returns.

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

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

The tool has zero parameters, and schema coverage is 100% trivially. The description does not add parameter semantics (since none exist), but it does describe the return object fields. According to guidelines, baseline 3 is appropriate when schema coverage is high and no param info is needed.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy from the GET /categories endpoint, cached per session. It lists the key fields (id, description, descriptionTranslated, parentId, parentDescription) and notes the categoryId is used by another tool. This distinguishes it from sibling tools like openfinance_list_transactions.

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

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

The description implicitly guides usage by mentioning that the 'id' field is the categoryId used by openfinance_update_transaction_category, indicating this tool provides the necessary IDs for updating transaction categories. It also states 'Single aggregated response — no batch ids,' clarifying the output format. However, it does not explicitly state when to use or not use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's mention of returning fields adds some context but no additional behavioral traits like pagination or rate limits. No contradiction.

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

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

Single sentence, approximately 20 words, front-loaded with the action (returns) and resource (saved bank connections). No redundant 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?

No output schema, but the description lists returned fields. It does not mention pagination or error handling, but for a simple list with no parameters, it is fairly 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 and 100% schema coverage, the baseline is 4. The description does not add parameter info, but that is acceptable as none exist.

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

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

The description clearly states the tool returns saved bank connections, listing specific fields (connector_id, item_id, bank_name, add_connection_url). It distinguishes itself from siblings like list_accounts or list_transactions 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?

The description implies usage for viewing existing connections and obtaining a URL to add more, but does not explicitly state when to use this over alternatives like 'connect' or 'marketplace'. No exclusions 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?

Beyond annotations (readOnlyHint, etc.), the description reveals complex behavioral details: payment cycle semantics, derived payment_status logic, cross-bill payment detection, open_bill derivation from pending transactions, and connector-specific limitations. 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 verbose but every sentence adds value. It is front-loaded with the main result and important caveats, then details opt-in and connector asymmetry. Could be slightly more structured, but the density of information is necessary for this complex 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?

Given the complexity of Brazilian Open Finance and no output schema, the description is thorough: it details all return fields, the derived payment_status, cross-bill payment logic, open_bill derivation, connector asymmetry, and error handling (warning instead of failure). It even explains when to use sibling tools.

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 each parameter: account_id (type), include_open_bill (opt-in, default false, effect), account_ids (bulk), and pagination (page, page_size implied). It also clarifies that results are bill-level summaries, not transactions.

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 distinguishing from the sibling tool openfinance_list_transactions for itemized transactions. It also differentiates from openfinance_get_credit_card_bill by implying this is for list/batch.

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

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

The description provides extensive when-to-use guidance, including instructions to use openfinance_list_transactions for itemized purchases, warnings about payment status interpretation, and the opt-in nature of include_open_bill. It also explains connector asymmetry and when to expect limited data.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing error behavior (returns warning on 403) and describing the response structure. 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 concise, only two sentences, and front-loads the main purpose with specific asset types. It could be structured with bullet points for better readability, but no information is wasted.

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 provides good detail on output fields and error handling, but lacks parameter descriptions. Given the complexity of the tool (4 optional params, no output schema), the description is moderately complete but has significant 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?

The description provides no information about the input parameters (item, page, type, page_size). Schema description coverage is 0%, so the description fails to compensate. Without parameter guidance, an AI agent cannot properly construct calls.

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 investment portfolio data for a connection with INVESTMENTS enabled. It lists specific asset types (FIIs, stocks, ETFs, etc.) and distinguishes from sibling tools like openfinance_list_accounts.

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

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

The description specifies when to use (for connections with INVESTMENTS product enabled) and how errors are handled (returns warning instead of throwing). It could be improved by explicitly stating when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by detailing returned fields (e.g., expenses, agreedRate) and bulk support. It does not contradict annotations and covers behaviors beyond them, though it omits rate limits or authentication needs.

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

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

The description is brief (three sentences), front-loads the core purpose, and avoids fluff. However, it could be slightly tighter by merging the first two lines, but overall it is well-structured for quick parsing.

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

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

Given the moderate complexity (4 params, no output schema), the description adequately covers the tool's purpose and output content but lacks parameter details and a complete return value specification. The absence of output schema is not compensated by a structured description of the return format.

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. It only mentions investment_id contextually and investment_ids for bulk, but fails to describe page, page_size, or provide complete parameter semantics. This leaves the agent guessing about syntax and constraints.

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

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

The description clearly states the tool returns 'movement history for a specific investment position' and lists transaction types (BUY, SELL, etc.). It distinguishes itself from sibling tools like openfinance_list_transactions by being investment-specific and explicitly references openfinance_list_investments for prerequisite context.

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 by stating 'Use after openfinance_list_investments to get the investment_id,' indicating a prerequisite. However, it does not explicitly exclude alternative tools or provide when-not-to-use guidance, leaving some ambiguity with closely related siblings like openfinance_list_transactions.

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

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: sequential queries with rate-limit spacing, return format with results/errors per connection. 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?

Two sentences: first states purpose, second details parameter usage and return format. Every sentence adds value; no redundancy or irrelevant info.

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 annotations (safe, idempotent, read-only) and single parameter with no output schema, the description fully covers what the tool does, how to use parameters, and what to expect (results/errors per connection). 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?

Input schema has no description for `items` (0% coverage). Description specifies that items are connection selectors (item_id uuid, connector_id, or connector_name) and how omitting changes behavior, providing essential 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?

Description starts with a clear verb and resource: 'Lists loan contracts per bank connection (GET /loans)'. It immediately distinguishes from sibling tools like list_accounts or list_transactions by specifying loan contracts and the per-connection 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?

Explicitly explains how to use the `items` parameter: pass connection selectors for specific connections or omit for all linked banks. Mentions rate-limit spacing for multiple connections. Does not provide when-not-to-use or alternatives, but context is clear.

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

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

The description goes far beyond annotations by detailing behavioral nuances: different behavior for BANK vs CREDIT, PENDING/POSTED variation by connector, upstream error handling returning special structure, pagination and truncation details, detail levels, and provider incident block. No contradiction with annotations (readOnlyHint indicates read operation).

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

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

The description is well-structured with logical sections and is front-loaded with core purpose. However, it is quite verbose and could be more concise while retaining all necessary information. The level of detail is justified by the tool's complexity.

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

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

The description is exceptionally complete given the tool's complexity and lack of output schema. It covers all parameters, behaviors, error handling, relationships to siblings, and even edge cases like provider incidents and batch execution.

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 fully compensates by explaining all parameters: dates, pagination, detail enum, search_queries, batch support, and constraints like max 5000 and truncation behavior. Each parameter's meaning and behavior is clearly described.

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

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

The description clearly states the tool returns transactions for BANK or CREDIT accounts, and explicitly distinguishes from sibling tools like openfinance_list_credit_card_bills and openfinance_list_accounts, specifying that for CREDIT accounts this is the ONLY way to get itemized transactions.

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

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

Provides explicit guidance on when to use this tool versus alternatives: for CREDIT accounts it is the only source for itemized transactions, for open bill totals use openfinance_list_credit_card_bills, for card statement dates use openfinance_list_accounts, and for connection health use 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?

Adds significant behavioral traits beyond annotations: resolves accounts internally, fans out transactions, caps at 5000/account with truncation flag, provider_incident block warning that totals may be incomplete, and that reconnecting does not fix it. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint 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 detailed but front-loaded with main purpose. Logical progression: main use, then parameter details, then warnings. Could be slightly more concise, but the complexity of the tool justifies the length. No redundant sentences.

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, description fully explains return values: compact summary (totals, monthly evolution, top expenses/recebimentos, per-account breakdown) and raw rows with optional detail enrichment. Also covers provider incidents and truncation. Completeness is high for a complex tool.

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

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

Schema coverage is 0%, so description must explain parameters. It explains item, from/to, granularity, detail, type, and top_n (implicitly via 'largest N'). Adds semantics like 'omit item to analyze ALL linked banks' and default granularity:'monthly' returns compact summary. Slight gap: top_n is not explicitly mapped to the parameter name, but context makes it clear.

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?

Clear verb+resource: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' Distinguishes from siblings like openfinance_list_accounts (no need to call first) and openfinance_list_transactions (this fans out account-level transactions internally).

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: for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'. Also explains when to set granularity:'raw' for itemized rows. Lacks explicit exclusions (e.g., when to prefer openfinance_list_credit_card_bills), 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds valuable behavioral details: returns 'global indicator', 'degraded components', 'open incidents', and flags incidents affecting your banks. 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?

Single paragraph, front-loaded with purpose, followed by use case and return details. Every sentence adds value; no redundancy or 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 parameters and no output schema, description fully covers purpose, trigger conditions, and return structure. Sufficient for agent to select 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?

Tool has zero parameters (schema coverage 100%). Description does not need to explain params. Baseline 4 applies as no additional param info is needed.

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

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

Description specifies it checks 'LIVE operational status of the Open Finance provider (its public status page)', clearly distinguishing from sibling 'openfinance_get_item_status' which checks connection-level health. Verb (checks) + resource (provider status) is specific and differentiates from similar tools.

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

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

Explicitly states when to use: 'whenever data looks incomplete or stale even though a connection shows UPDATED', and explains why (reveals upstream outage/known incident). Mentions separation from alternative tool but does not list explicit exclusions. Provides actionable context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds critical behavioral context: non-Open-Finance connectors have a 'caveat' warning about manual reconnection, and it honors the user's plan. 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 a single paragraph but well-structured: main purpose first, then details, caveat, and usage instruction. It is reasonably concise for the amount of information provided, though could be slightly more compact.

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 explains what is returned (connector id, access, audience, linked connections, accounts conditionally, connect_url). It also covers the caveat and plan filtering, leaving no major gaps for the agent.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains both parameters: keywords (array of strings, with example) and include_accounts (boolean). However, it says keywords is REQUIRED while the input schema marks it as optional (0 required parameters), creating a minor inconsistency.

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 lists the exact information returned (connector id, access type, audience, linked connections, connect_url). It distinguishes from siblings like 'connect' and 'marketplace' by specifying it's a pre-connection search 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 explicitly says 'Call this BEFORE connecting' and notes that 'keywords[] is REQUIRED — without it returns a hint (never dumps the whole catalog).' It also mentions plan-based filtering, providing clear when-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?

The description discloses key behaviors: overrides Pluggy's automatic categorization, teaches Pluggy by creating a Category Rule, batch behavior (per-item errors don't fail whole batch), and response format. This adds substantial context beyond annotations (which only indicate non-readOnly, non-destructive). 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 fairly long but every sentence adds value. It front-loads the main action and then explains side effects and batch behavior. Minor redundancy could be tightened, but overall 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 complexity (mutating tool with side effects, batch processing, no output schema), the description is comprehensive. It covers prerequisites, behavior, error handling, and response format. 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?

Despite 0% schema description coverage, the description provides detailed parameter semantics: items is an array of { transaction_id, category_id }, with explicit sources (from openfinance_list_transactions and openfinance_list_categories). It also explains the response structure, fully compensating for schema 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 states the verb 'Corrects the category' and resource (PATCH /transactions/:id). It clearly 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 explains when to use: to fix miscategorized transactions and improve categorization. It references sibling tools for getting IDs (openfinance_list_transactions, openfinance_list_categories) and describes the side effect of creating a Category Rule. It lacks explicit when-not-to-use, but context is clear.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false, so the tool is safe to retry. The description adds advice on including conversation but doesn't elaborate on behavioral traits beyond what annotations already provide.

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

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

The description is two sentences with no unnecessary words, efficiently conveying the purpose and a key usage tip.

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 provides the core purpose and a usage hint but lacks details on parameter formats, response, and other output. Given no output schema, more detail would be helpful.

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 the conversation parameter (as an array of messages) and implicitly the message. The context parameter is not explained.

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 reporting bugs, missing features, or feedback. It is distinct from the provided sibling tools which are mostly authentication and financial services.

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 including the conversation array for reproduction, giving clear usage guidance. It doesn't explicitly state when not to use, but the context with unrelated siblings makes it obvious.

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 false. Description adds that it shows platform and adapter versions, which is consistent but adds minimal 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 sentence, front-loaded with purpose, zero wasted words. Ideal 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?

For a simple version tool with no parameters, the description is sufficient. It could mention return format but is adequate given low 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?

No parameters exist, so description doesn't need to add param details. Baseline score of 4 is appropriate as per guidelines for 0-parameter tools.

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

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

Description clearly states the tool shows current MCP platform and adapter versions, using a specific verb and resource. With no sibling version tools, purpose is 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?

No explicit guidance on when to use or not use, but the tool is self-explanatory as a simple version display. No alternatives exist among siblings, making usage context clear enough.

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

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

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description adds value by specifying the exact data returned (installed MCPs, connection status, catalog tools count), providing behavioral context beyond the annotations.

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

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

A single sentence that is concise, front-loaded with the action, and contains no unnecessary words. Every part of the sentence provides 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?

The description fully explains what the tool returns, including the key components (installed MCPs, connection status, catalog tools count). Since there is no output schema, the description adequately covers the return value. No additional information 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?

The tool has no parameters, so baseline score is 4. The description does not need to add parameter information, and the schema coverage is 100% (no parameters to cover).

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 'Returns' and the resource 'current toolkit state', with specific details about what is returned (installed MCPs, connection status, catalog tools count). It distinguishes from sibling tools which are primarily authentication and financial data 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 implies usage for retrieving toolkit state, but does not explicitly state when to use or not use this tool versus alternatives. However, since no sibling tool serves a similar purpose, the context is clear and no exclusionary guidance is necessary.

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