PagBank MCP

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

Annotations set idempotentHint=true and destructiveHint=false, but the description adds crucial context: what happens when called with token (session-only login) vs no args (returns a link). It also warns about token non-expiration, enhancing transparency 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?

The description is well-structured, starting with the purpose and then listing usage cases. It is slightly verbose but every sentence adds value. A minor simplification could improve conciseness, but it remains effective.

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

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

Given no output schema and the tool's complexity (two modes, security implications), the description covers all necessary aspects: login method, token usage, permanent vs session, and where to find the token. It is fully complete for an 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?

The input schema has one optional parameter 'token' with no description (0% coverage). The description fully compensates by explaining its role: when provided, it performs login; when omitted, a link is returned. 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 starts with 'MCP.AI for IDE agents (Cursor, etc.): log in in the browser, copy the access token.' This clearly states the tool's purpose: authentication for IDE agents. It distinguishes from sibling tools like 'connect' or 'marketplace' by specifying its unique role.

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 explains when to use the tool with or without arguments ('call with { token: "<jwt>" }' vs 'with no args to get the link'). It also provides the alternative best practice of adding the token to config for a permanent connection, guiding the agent on optimal usage.

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

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds behavioral context by detailing the response structure (authenticated, pending, connect_url) without contradicting 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 three concise sentences, each adding value. The main purpose is front-loaded, and there is 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately covers the behavioral states. It could mention prerequisites like authentication, but the status check likely works without prior auth. Overall sufficient.

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 no parameters, so schema coverage is 100% and description does not need to add parameter info. The baseline is 4, and no further explanation is required.

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

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

The description clearly states the tool returns connection status and URLs, specifying the two scenarios (all providers connected vs. credentials missing). This distinguishes it from the sibling 'authenticate' tool by focusing on status rather than authentication action.

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

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

The description provides context on when it returns authenticated:true vs connect_url, implying it is used to check connection status. However, it does not explicitly mention when to use it over alternatives like 'authenticate' or other 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?

The description adds substantial behavioral context beyond annotations: it details write operations requiring admin, invoke working even without installation, handling of missing credentials/payment via links, and non-destructive nature of install/uninstall. There is no contradiction with annotations, and the openWorldHint and readOnlyHint are well supported.

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 too long (approximately 20 lines) and contains some redundancy, such as repeating the invoke behavior. While it is logically structured and front-loaded with the main purpose, it could be more concise without losing essential information.

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

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

Given the tool's complexity (many actions, 13 parameters, no output schema), the description is quite complete: it explains the overall flow, each action's purpose, auth/payment handling, and ownership requirements. It lacks explicit return value descriptions for all actions but covers search/describe outputs. The presence of annotations helps, but the description adds necessary 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 compensates by explaining the action enum in context and mentioning key parameters like mcp_id, tool_id, arguments, and immediate. However, it does not systematically describe all 13 parameters, leaving some (e.g., limit, query, message) implied rather than explicit.

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 as 'THE official mcp.ai marketplace' and explains its role as a catalog and execution environment. It distinguishes from other tools by positioning it as the first to use for capability discovery, contrasting with external registries and sibling tools like authenticate or openfinance functions.

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 this tool ('use THIS tool FIRST') and outlines a core flow (search → describe → invoke). It distinguishes between one-off invoke and permanent install, and lists alternative actions (subscribe, cancel, report_bug, request_mcp) with their purposes, giving clear decision criteria.

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

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

Annotations already indicate destructiveHint=true, and the description adds critical context: data will no longer be available and a re-connection URL is returned. This goes beyond the annotation, providing full behavioral 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?

Two sentences, no filler, front-loaded with the primary action. Every word adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers the main purpose and outcome. However, it lacks parameter explanation and any mention of prerequisites (e.g., bank must be connected) or error scenarios, leaving some 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 sole parameter 'item' is a string with no description in the schema (0% coverage). The description mentions 'for a specific bank' but does not clarify whether it expects a bank ID, name, or other identifier, nor any format 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 action ('Revokes consent and deletes connection data') and the resource ('for a specific bank'). It distinguishes from sibling tools like openfinance_list_connections or openfinance_force_sync 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?

The description implies when to use it (to revoke consent and delete data) and hints at post-use behavior (returns re-connection URL). However, it does not explicitly state when not to use it or name alternative tools, leaving some ambiguity.

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

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

Discloses behavioral traits beyond annotations: polling up to ~60s, returns final status and executionStatus, timed_out handling, needs_action meaning. Annotations only indicate non-read-only, non-destructive, non-idempotent; the description adds critical context.

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

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

The description is well-structured with a clear front-loaded action statement followed by details. While comprehensive, it could be slightly more concise by removing some redundant clauses, 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?

Complete for a sync polling tool with no output schema: explains return format { results, errors }, status fields, needs_action, timed_out. Covers all necessary information 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?

Despite 0% schema description coverage, the description fully explains both parameters: items as array of selectors (item_id, connector_id, connector_name) with omission syncing all, and wait with fire-and-forget option. 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 the tool forces a re-sync and waits for completion. It uses specific verbs and resources ('Forces the bank to re-sync one or more connections NOW and WAITS for it to finish'), and distinguishes from siblings like openfinance_get_item_status and openfinance_disconnect_bank.

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

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

Provides explicit guidance: 'Use this when a balance or transaction list looks stale' and explains when to use alternatives (e.g., re-check with openfinance_get_item_status). Also covers when to set wait: false for fire-and-forget.

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

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

Beyond annotations (readOnly, idempotent), description adds real-time nature, specific error handling for CREDIT accounts (warning vs throw), and response shape, providing rich 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?

Extremely concise: two sentences plus response shape, all relevant and front-loaded.

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

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

For a simple read tool with one parameter and no output schema, the description fully covers behavior, constraints, and output.

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% coverage; description adds that account_ids is an array of IDs (size 1-50) and implies they are account IDs, but could hint at source (e.g., from list_accounts).

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 'Returns real-time balance payload per account id' with HTTP endpoint and specifics about CREDIT account errors, making the purpose unmistakable.

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 parameter guidance (array of 1-50 IDs) but does not explicitly differentiate from sibling tools or state when not to use it.

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

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

Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds value by specifying the output shape ({ results, errors }) and that it includes extended creditData, going beyond the annotations to explain what 'full account objects' entails.

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 explains purpose and endpoint, second specifies parameter and return format. No redundant words, front-loaded with key actions.

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

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

The description covers the return shape and the inclusion of creditData. It does not detail the error structure or potential field list, but given the tool name and sibling tools, the context is adequate. Minor improvement could mention error handling.

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, but the description explicitly describes the parameter 'account_ids' as an array of strings with a size constraint (1–50), which adds critical information not present in the schema. This fully compensates for the lack of schema descriptions.

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

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

The description clearly states the tool returns full account objects including extended creditData for specific IDs. It references the HTTP endpoint (GET /accounts/:id) and distinguishes it from siblings like openfinance_list_accounts (listing) and openfinance_get_account_balance (balance only).

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

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

The description implies when to use: to get detailed account objects for a list of IDs. It does not explicitly state when not to use, but the sibling context (e.g., list vs. detail) provides sufficient implied 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=true, idempotentHint=true), the description discloses the batch shape {results, errors}, explains the absence of a paid/status field from Pluggy, and clarifies the meaning of payments[] relative to billing cycles. 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 somewhat verbose but well-structured and front-loaded with the core purpose. Every sentence adds value, covering what the tool does, what it doesn't, and key caveats. Minor redundancy could be trimmed but overall effective.

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

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

Given no output schema and one parameter, the description thoroughly explains return shape, fields, and common pitfalls. It addresses potential confusion about paid status and payment interpretation, making it fully adequate for an AI agent.

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

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

The schema has 0% description coverage for the single parameter bill_ids. The description adds context by stating to pass bill_ids as an array and recommending prior use of openfinance_list_credit_card_bills to discover IDs. While helpful, it does not provide examples or constraints like max length.

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, lists specific fields returned (financeCharges, payments[]), and explicitly distinguishes from sibling tools by noting it does NOT return individual transactions.

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

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

The description provides explicit when-to-use and when-not-to-use guidance, directs to openfinance_list_transactions for itemized transactions, and advises using openfinance_list_credit_card_bills first to discover bill IDs. It also includes a detailed note about interpreting payments[] in the Brazilian Open Finance 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 declare the tool as read-only and idempotent, which the description does not contradict. The description adds transparency by specifying possible status values (UPDATED, UPDATING, LOGIN_ERROR, etc.) and explaining the two response formats depending on the parameter. This is valuable behavioral info 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 concise with two sentences. The first sentence clearly states what it returns including example values, and the second sentence efficiently explains the two usage modes. 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?

For a tool with no output schema, the description explains the two modes and provides example response structure for the 'all' case. However, it does not specify the exact response format for a single bank (e.g., whether it returns an object or just the status), nor does it mention potential errors or edge cases. Given the tool's simplicity, it is mostly complete but could benefit from specifying the single bank response.

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

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

The single parameter 'item' is fully described: omitting it returns all connections in a paginated format, passing it returns a single bank. This adds the necessary context that the schema lacks (0% coverage). No additional constraints are 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 it returns bank connection status with specific possible values and distinguishes between single and all connections. It uses a specific verb ('Returns') and resource ('status of bank connection'), making the purpose clear. However, it does not explicitly differentiate from sibling tool 'openfinance_list_connections' which might also provide status information.

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

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

The description provides usage guidelines for the optional 'item' parameter (omit for all, pass for single). However, it does not explain when to use this tool versus sibling tools like 'openfinance_list_connections' or 'openfinance_provider_status', which may also return connection information. There is no guidance on when not to use it.

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

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

Annotations already declare the tool as read-only and idempotent. The description adds valuable warnings about credit balance being connector-dependent and explains creditData fields, going 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 long but well-structured with two clear sections. Every sentence adds value; no redundancy. Slightly verbose but justified given the 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?

Lacks output schema, but description covers return fields and important behavioral notes (credit balance ambiguity). Does not mention pagination or limits, but otherwise complete for the tool's purpose.

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

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

Schema has no descriptions (0% coverage). The description explains the `item` parameter clearly (omit vs. pass) and implies the `type` parameter by mentioning account type subtypes, but does not explicitly state that `type` filters results.

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 accounts with specific fields (balance, number, type, etc.) and distinguishes between BANK and CREDIT types. It also differentiates from sibling tool openfinance_list_credit_card_bills by noting that this tool's credit balance is not standardized.

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 omit vs. pass the `item` parameter, and directs users to openfinance_list_credit_card_bills for standardized billing data. Provides clear context for user-facing text (use `bank` not `name`).

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, but the description adds valuable behavioral context: caching behavior ('cached for the adapter session'), response format ('single aggregated response — no batch ids'), and field semantics (e.g., English vs. Portuguese descriptions). This goes beyond annotations without contradiction.

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

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

Two tightly written sentences: first captures purpose and caching, second lists fields with practical guidance. No wasted words, front-loaded with key information.

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

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

Given no parameters, no output schema, and rich annotations, the description fully covers purpose, output structure, caching details, and integration hints. It is self-contained and leaves no ambiguity for an agent.

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

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

No parameters exist, and schema coverage is 100% trivially. The description compensates by detailing the output fields and their usage (e.g., how 'id' links to another tool). This adds value beyond 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 Pluggy's transaction category taxonomy, specifying it as a GET /categories endpoint. It distinguishes from siblings by explicitly linking to openfinance_update_transaction_category via the 'id' field, making its purpose unique among 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 clear context on when to use the tool (e.g., before updating categories) and offers field-level guidance (prefer descriptionTranslated for pt-BR users). However, it does not explicitly state when not to use it or mention alternatives, though few exist among siblings.

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

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

Annotations already indicate read-only behavior. The description adds context about return fields and the add_connection_url, but lacks details on auth requirements or rate limits. 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 single sentence is direct, front-loaded, and contains all necessary information without extraneous 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?

Given no output schema, the description adequately explains the return value. Minor omission: no mention of behavior when no connections exist, but acceptable for a simple list.

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 does not need to add param details. Baseline of 4 is appropriate.

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

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

The description specifies the verb 'Returns' and the resource 'saved bank connections', explicitly listing returned fields and distinguishing it 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 implies usage to retrieve connections and obtain an add_connection_url, but provides no explicit guidance on when to use this tool versus alternatives like openfinance_search_bank_connectors.

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

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

The description goes far beyond the annotations by detailing complex behaviors like payment allocation across cycles, the derivation of payment_status, connector asymmetry for open bills, and the extra scan required for include_open_bill. No contradictions with annotations.

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

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

The description is long but well-structured with clear sections (IMPORTANT, CONNECTOR ASYMMETRY, etc.). Every sentence provides necessary detail for a complex domain. The front-loading of the main function is effective, though the length could be slightly reduced without losing essential context.

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 the tool (5 parameters, no output schema, 0% parameter description coverage), the description is remarkably complete. It covers return fields, interpretation of derived fields, limitations, alternatives, and edge cases like connector asymmetry, leaving no significant gaps for an agent to understand correct usage.

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

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

With 0% schema description coverage, the description must compensate for all parameters. It explains account_id (required), account_ids (bulk), and include_open_bill in detail, but does not mention page and page_size. The explanation of include_open_bill adds significant value, but the gap for pagination parameters prevents a higher score.

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 CLOSED credit card bills for a CREDIT-type account, listing specific fields and noting it provides bill-level summaries, not transactions. It distinguishes itself from the sibling tool openfinance_list_transactions, which is for itemized purchases.

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 this tool (for closed bills), when not to use it (for open bills without include_open_bill), and alternatives (openfinance_list_transactions for individual transactions). It also explains the derived payment_status and warns against misinterpreting the payments array.

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

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

Annotations indicate readOnlyHint and destructiveHint false, consistent with read behavior. The description adds error handling behavior: returns a structured response instead of throwing on 403 or upstream errors, which is valuable 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 that is reasonably concise and front-loaded with the main action. However, it could benefit from breaking into bullet points for clarity. Still, 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 exists, so the description should fully describe return shape. It lists some fields but omits details like pagination semantics, response metadata, and parameter effects. With 4 undocumented parameters, the description is incomplete.

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 explain any of the four parameters (item, page, type, page_size). Despite listing return fields, the absence of parameter documentation significantly hinders correct invocation.

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 with explicit listing of asset types (FIIs, stocks, ETFs, fixed income, etc.) and distinguishes from sibling tools like openfinance_list_accounts by specifying it's for connections with INVESTMENTS product enabled.

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 like openfinance_list_accounts or openfinance_list_transactions_by_item. The description does not mention prerequisites or scenarios where another tool is preferred.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety traits are clear. The description adds value by detailing the return fields (quantity, value, amount, etc.) and bulk execution feature. However, no mention of pagination or rate limits.

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 succinct sentences plus a line for bulk support, front-loaded with purpose. No extraneous content, though a slight improvement could be structured formatting.

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 moderate complexity (4 params, no output schema), the description covers return fields and bulk usage but omits pagination details (`page`, `page_size`). Lacks completeness for a tool with many fields and optional filters.

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 4 parameters with 0% description coverage. Description explains `investment_id` and `investment_ids` (bulk support) but omits `page` and `page_size`. Thus, it adds only partial value beyond the schema.

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

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

The description clearly states the tool returns 'movement history for a specific investment position' and lists transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER). It also specifies the prerequisite use of `openfinance_list_investments`, distinguishing it from sibling tools like `openfinance_list_investments` and `openfinance_list_transactions`.

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

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

Explicitly states 'Use after openfinance_list_investments to get the investment_id', providing clear guidance on when to invoke. Mentions bulk support for `investment_ids`. Lacks explicit 'when not to use' but context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, covering safety. The description adds behavioral context beyond annotations: sequential queries with rate-limit spacing and per-connection return structure ({ results, errors }). 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 three sentences with no redundant information. It front-loads the core purpose and immediately provides actionable instructions. Every sentence adds value.

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

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

For a tool with one optional parameter, no output schema, and well-covered annotations, the description covers input semantics, behavioral nuances, and output structure ({results, errors}). No missing critical information for an agent to use it correctly.

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

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

The input schema has one parameter (items) with 0% description coverage. The description fully compensates by explaining that items is an array of connection selectors (item_id, connector_id, or connector_name) and the behavioral implications (sequential querying per entry).

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 per bank connection with a specific verb (List) and resource (loans). It distinguishes from sibling tools like openfinance_list_accounts by specifying the resource (loans vs accounts) and mentioning the HTTP endpoint GET /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?

The description explains two usage modes: pass `items` for specific connections or omit for all banks. It also mentions sequential querying with rate-limit spacing. However, it does not explicitly state when not to use this tool or provide direct alternatives, though sibling names imply differentiation.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description extensively discloses behavior: auto-pagination up to 5000 ceiling with truncation, error handling (returns {total:0, results:[], warning, error}), dependency on upstream connector for CREDIT PENDING/POSTED, and fallback to openfinance_get_item_status for connection health.

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?

While the description is long, it is well-structured with logical sections (main purpose, credit card specifics, date filtering, search, pagination, error handling, detail levels, bulk support). Every sentence provides essential information, though some rephrasing could reduce length. It is not overly verbose given the 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 high parameter count (8) and no output schema, the description is remarkably complete. It covers return data shape, pagination limits, truncation warnings, error responses, connection health checks, and references to sibling tools for related data. An agent can confidently use this tool without ambiguity.

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

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

Schema description coverage is 0%, but the description compensates by explaining each parameter in detail: from/to as ISO YYYY-MM-DD, search_queries as case-insensitive substring match with OR semantics, page omission for auto-pagination, page_size max 500, enum detail with compact/rich/raw meanings, account_id and account_ids for bulk. This adds significant meaning beyond 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 transactions for bank accounts (BANK or CREDIT type) and distinguishes itself from sibling tools like openfinance_list_credit_card_bills by specifying that for CREDIT accounts it is the only way to get itemized transactions, with linkage to bills. It also mentions bulk support via 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?

Provides explicit guidance on when to use this tool vs alternatives: for CREDIT accounts, use this for itemized transactions; for open bill totals use openfinance_list_credit_card_bills. Also explains when to use detail levels, pagination manual vs auto, and how to handle truncation.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: transaction scan caps at 5000/account with a 'truncated:true' flag, default 'monthly' returns a compact summary, and 'raw' plus 'detail' options affect data richness. 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 dense and informative, with all sentences adding value. However, it is relatively long and could benefit from bullet points or clearer segmentation. It is front-loaded with purpose.

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

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

Given the complexity (7 parameters, no output schema), the description is remarkably complete. It explains the return structure (entradas, saídas, por_mes, top_despesas, etc.), per-account breakdown, truncation behavior, and details on enrichment options. No output schema makes this essential.

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

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

Schema has 0% description coverage, so the description fully explains all 7 parameters: 'from'/'to' as ISO dates, 'item' as connector identifier, 'type' as BANK/CREDIT, 'top_n' for largest N, 'detail' for enrichment levels, and 'granularity' for summary vs raw. It adds meaning beyond the schema.

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

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

The description clearly states the tool performs consolidated cash-flow analysis for a bank connection over a period, resolving accounts internally, eliminating the need for separate account listing calls. It distinguishes itself from siblings like openfinance_list_transactions by highlighting its aggregated nature.

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 specifies when to use this tool (e.g., 'análise anual/mensal', 'fluxo de caixa'), how to omit 'item' to analyze all banks, and when to set granularity to 'raw'. It provides clear guidance on parameter combinations.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context by detailing what the tool returns (global indicator, degraded components, open incidents, your_banks_affected) and how it helps differentiate provider issues, without contradicting 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, well-structured sentence that front-loads the purpose, explains usage context, and lists return values. Every part is informative with no redundancy.

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

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

Despite lacking an output schema, the description adequately explains the return fields (global indicator, degraded components, open incidents, your_banks_affected). For a simple status tool with no parameters, this is sufficiently complete.

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

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

The tool has zero parameters, and schema coverage is 100%. The description does not need to add parameter detail; it appropriately focuses on functionality, achieving the baseline of 4.

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

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

The description clearly states the tool checks the 'LIVE operational status of the Open Finance provider', distinguishing it from sibling tools like openfinance_get_item_status. It specifies the target (provider's health) and uses specific verbs.

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: 'whenever data looks incomplete or stale even though a connection shows UPDATED'. It explains the diagnostic purpose (separating provider-side problems from connection issues) but does not explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about how it honors the user's plan (PF hides PJ banks) and that some connectors have caveat warnings about auto-update. 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 front-loaded with the main purpose and every sentence adds value. It is slightly long but necessary to convey important details like the caveat warning and plan honoring. It could be tightened slightly without losing information.

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

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

Given no output schema, the description adequately describes the return fields (connector id, access, audience, linked connections/accounts, connect_url) and the caveat warning. It covers the essential information for a search tool with two parameters.

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 keywords[] is an array of bank names and is REQUIRED, and that include_accounts includes accounts in the response. This adds meaningful semantics beyond the bare schema, though it could specify search behavior (e.g., case sensitivity).

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 like connector id, access type, audience, and connect_url. It distinguishes itself from sibling tools like 'connect' and 'openfinance_list_connections' by focusing on search before connection.

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

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

The description explicitly says to call this BEFORE connecting and notes that keywords[] is REQUIRED to avoid dumping the full catalog. It advises surfacing caveat warnings for non-Open-Finance connectors. However, it does not explicitly name alternative tools for comparison.

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 critical behaviors beyond annotations: it overrides automatic categorization and creates a Category Rule for future similar transactions. It also describes batch error handling (per-item errors do not fail batch) and the response shape. Annotations only provide hints, so description adds substantial 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 relatively long but each sentence adds essential information. It is front-loaded with the main action and HTTP method. Minor redundancy could be trimmed, 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 tool's complexity (batch update with side effects and error handling), the description fully covers: purpose, input sourcing, behavioral effects (rule creation), and return shape. No output schema exists, but the description provides sufficient details for an agent to use the tool correctly.

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

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

Despite 0% schema description coverage, the description explains the single parameter `items` as an array of objects with `transaction_id` and `category_id`, and specifies how to obtain those IDs from other tools. This compensates well for the lack of schema-level descriptions.

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

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

The description clearly states the tool's purpose: "Corrects the category of one or more transactions (PATCH /transactions/:id)". It specifies the verb (corrects), resource (category of transactions), and distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_categories by referencing their outputs as inputs.

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 accuracy going forward". It tells where to get required IDs (from list_transactions and list_categories). It implicitly excludes other uses but does not explicitly state when not to use or provide direct alternatives for similar actions.

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

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

Annotations indicate idempotent and non-destructive behavior. The description adds that the conversation array is needed for reproduction, which is relevant but does not elaborate on rate limits, side effects, or other behavioral aspects.

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

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

The description is extremely concise—two sentences that front-load the purpose and immediately provide key usage instruction. No unnecessary words.

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

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

For a simple feedback tool with no output schema and three parameters, the description covers the core purpose and one parameter's role. It lacks detail on expected input formats, response behavior, or the purpose of the 'context' parameter.

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

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

With 0% schema description coverage, the description must compensate. It only explains the 'conversation' parameter, leaving 'message' (required) and 'context' without additional meaning beyond the schema.

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

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

The description clearly states the tool is for reporting bugs, missing features, or sending feedback. This purpose is distinct from sibling tools, which are primarily finance-related operations.

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

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

The description provides guidance to include the conversation array for reproduction, implying usage context. However, it does not specify when not to use this tool or suggest alternatives, leaving room for ambiguity.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context beyond stating the action, so it neither contradicts nor enriches 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?

The description is a single sentence with no wasted words. It is appropriately sized and front-loaded with the core 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?

Given zero parameters, no output schema, and annotations that fully capture the tool's read-only, idempotent nature, the description is complete. No additional context is necessary.

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 the input schema fully covers them (100% coverage). The description does not need to add parameter details, and a baseline of 4 is appropriate for this case.

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 shows current MCP platform and adapter versions. The verb 'show' and resource 'versions' are specific and distinct from sibling tools which involve authentication, finance operations, etc.

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 versus alternatives is provided. However, the simplicity of the tool (no parameters, straightforward purpose) implies its use case, reducing the need for detailed guidelines.

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 cover readOnlyHint, idempotentHint, destructiveHint. The description adds value by detailing what is returned (installed MCPs, connection status, catalog tools). 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, concise sentence that front-loads the purpose. Every word adds value with no redundancy.

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

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

No output schema exists, so the description compensates by clearly stating the return data: installed MCPs, connection status, and catalog tool count. This is sufficient for a simple info tool.

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

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

No parameters exist, and schema coverage is 100%. Baseline of 4 is appropriate as the description does not need to add parameter information.

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 specific resource 'current toolkit state' with concrete data points (installed MCPs, connection status, catalog tool count). It effectively distinguishes from sibling tools like connect or authenticate.

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

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

The description implies usage for checking state but does not explicitly state when to use or provide alternatives. Context from sibling tools (e.g., connect) suggests this is for read-only information, but no direct guidance is given.

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