PicPay MCP

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

Annotations already indicate idempotent and non-destructive. The description adds context about required user actions (copy token, paste), and behavior when called with no arguments (returns link).

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 slightly verbose but efficiently covers both authentication methods. Front-loaded with purpose and audience.

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 schema and no output schema, the description adequately covers authentication flows, token format, and no-arg behavior. Lacks return value details 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 coverage is 0% but the description thoroughly explains the sole parameter 'token': it's a JWT from browser login, optional for getting link, required for session authentication.

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

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

The description clearly states the tool authenticates for MCP.AI IDE agents, explaining both permanent and session-based methods. It distinguishes from siblings like connect and marketplace by focusing on user 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 instructions for two usage scenarios: adding token to config for permanent access or pasting token for session-only. It does not explicitly exclude alternatives, but the scope 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=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context by explaining response based on state (authenticated vs missing credentials), which is 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, front-loaded with main purpose, no extraneous information. Highly concise and well-structured.

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

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

For a zero-parameter tool with good annotations, the description provides sufficient context to understand what to expect. However, missing explicit return structure details could be improved.

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

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

No parameters, so baseline 4. Description adds value by explaining what the return contains in different states, partially compensating for lack of 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?

Description clearly states it returns connection status and URLs with examples for different states. Verb 'returns' specifies action and resource. However, it does not explicitly distinguish from sibling tools like authenticate, which is related.

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: check connection status. No explicit when-to-use or alternatives. Lacks guidance on when to use this vs authenticate or other connection-related 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 only include openWorldHint=true; description adds critical behavioral context: invoke can run tools without installing, may return connect/checkout links, writes require owner/admin. No contradiction with annotations (readOnlyHint=false aligns with mutating actions).

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

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

Description is long but well-structured: first sentence states purpose, then explains flow, then details invoke behavior, then contrasts install, then lists other actions. Front-loaded with critical info. Could be slightly more concise, 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?

Given 15 parameters, no output schema, and moderate complexity, the description provides a comprehensive overview of the tool's capabilities, actions, and usage patterns. Lacks some parameter-specific details but overall covers the main context needed for an agent to use it effectively.

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

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

Schema has 15 params with 0% description coverage. Description explains key parameters (action, mcp_id, tool_id, arguments, immediate, etc.) and enumerates action options with their purposes. Some params (limit, query, message, tier_slug, etc.) are not explicitly described, but the core parameters are well covered.

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

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

Description clearly states this is the official marketplace for discovering and running MCPs/tools, and explicitly says to use it first before any external registry. It distinguishes from sibling tools by explaining the core workflow (search → describe → invoke) and contrasts with related actions like install and 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?

Provides explicit guidance: 'use THIS tool FIRST', explains the standard flow (search→describe→invoke), and contrasts invoke vs install for one-off vs permanent use. Also notes that writes require owner/admin, and gives alternatives like list_tools, subscribe, cancel, report_bug, request_mcp.

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

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

Describes the destructive nature beyond annotations (deletes data, data no longer available) and mentions the return value, providing comprehensive behavioral context.

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

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

Two concise sentences front-load the action and effect, with no wasted words.

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

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

Covers the main action, effect, and return value, but the ambiguous parameter prevents full completeness for a one-param tool.

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

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

Schema coverage is 0% and the description does not specify what the 'item' parameter represents (e.g., connection ID or bank name), leaving ambiguity for the agent.

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

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

The description clearly states it revokes consent and deletes connection data for a specific bank, differentiating it from siblings like openfinance_list_connections. It also mentions the return of a reconnect 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 implicitly indicates when to use (to disconnect a bank) and provides the reconnection hint, but lacks explicit guidance on when not to use or 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?

Discloses key behaviors: waits up to 60s, polling mechanism, return fields (status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out). Annotations (readOnlyHint=false, destructiveHint=false) are consistent with a state-changing sync operation. 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 thorough but not overly verbose. It is well-structured: purpose, use case, parameter details, return value breakdown, error handling. Could be slightly tighter but each sentence adds value.

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

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

Given two parameters and no output schema, the description covers all essential context: how to invoke, return format, error states, timeout behavior, and post-sync actions. It is complete for an agent to select and 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?

With 0% schema description coverage, the description fully explains both parameters: 'wait' (fire-and-forget vs blocking) and 'items' (array of selectors or omitted for all). Adds concrete examples and behavior, compensating completely for the schema gap.

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

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

The description clearly states the tool forces a bank to re-sync connections and waits for completion. It specifies the verb 'forces', the resource 'connections', and the mode 'now and waits'. It distinguishes itself from sibling tools by noting it does not disconnect/reconnect, and provides a specific use case.

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'. Also provides guidance on what to pass (items array) and when to omit (sync all). It contrasts wait=true vs false, and tells the user to re-check with openfinance_get_item_status if timed_out.

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 readOnlyHint and idempotentHint as true. Description adds significant behavioral context: structured warning instead of throwing for CREDIT accounts, degradation to last-synced balance with realtime:false and warning for upstream failures. This goes well 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 concise (3-4 sentences) with no fluff. Front-loaded with the core purpose, then covers constraints and edge cases efficiently.

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

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

Despite no output schema, description fully explains the response shape, error handling details, and degradation behavior. It covers input constraints, multiple error scenarios, and response structure, making it complete for an agent to understand usage and outcomes.

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 for the single required parameter 'account_ids'. Description adds crucial semantics: it must be an array of 1-50 strings. This is essential for correct usage and significantly adds value 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?

Clearly states the tool returns real-time balance per account id, with the verb 'Returns' and resource 'real-time balance payload per account id'. Distinguishes from sibling tools like 'openfinance_list_accounts' by focusing on balance retrieval for given 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?

Provides explicit usage context: pass account_ids as an array of 1-50 items, and describes behavior for CREDIT accounts and unavailable institutions. Does not explicitly mention when not to use or alternative tools, but the detailed behavior description suffices for most agents.

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 and idempotent. The description adds critical behavioral context: batch shape with results/errors array, and a provider_incident block that can make credit limits/balances unreliable. This goes well 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 four sentences, front-loaded with the main purpose and parameter info. Each sentence adds value (batch shape, provider incident warning). Slightly wordy but not excessive.

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 single-parameter tool with no output schema, the description adequately covers the main output, batch shape, and a critical edge case (provider incident). It does not explain the full structure of account objects, but that is reasonable given the context.

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

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

The schema only defines account_ids as an array of strings with no constraints. The description adds the semantic meaning: 'Pass account_ids as an array (1–50)' and explains the batch shape. This compensates for the 0% schema coverage and adds practical usage guidance.

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 account objects including extended creditData per id', specifying the verb (returns) and resource (account objects with extended data). It distinguishes from sibling tools like openfinance_list_accounts by indicating this is a detailed endpoint per ID.

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

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

The description gives clear usage context: pass account_ids as an array (1–50), notes batch shape with results/errors, and warns about provider incidents. It does not explicitly state when not to use, but the context is sufficient for an agent to decide.

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. The description adds valuable behavioral context beyond annotations: batch shape, Pluggy missing paid/status field, Brazilian Open Finance payment semantics (payments[] reflects previous bill), and that individual transactions are not returned. 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 well-structured with a clear first sentence summarizing purpose, followed by essential details, warnings, and cross-references. Each sentence adds value without redundancy. Length is appropriate for the complexity of the tool's behavior.

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 describes the output shape (financeCharges, payments array with fields, batch shape), notes what is not returned (individual transactions), and explains edge cases (Pluggy, payment semantics). Completely covers what an agent needs to invoke and interpret results.

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

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

Schema coverage is 0%, so description must compensate. It explains that bill_ids should be an array and directs to use openfinance_list_credit_card_bills to discover valid IDs, providing practical guidance beyond the schema. Does not detail constraints like max length, but for a simple array of strings this is sufficient.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by ID, and explicitly differentiates from sibling tools like openfinance_list_credit_card_bills (for discovering IDs) and openfinance_list_transactions (for itemized transactions). The purpose is 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?

The description provides explicit guidance: first use openfinance_list_credit_card_bills to discover IDs, then pass them as an array; for transactions use openfinance_list_transactions with date range; warns not to reconstruct total from transactions; explains payment interpretation nuances. It clearly states when to use and when not to.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool is safe. The description adds value beyond annotations by detailing the return format (status values, count/items structure) and the effect of the `item` parameter, providing full transparency.

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

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

The description is two sentences with no wasted words. The first sentence states the core functionality, and the second explains the two usage modes. Every sentence adds value.

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

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

Given no output schema, the description sufficiently explains the return values and structure (status, executionStatus, metadata, and count/items wrapper). It is complete for a status-check tool with single optional 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?

The schema has 0% description coverage for the `item` parameter. The description fully compensates by explaining that omitting `item` returns all banks (with a wrapped response) and passing it returns a single bank's status, providing essential semantic clarity.

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

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

The description explicitly states it returns the current status of a bank connection, listing possible status values (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, and connector metadata. It distinguishes between fetching status for all linked banks vs. a single bank, which differentiates it from sibling tools like openfinance_list_connections or openfinance_provider_status.

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

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

The description provides clear usage guidance: omit `item` to get status for all linked banks or pass `item` for a single bank. It does not explicitly state when not to use the tool or mention alternatives, but the two modes cover common use 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?

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds batch envelope '{ results, errors }' and array size limit, but 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?

Single paragraph packed with information; front-loaded with main purpose. No fluff, but could be slightly restructured for readability.

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

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

Compensates for missing output schema by listing key output fields. Covers usage order, parameter details, and batch shape. Adequately complete.

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

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

Schema has no property descriptions (0% coverage). Description adds array size constraint (1-50) and batch hint, partially compensating for low coverage.

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

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

Clearly states it returns full loan contract detail by ID, listing specific fields. Distinguishes from sibling openfinance_list_loans by instructing to use after listing.

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

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

Explicitly says 'Use after openfinance_list_loans to deep-dive on a specific contract' and specifies array size limit 1-50.

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, indicating safe read operation. The description adds critical behavioral context: balance meaning for CREDIT is connector-dependent, provider_incident block may indicate unreliable data, and advises not to present those values as real. 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 verbose with multiple paragraphs, but it is well-organized and front-loaded with the main purpose. Some redundancy could be trimmed, but every sentence provides valuable information. Overall, it is structured effectively.

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

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

Given no output schema, the description provides comprehensive detail about the response structure: bank, connector_id, item_id, account types, balance meaning, creditData fields, provider_incident block. It also references the alternative tool for billing, ensuring completeness for a list tool.

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

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

Schema description coverage is 0%, so the description must compensate. It explains both parameters: 'item' (optional, string) with effect of omission vs. passing, and 'type' (enum with BANK and CREDIT) with context on what they represent. This adds substantial meaning beyond the minimal 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 accounts for a bank connection, listing specific types (BANK, CREDIT) and fields like balance, number, type, subtype, bankData, creditData. It distinguishes between listing all accounts (omit item) and targeting a single bank (pass item), 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' (user asks for 'my accounts/cards' without naming a bank) and when to pass 'item' (target a single bank). Also provides an alternative tool for standardized billing amounts, guiding the agent on which tool to use for specific needs.

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 that results are cached for the adapter session, which is useful behavioral context beyond what annotations provide. 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?

Three sentences, each concise and informative. Front-loaded with the core purpose, then details on entry structure 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?

Despite no output schema, the description fully explains the response structure: id, description, descriptionTranslated, parentId, parentDescription. It also clarifies caching and that it's a single aggregated response (no pagination or batching). Complete for a list tool.

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

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

No parameters exist (schema coverage 100%). Description does not need to add parameter semantics; baseline for zero parameters is 4. It could potentially note that no parameters are needed, but it already implies that by stating 'Single aggregated response — no batch ids.'

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 Pluggy's transaction category taxonomy, cached for the session, and specifies it corresponds to GET /categories. This distinguishes it from sibling tools like openfinance_list_transactions; it is the only category-specific tool.

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

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

Explicitly mentions that the 'id' field is used by openfinance_update_transaction_category, guiding when to use this tool prior to updating categories. It also notes that descriptionTranslated is preferred for pt-BR users, providing user-specific guidance. It does not explicitly exclude other contexts, 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 provide readOnlyHint, idempotentHint, destructiveHint, so safety is clear. Description adds the returned fields but no additional behavioral traits like external calls or pagination.

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, well-structured sentence with key information 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?

For a parameterless listing tool with good annotations, the description is fairly complete. Could mention if result is paginated or sorted, but not critical.

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, schema coverage 100%, so baseline is 4. Description does not need to add parameter info.

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 specifies the returned fields (connector_id, item_id, bank name, add_connection_url). It distinguishes from sibling list tools 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?

No guidance on when to use this tool versus alternatives, no prerequisites or context for selection among the many list 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?

The description discloses nuanced behavioral traits beyond annotations: payment cycle logic, derived payment_status derivation, open bill availability asymmetry, bill_grouping_reliability warnings, and connector-specific limitations. Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds critical context without contradiction.

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

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

The description is lengthy but well-structured with sections like 'IMPORTANT' and 'CONNECTOR ASYMMETRY'. Every sentence adds value for the complex domain, though some redundancy could be trimmed. It is appropriately front-loaded with the basic return 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, and the need for cross-tool references, the description is exhaustive. It covers return fields, derived fields, edge cases, warnings, and sibling tool guidance, enabling an agent to select and invoke the tool correctly.

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

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

With 0% schema description coverage, the description compensates well by explaining include_open_bill and account_id. However, it does not explicitly describe page and page_size parameters. While the bulk support implies account_ids, pagination is not addressed, which is a minor 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 it returns CLOSED credit card bills for a CREDIT-type account, lists key fields, and distinguishes it from other tools like openfinance_get_credit_card_bill and openfinance_list_transactions. It also notes bulk support and that results are bill-level summaries.

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: when to use this tool, when to opt-in for open_bill, how to interpret payment_status, when to use openfinance_list_transactions for itemized purchases, and warnings about cross-bank attribution. It also explains the open_bill asymmetry and when to rely on the bank app.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds value by detailing error handling: returns {total, results, warning} instead of throwing errors on 403 or upstream issues. This goes 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?

The description is a single sentence that packs a lot of information, which is efficient but slightly dense. It could be split for readability. No wasted words.

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

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

Given no output schema, the description explains return values and error handling well. However, it lacks parameter semantics, which is a gap for a tool with 4 parameters and 0% schema coverage. Complexity is moderate.

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. However, it does not explain the input parameters (item, page, type, page_size). It only describes return fields. Minimal compensation for missing parameter documentation.

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

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

The description clearly states it returns the investment portfolio for a connection, listing many specific types (FIIs, stocks, ETFs, etc.), which is a specific verb+resource. It distinguishes itself from sibling tools like openfinance_list_investment_transactions by focusing on the overall portfolio rather than transactions.

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

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

The description implies usage for retrieving investment portfolio data, but does not explicitly state when to use this tool vs alternatives (e.g., openfinance_list_investment_transactions). No exclusions or when-not-to-use guidance 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 already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds value by detailing the returned columns (quantity, value, amount, netAmount, agreedRate, brokerageNumber, expenses breakdown) and the bulk execution capability. 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 concise: two short paragraphs. The first paragraph immediately conveys the core purpose and return data. The second adds usage and bulk support without redundancy. Every sentence adds value.

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

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

Given 4 parameters, no output schema, and annotations covering safety, the description explains the return structure in sufficient detail and provides usage context. The absence of output schema is partially offset by listing the columns. However, pagination behavior and limits are not mentioned.

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 explains that investment_id comes from openfinance_list_investments and that investment_ids enables bulk execution. However, it does not explain the page and page_size parameters, leaving some ambiguity for those fields.

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 starts with 'Returns the movement history for a specific investment position' which clearly states the verb (returns), resource (movement history), and scope (specific investment). It lists transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER) and mentions use after openfinance_list_investments, distinguishing it from sibling tools like openfinance_list_investments.

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

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

The description says 'Use after openfinance_list_investments to get the investment_id' which provides explicit sequential usage guidance. It also mentions bulk support via investment_ids. However, it does not explicitly state when not to use this tool or list alternative tools for different scenarios.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals that multiple connections are fetched sequentially with rate-limit spacing and the return format is { results, errors } per connection. 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?

Three sentences, front-loaded with the core purpose, each sentence adding essential information 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?

Given the tool's simplicity (one optional parameter, no output schema, strong annotations), the description covers all necessary aspects: purpose, input semantics, usage modes, behavior, and return 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?

The input schema has 0% coverage (no description) for the single parameter 'items'. The description compensates fully by explaining it is an array of connection selectors (item_id, connector_id, or connector_name) and how usage differs between providing and omitting it.

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 lists loan contracts, specifies the REST endpoint (GET /loans), and explains the two modes: with items for specific connections or omitted for all banks. This distinguishes it from sibling list 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?

Provides clear direction on when to use each mode (pass items for specific connections, omit for all), and mentions sequential querying with rate-limit spacing. However, it does not explicitly state when not to use or list alternatives, though the purpose is specific 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. The description adds critical behavioral details: variable coverage per connector for CREDIT pending/posted, auto-pagination up to 5000, truncation behavior, error response format, detail levels, account echo, provider incidents, and bulk support. 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?

Despite length, every sentence earns its place given the tool's complexity. Well-organized into sections (pagination, detail, error handling, etc.) with the core purpose stated first. No redundant or filler content.

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

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

For a tool with 8 parameters, no output schema, and multiple account types, the description covers all necessary aspects: purpose, usage guidelines, parameter semantics, response structure (account echo, total, warning, error, provider_incident), and cross-tool dependencies. Exceptionally complete.

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

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

Schema description coverage is 0%, but the description thoroughly explains every parameter: account_id (required), from/to date format, page auto vs manual, page_size max, detail enum options with implications, search_queries behavior (case-insensitive substring match, OR semantics, 5000 cap), and account_ids for bulk. Adds meaning far beyond 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?

Clearly states it returns transactions for a bank account (BANK or CREDIT type), and explicitly distinguishes from siblings like openfinance_list_credit_card_bills. The verb+resource is 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 for CREDIT accounts, alternatives for bill totals, pagination strategies, filtering, error handling, and cross-references to other tools (e.g., openfinance_get_item_status). Includes explicit instructions on when to omit vs. pass page.

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 discloses internal behavior: resolves accounts internally, caps at 5000 transactions per account with a `truncated:true` flag, includes a `provider_incident` block when provider issues exist, and details the compact output structure. 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 well-structured with the main purpose front-loaded. It is dense but comprehensive; every sentence adds value. Minor verbosity could be trimmed, but it remains efficient given the tool's complexity.

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

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

Given the tool's complexity (7 parameters, no output schema, rich annotations), the description is highly complete. It covers the consolidated output, truncation behavior, provider incident handling, and parameter defaults. The only minor gap is not explicitly stating the output format, but it is implied by the described fields.

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: `item` (connector_id, connector_name, item_id, or omit), `from`/`to` as ISO dates, `granularity` (monthly vs. raw), `type` (BANK/CREDIT), `detail` (compact/rich/raw), and `top_n` (implied by 'largest N'). This adds significant meaning beyond the schema enums.

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: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It uses specific verbs ('analyze') and resources ('connection transactions'), and distinguishes it from siblings like openfinance_list_accounts and openfinance_list_transactions by highlighting that it resolves accounts internally and fans out 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 scenarios: 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos'. It also advises against calling openfinance_list_accounts first and explains when to omit the `item` parameter. Usage of `granularity`, `detail`, and `type` parameters is clearly contextualized.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the live nature of the check and the output fields (global indicator, degraded components, open incidents, affected banks). No contradictions.

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

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

The description is concise and well-structured, starting with the main purpose, then usage guidance, followed by output 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?

Given no parameters and no output schema, the description provides complete context: what the tool does, when to use it, and what it returns. Annotations cover safety. 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?

The tool has no parameters, so schema coverage is 100%. The description does not need to add parameter information, and it provides sufficient context about the tool's behavior without referencing 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 clearly states the tool checks the LIVE operational status of the Open Finance provider, distinct from connection status. It uses specific verbs ('checks', 'reveals') and explicitly distinguishes from sibling tool 'openfinance_get_item_status'.

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: when data looks incomplete or stale even though a connection shows UPDATED. It explains the tool reveals upstream outages or incidents, differentiating provider-side problems from connection issues.

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

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

Discloses key behavioral traits: returns connector metadata, linked connections, accounts if requested, and a connect URL. Also warns about caveat for non-Open-Finance connectors that need manual reconnection. Complements annotations which already indicate read-only and idempotent behavior.

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

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

Every sentence adds value, no redundancy. The description is front-loaded with the main purpose and flows logically into usage, parameters, and behavioral notes.

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?

Comprehensive for a search tool with two parameters and no output schema. Covers purpose, input requirements, return fields, caveats, and workflow integration. No gaps for an agent to misuse the 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?

Both parameters are explained with examples (keywords[] with e.g., include_accounts with behavior). However, the description says keywords is required while the schema does not mark it required, creating a slight 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 the tool searches bank connectors by name and returns specific fields. It distinguishes itself from siblings like 'connect' and 'list_connections' by positioning itself as a pre-connect search step.

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

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

Explicitly instructs to call this BEFORE connecting, mentions that keywords are required (otherwise returns a hint), and notes plan-based filtering. Provides clear when-to-use and what it should not be used for (never dump the whole catalog).

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

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

The description goes well beyond the annotations (which provide no behavioral clues) by disclosing that the tool overrides Pluggy's automatic categorization and teaches Pluggy by creating a Category Rule for the client. It also details batch behavior (per-item errors don't fail the whole batch) and the return shape. This is excellent transparency for a mutation tool.

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

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

The description is front-loaded with the main action and then expands on effects and error handling. Every sentence provides value, though it is somewhat lengthy. It is well-organized but could be slightly tighter without losing clarity.

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

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

Given that there is no output schema, the description fully describes the return structure ({ updated, results, errors }) and error semantics (per-item errors don't fail the whole batch). It also covers prerequisites (IDs from other tools) and side effects (Category Rules). This makes the tool completely understandable without external documentation.

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?

Although the schema description coverage is 0%, the description compensates by explaining the structure of the `items` array (array of { transaction_id, category_id }) and provides context on where to obtain each ID. It clarifies the intended use of the parameters, adding semantic value 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 corrects transaction categories, specifies the HTTP method and path (PATCH /transactions/:id), and distinguishes it from sibling tools like openfinance_list_transactions and openfinance_list_categories. It uses a specific verb ('corrects') and identifies the resource (transaction categories), making the purpose unambiguous.

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

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

The description explains exactly when to use this tool (fix miscategorized transactions), provides sources for required IDs (transaction_id from openfinance_list_transactions, category_id from openfinance_list_categories), and describes the behavioral impact (creates Category Rules for future similar transactions). It implicitly contrasts with listing tools but does not explicitly state when not to use it, which would improve the score.

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 idempotent and non-destructive behavior. The description does not add further behavioral details (e.g., processing time, rate limits), 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?

Two concise sentences provide essential information without extraneous content.

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

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

For a simple feedback tool without output schema, the description covers primary usage. Could note that 'message' is required, but overall it is complete enough 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?

With 0% schema coverage, description partially compensates by explaining the conversation parameter. However, 'context' parameter remains unexplained, and no format details are given for the conversation string.

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

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

The description clearly states the tool's purpose: reporting bugs, missing features, or sending feedback. It is distinct from sibling tools, which focus on financial 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?

It instructs to include the conversation array for reproduction, providing clear context. No exclusions or alternatives are needed since no sibling tool serves the same function.

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, and destructiveHint. The description adds the specific output (MCP platform and adapter versions), which provides useful context beyond annotations.

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

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

The description is a single sentence, very concise, and front-loaded with the key action and resource. There is no wasted text.

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 (current MCP platform and adapter versions) and there are no parameters. This is complete for a simple version 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?

There are no parameters, and schema description coverage is 100%. The description adds no parameter information because none is needed.

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

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

The description clearly states the tool's purpose: showing current MCP platform and adapter versions. It uses a specific verb ('Show') and resource, and it is easily distinguishable from sibling 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?

No explicit guidance on when to use this tool vs. alternatives is provided. The context is implied—it's a simple version display—but there is no mention of when not to use it or of 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 declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the exact output content (MCPs, connection status, catalog counts), providing 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?

The description is a single, front-loaded sentence that directly conveys the tool's purpose without any extraneous 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?

For a simple info tool with no parameters or output schema, the description is sufficiently complete, detailing the three components of the returned state.

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 description appropriately does not mention parameters. It adds no redundancy and fully leverages the empty 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 the current toolkit state with specific components: installed MCPs, connection status, and catalog tool counts. It uses a specific verb ('Returns') and resource, distinguishing it from sibling tools like show_version.

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

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

The description implies usage for retrieving toolkit state but does not explicitly state when to use this tool over alternatives. However, given its zero-parameter read-only nature, 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.