Midway MCP

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

Annotations include idempotentHint=true and destructiveHint=false. The description adds context about returning a login link when called without arguments, but does not detail side effects or token expiration 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?

The description is a single paragraph that efficiently conveys the purpose and usage instructions. It is front-loaded with the tool's intent and avoids 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?

Given the tool's simplicity and lack of output schema, the description covers the main use cases. However, it does not specify the return format or what happens upon successful authentication, leaving some gaps for an AI agent.

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

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

Schema description coverage is 0%, but the description compensates by explaining that 'token' is a JWT obtained from the browser, and that calling without arguments returns a link. This provides clear meaning beyond the schema.

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

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

The description clearly states it is for authentication, specifying it is designed for MCP.AI IDE agents and explains the login process in the browser. It distinguishes itself from sibling tools as the only authentication tool.

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

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

The description provides clear guidance on two use cases: permanent login via config and session-only login via token. It explains when to call with token and when without, but does not explicitly 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 declare readOnlyHint=true and idempotentHint=true, indicating safe, read-only behavior. The description adds behavioral details about return values in different states, which is consistent 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?

Two sentences, no wasted words, front-loaded with the key action ('Returns connection status and URLs').

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 tool has no parameters and no output schema, so the description covers the main scenarios adequately. However, it does not mention potential error states or if any prerequisites (like prior authentication) exist, which would add completeness.

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

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

There are no parameters, so schema coverage is 100%. The description adds meaning by specifying the output structure (authenticated, pending, connect_url) beyond what the empty schema provides.

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: returning connection status and URLs. It distinguishes itself from siblings like 'authenticate' and 'openfinance_list_connections' by focusing on the overall connection status, not authentication flow or per-connection details.

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

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

The description implicitly guides usage by explaining the two possible outputs based on connection state (when all providers connected vs credentials missing). It does not explicitly list alternatives or when-not-to-use, but the context is clear.

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

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

The description discloses behaviors beyond annotations: invoke runs one-off without installation, install makes permanent, invoke may return connect/checkout links, search/describe flag installed status, and writes require admin. 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 a dense block of text (~150 words) without breaks or structure. While information-rich, it lacks conciseness and would benefit from bullet points or sections for better readability.

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

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

Given the tool's complexity (15 params, many actions, no output schema), the description covers purpose, flow, usage guidelines, and key behaviors. It lacks explicit return value descriptions for search/describe, but otherwise is reasonably complete.

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

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

With 15 parameters and 0% schema description coverage, the description adds meaning by explaining actions (search, describe, invoke, etc.) and how parameters like mcp_id, tool_id, arguments are used. However, it does not systematically cover every parameter.

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

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

The description clearly identifies the tool as the official mcp.ai marketplace for discovering, describing, and running MCPs/tools. It specifies the core flow and distinguishes from siblings (e.g., OpenFinance tools) by stating 'use THIS tool FIRST'.

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

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

The description provides explicit guidance on when to use the tool (e.g., before external registries), the core flow (search → describe → invoke), and when to prefer invoke over install. It also notes permission requirements for writes.

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?

Description adds value beyond destructiveHint annotation by specifying consent revocation, data deletion, irreversible unavailability, and return of a re-connect URL. No contradiction with annotations.

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

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

Three short, front-loaded sentences efficiently convey action, consequence, and return 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?

Despite being a simple tool, the missing explanation of the sole parameter leaves a critical gap; the description is insufficient 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?

Schema has one required parameter 'item' with 0% description coverage, and the tool description does not explain what 'item' represents (e.g., bank identifier or connection ID), leaving the agent guessing.

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 revokes consent and deletes connection data for a specific bank, which is a distinct destructive action among siblings like openfinance_list_connections or 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 implies use when disconnecting a bank, but offers no explicit guidance on when to use versus alternatives like list_connections or force_sync. The mention of a re-connect URL provides some 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?

Discloses wait behavior (polls up to ~60s, returns immediately if wait=false), explains return fields like status, executionStatus, lastUpdatedAt, synced, needs_action, timed_out. Adds significant context beyond annotations, which only indicate non-read-only and non-destructive.

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 dense but well-structured, front-loaded with action. Every sentence adds useful information, though slightly long. Could be trimmed slightly 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 no output schema, description thoroughly explains return format and all relevant behaviors (wait timeout, error states, synced meaning). Covers parameters, usage context, and alternative tool references, making it complete 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?

Adds meaning to both parameters: wait explained as fire-and-forth flag, items described as array of selectors (item_id, connector_id, or connector_name) with instruction to omit for all banks. Schema provides no descriptions, so description fully compensates.

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

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

The description clearly states the tool forces a bank to re-sync connections and waits for completion. It distinguishes itself by explaining it pulls fresh data without disconnecting/reconnecting, and mentions the return format with results and errors.

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

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

Explicitly advises to use when balance or transaction list looks stale, states it pulls fresh data without disconnecting, and suggests omitting items to sync all. Provides guidance on fire-and-forget via wait=false and mentions re-checking with openfinance_get_item_status on timeout.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral context: it details error handling (warning instead of throwing for CREDIT accounts, degradation to last-synced balance with realtime:false for upstream issues) and the response shape. 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 slightly verbose but well-structured: purpose first, then parameter usage, then error behaviors, then response shape. Each sentence adds value without redundancy. Could be marginally more concise, but effective.

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

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

Given the tool has one parameter, no output schema, and returns complex responses with errors and warnings, the description covers the response shape, error modes, and degradation behavior. It lacks details on pagination or rate limits, but for a read-only, idempotent tool this is 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?

The input schema has 0% description coverage. The description compensates by adding the constraint that account_ids must be an array of 1-50 strings and explains its purpose. It does not elaborate on the format of individual account IDs, but the added value is substantial.

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 real-time balance per account id, using a specific verb ('Returns') and resource ('balance payload per account id'). It distinguishes from sibling tools like openfinance_list_accounts (which lists accounts) and openfinance_get_accounts_detail (likely returns more account info) by specifying the balance focus.

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 context by specifying the parameter constraint (array of 1-50 ids) and detailing error scenarios. While it does not explicitly state when not to use it or list alternatives, the purpose is distinct enough for an agent to differentiate from 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 readOnlyHint and idempotentHint. The description adds valuable behavioral context: the batch response shape {results, errors}, the provider_incident block warning, and reliability caveats for credit limits/balances. This exceeds 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?

Three sentences: main action, batch shape, and a warning. No filler, front-loaded, each sentence adds distinct 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 parameter, no output schema, and adequate annotations, the description provides reasonable completeness: it covers constraints, response shape, and a key error condition. Could mention the response structure in more detail, but not required 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 has 0% description coverage, but the description explains the sole parameter: an array of account IDs with a 1-50 size constraint. This adds meaning beyond the raw schema, though it could specify what account IDs refer to (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?

The description clearly states the tool returns full account objects with extended creditData per ID, using a specific verb and resource. It distinguishes itself from sibling tools like openfinance_list_accounts by emphasizing detailed information and batch shape.

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 specifies passing account_ids as an array (1-50) but does not explicitly state when to use this tool versus alternatives like list_accounts or other detail endpoints. Usage context is implied rather than explicit.

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 and idempotentHint=true. The description adds critical behavioral context: batch shape { results, errors }, connector-specific behavior (Pluggy does not return paid/status field; Brazilian Open Finance payments reflect previous bill), and a warning not to reconstruct totals. 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 thorough but slightly long; however, every sentence adds value. It is well-structured with a main statement followed by detailed notes and caveats. Could be slightly more concise, but not overly verbose.

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 has one parameter, no output schema, and moderate complexity (batch result, connector-specific behavior), the description fully covers what the agent needs: return fields, usage pattern, limitations, and behavior across different financial systems. 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?

Schema has 0% description coverage, so the description fully compensates. It explains that bill_ids must be passed as an array, and advises using openfinance_list_credit_card_bills first to discover ids. Only one parameter, so coverage is complete.

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

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

The description explicitly states the tool returns bill-level detail for credit card bills by id, listing specific fields (financeCharges, payments). It also distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_credit_card_bills, making purpose crystal clear.

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

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

Provides explicit when-to-use (get bill details), what NOT to do (do not sum transactions by billId), and when to use alternatives (use openfinance_list_transactions for itemized transactions, openfinance_list_credit_card_bills to discover bill ids). Also warns about interpreting payments and paid status, offering a preferred alternative.

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

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

Annotations already declare readOnlyHint and idempotentHint, so safety is covered. The description adds response structure details (e.g., `{ count, items }` for the all-banks case) and lists example status values, which 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?

Two sentences with no fluff. The purpose is front-loaded, and the two usage modes are clearly separated. 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 the low tool complexity (one optional parameter, no output schema), the description is mostly complete. It covers both modes and expected status values, but could be more precise about the single-bank response structure.

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

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

With 0% schema description coverage, the description fully explains the single parameter `item`: omitting it returns all banks, passing it returns a single bank. This adds essential meaning beyond the schema type definition.

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

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

The description clearly states it returns the current status of a bank connection with specific status values and distinguishes between retrieving all banks vs. a single bank. It differentiates from siblings like openfinance_list_connections.

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

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

Provides clear context on when to omit or pass the `item` parameter to get all banks vs. a single bank, but does not explicitly mention when not to use the tool or compare to alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds further behavioral details: HTTP method, batch shape with results/errors, and a comprehensive list of returned fields. 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 sentence with dense information, but well-structured with parenthetical detail. Could be slightly cleaner with bullet points, but conciseness is maintained.

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

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

Given no output schema and 0% schema coverage, the description provides sufficient context on parameter and return structure. Minor gaps: no explicit mention of auth requirements or error handling details, but acceptable for a read-only batch endpoint.

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

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

Schema coverage is 0%, so the description carries full burden. It clarifies that loan_ids is an array of strings with length 1-50 and mentions the batch shape. Prevents misuse of wrong type or size.

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

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

The description clearly states it returns full loan contract detail by ID, listing multiple specific fields. It distinguishes from the sibling tool openfinance_list_loans by specifying this is a deep-dive endpoint.

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

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

Explicitly instructs to use after openfinance_list_loans for deep-dive, and specifies the parameter constraint (array of 1-50 strings). Provides clear usage context and batch shape.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds substantial context: connector-dependency of credit balances, existence of 'provider_incident' block causing unreliable data, and aggregation behavior. 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 comprehensive but somewhat lengthy. It front-loads the main purpose, then adds necessary caveats and details. Every sentence serves a purpose, but could be slightly more concise.

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 (multiple account types, connector-dependence, provider incidents) and absence of an output schema, the description covers all critical aspects: fields returned, meaning of 'bank' vs 'name', credit balance ambiguity, and provider incident handling. It is very complete.

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

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

Schema has no descriptions (0% coverage). The description explains the 'item' parameter well (omitting for all, specifying for one). The 'type' parameter is implied through discussion of account types but not explicitly stated as a filter. This adds significant 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?

The description clearly states the tool returns accounts for bank connections, listing details like balance and type. It distinguishes between BANK and CREDIT types and explains the 'bank' field vs 'name' field. Among siblings like 'openfinance_list_connections' or 'openfinance_list_credit_card_bills', this tool's purpose is specific and unique.

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: OMIT 'item' for all banks, pass 'item' for a single bank. Warns against misinterpreting credit balance as this month's bill, recommending 'openfinance_list_credit_card_bills' instead. Also advises ignoring data when 'provider_incident' is present. These guidelines effectively tell when and when not to use this tool.

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

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

Annotations already indicate read-only and idempotent behavior; the description adds useful details like caching per session and that it returns a single aggregated response with no batch IDs, enhancing 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 concise with two sentences, front-loading key information (returns taxonomy, cached) and adding response field details without 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?

Given no parameters, good annotations, and no output schema, the description sufficiently explains the tool's purpose, behavior (caching), response structure (fields), and usage hints (language preference), making it complete.

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

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

The input schema has no parameters and 100% schema coverage, so the baseline is 4; the description adds no parameter information, which is appropriate since none 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 the tool returns 'Pluggy's transaction category taxonomy' and mentions the underlying endpoint, distinguishing it from sibling tools by specifying it returns categories used by another tool.

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

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

The description explains the result is cached and provides guidance on using descriptionTranslated for pt-BR users, but does not explicitly state when to use this tool over alternatives; however, given no sibling returns categories, the usage intent 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the returned fields (connector_id, item_id, bank name, add_connection_url) but does not mention any potential side effects or behavior beyond the annotation-provided safety profile.

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

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

A single sentence that is front-loaded with the action and resource, no wasted words. Every part of the description is valuable.

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 the returned fields sufficiently. However, it could be more complete by mentioning pagination, ordering, or performance characteristics 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?

The tool has zero parameters, so there is no need for parameter-level description. The description adds no parameter information, but baseline for 0 parameters is 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 it returns saved bank connections for this install, listing specific fields (connector_id, item_id, bank name, add_connection_url). The verb 'Returns' and resource 'saved bank connections' are specific and unambiguous, distinguishing it from sibling list tools.

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

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

The description provides no guidance on when to use this tool versus alternatives, no context on prerequisites or when not to use it. It simply states what it does without usage direction.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds extensive behavioral context: Brazilian Open Finance semantics for payment assignment, derived payment_status logic, open bill derivation with confidence levels, connector asymmetry scenarios, and warning behavior for disabled products. 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 very long and densely packed with details. While every sentence adds value, it lacks conciseness and could be restructured for easier scanning. Front-loads basic output but then dives into extensive edge cases and derivations.

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

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

No output schema, but description fully explains the response structure: fields per bill, payments array, payment_status derivation, open_bill with confidence, future_bills, warnings (bill_grouping_reliability, connector_asymmetry). Covers all return values and edge cases comprehensively.

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 carries full burden. It explains account_id (required), include_open_bill (with detailed effects), account_ids (batch), and implicitly page/page_size via bulk support. However, page and page_size parameters are not explained in detail, leaving some ambiguity about pagination behavior.

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 CREDIT-type accounts, listing specific fields like dueDate, totalAmount, and payment arrays. It distinguishes from sibling tools like openfinance_get_credit_card_bill and openfinance_list_transactions by specifying the scope (list vs detail, bill-level vs 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 advises when to use include_open_bill (opt-in for open bill and total debt), when to use openfinance_list_transactions for itemized purchases, and warns about connector asymmetry and bill grouping reliability. Also instructs not to reconstruct bill totals from transactions, providing clear when-to-use and when-not-to guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the return structure and error handling (returns { total:0, results:[], warning } instead of throwing). This provides 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 paragraph that efficiently conveys purpose, asset types, return fields, and error behavior. It is well front-loaded with the core function. Some additional structure (e.g., bullet points for fields) could improve readability, but it remains concise.

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 tool has four parameters and no output schema. The description partially covers the output fields but lacks any parameter guidance. Without parameter documentation, the description is incomplete for effective tool use.

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

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

Schema description coverage is 0%, meaning the schema provides no descriptions for the four parameters (item, page, type, page_size). The description does not compensate: it mentions fields returned but does not explain how to use the parameters or map the 'type' enum to the listed investment types. This is a significant 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 investment portfolio for a connection and lists specific asset types. However, it does not explicitly differentiate from the sibling tool 'openfinance_list_investment_transactions', which focuses on transactions rather than holdings.

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 by stating what the tool does (portfolio retrieval) and mentions error handling, but it does not provide explicit guidance on when to use this tool versus alternatives like list_investment_transactions or 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, destructiveHint=false, idempotentHint=true. The description adds value by specifying the exact fields returned (quantity, value, amount, netAmount, etc.) and the itemized expenses. 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. The first sentence clearly states the purpose, followed by a list of fields, and a second paragraph on bulk support. 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 provides a good overview of the return fields. However, it does not explain the pagination parameters (page, page_size), which are present in the schema. Otherwise, it is complete for the tool's complexity.

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

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

The schema has 4 parameters but 0% schema description coverage. The description mentions investment_id and investment_ids (bulk support) but omits the page and page_size parameters. This leaves the agent to infer pagination from schema names alone, which is insufficient.

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

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

The description clearly states it returns movement history for a specific investment position, listing transaction types (BUY/SELL/TAX etc.) and the fields returned. It distinguishes from the sibling tool openfinance_list_investments by explicitly noting it should be used after that tool to get the investment_id.

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

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

The description tells the agent to use this tool after openfinance_list_investments to obtain the investment_id, and mentions bulk support via investment_ids. It does not explicitly state when not to use, but the context is clear and provides a clear reference to a related sibling.

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. Description adds value by disclosing sequential execution with rate-limit spacing and return format '{ results, errors }' per connection, 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?

Two sentences with no waste: first sentence states purpose and endpoint, second explains parameters and behavior. Front-loaded and efficient.

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

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

Given one optional parameter and no output schema, the description fully covers purpose, parameter semantics, sequential behavior, rate-limiting, 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?

Input schema has one property 'items' with 0% description coverage. Description compensates by explaining that 'items' is an array of connection selectors (item_id uuid, connector_id, or connector_name), adding critical 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?

Description clearly states it lists loan contracts per bank connection, specifying the HTTP GET endpoint. This distinguishes it from sibling tools that list other financial data types such as accounts or transactions.

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

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

Provides explicit usage guidance: pass 'items' as an array of connection selectors to fetch specific connections, or omit to list across all linked banks. Also explains sequential querying with rate-limit spacing. Lacks explicit mention of alternatives but context is clear.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: auto-pagination up to 5000 with truncation warning, per-connector differences in CREDIT pending/posted display, provider incident handling, and error responses returning {total:0, results:[], warning, error} instead of throwing. No contradiction with annotations.

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

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

The description is long but well-structured with logical sections (pagination, detail levels, bulk support). Every sentence adds value, though some redundancy exists (e.g., billId caution mentioned twice). It is front-loaded with the core functionality. A slightly more concise version could earn a 5.

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 (8 parameters, no output schema, numerous edge cases), the description is remarkably complete. It covers pagination behavior, filtering, error handling, per-connector nuances, relationship with other tools (bills, accounts, item status), and response structure (account echo, provider_incident block). The description leaves minimal gaps for an AI agent.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains all parameters: from/to (ISO YYYY-MM-DD), search_queries (case- and accent-insensitive substring OR-match), page (omit for auto-pagination, explicit for manual, max 500 for page_size), detail (compact/rich/raw with specific behaviors), account_id required, account_ids for bulk. It also describes the response structure, compensating for the 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?

The description states the tool returns transactions for a bank account, distinguishing between BANK and CREDIT types. It differentiates from siblings like openfinance_list_credit_card_bills by clarifying that for CREDIT accounts, this is the only way to get itemized transactions. The purpose is specific and clear.

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

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

The description provides extensive usage guidance: when to use this tool vs alternatives, such as using openfinance_list_credit_card_bills for standardized bill totals. It explains when to narrow from/to if truncated, how to handle pagination (omit page for auto-pagination, explicit page for manual walk), and what to do if total is 0 for CREDIT accounts (check connection health). These guidelines are explicit and actionable.

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 annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: it mentions a scan cap of 5000/account with a truncation flag, a provider_incident block for Open Finance provider issues, and the effects of different granularity and detail settings. No contradictions are present.

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

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

The description is long but each sentence adds value. It is structured logically: purpose, parameters, use cases, caveats. It could be slightly more concise, but the level of detail is justified by the tool's complexity. It is front-loaded with the main purpose and key differentiator.

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

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

Given 7 parameters, no output schema, and many sibling tools, the description is nearly complete. It explains the output format (compact vs raw, top expenses, per-account breakdown), covers edge cases (truncation, provider incidents), and provides usage examples. No output schema exists, but the description sufficiently describes return values.

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 explain parameters. It does so thoroughly: it explains 'from' and 'to' as ISO dates, 'item' as targeting a connection or all connections, 'granularity' with defaults and output implications, 'detail' values and their enrichment, 'type' for filtering BANK or CREDIT, and 'top_n' is implied in top_despesas/recebimentos. Nearly every parameter is clarified 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's purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It specifies the verb 'analyze' and the resource 'transactions by item', and distinguishes it from sibling tools by noting that it eliminates the need to call openfinance_list_accounts first.

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 for 'análise anual/mensal', 'fluxo de caixa', 'entradas e saídas', 'maiores gastos/recebimentos''. It also explains when to switch granularity to 'raw' for itemized rows and when to use 'detail' options. However, it does not explicitly state when not to use this tool versus the sibling openfinance_list_transactions, which could cause confusion.

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?

No annotation contradiction. Description adds behavioral context beyond annotations: returns global indicator, degraded components, open incidents, and flags your connected banks' affected incidents.

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 adding value: purpose, usage scenario, and return details. No wasted words; 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?

Despite no output schema, description fully explains return content (global indicator, degraded components, incidents, your_banks_affected), making it complete for a status check 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, so schema coverage is 100% trivially. Description need not explain parameters; baseline 4 is appropriate.

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

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

The description uses specific verb 'checks' and resource 'LIVE operational status of the Open Finance provider', clearly distinguishing it from sibling tools like 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?

Explicit guidance: 'Use it whenever data looks incomplete or stale... it reveals an upstream outage...' and contrasts with connection-level status, providing clear when-to-use and 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 declare read-only and idempotent, and the description adds behavioral details such as the caveat for non-Open-Finance connectors and plan-based filtering. 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 detailed but well-structured, starting with the core functionality and then adding important nuances. It is not overly verbose and each sentence serves a purpose.

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

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

Given no output schema, the description fully explains the return structure, including caveats and plan-based behavior. It is sufficiently complete for a search tool, though error handling is not covered.

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 both parameters: keywords as an array of strings (with examples) and include_accounts as a boolean for including accounts. This compensates for the lack of schema 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 the tool searches bank connectors by name, returning numerous details and a connect URL. It distinguishes from sibling tools like connect and marketplace by specifying its role in the connection workflow.

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 that keywords is required, returning a hint if omitted. It does not mention when not to use or alternatives, but usage is clear from 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 provide minimal info (non-readonly, non-destructive, non-idempotent). Description adds critical behavioral context: it overrides automatic categorization and creates a Category Rule affecting future transactions. 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 a single dense paragraph but front-loads the main action and then provides necessary details about side effects and batch behavior. Could be split into clearer sentences, but no waste.

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

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

Given no output schema, description thoroughly explains return shape { updated, results, errors } and batch behavior. Covers purpose, parameters, side effects, and error handling adequately for a complex tool.

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

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

Schema coverage is 0%, so description compensates by explaining 'items' as an array with transaction_id and category_id, and specifying where to get those IDs (from list tools). Adds meaning beyond the schema's type/required 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?

Description clearly states the tool corrects transaction categories via PATCH endpoint. It specifies the verb 'corrects' and resource 'transaction categories', and distinguishes from sibling tools like openfinance_list_transactions and openfinance_list_categories by telling where to get 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?

Explicitly states when to use: to fix miscategorized transactions and improve future categorization. It provides sources for required IDs. While it doesn't explicitly list when not to use, the context and sibling names imply clear purpose. Missing explicit alternatives but still strong.

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 idempotentHint=true and destructiveHint=false. The description adds useful behavioral context by specifying that the conversation array is needed for reproduction, beyond what annotations indicate. No contradictions are present.

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

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

The description is two sentences long, front-loading the purpose and then a key guideline. Every sentence is necessary, with no 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?

Given no output schema and the tool's simplicity, the description covers the core task and a critical usage hint. It lacks mention of what happens after reporting (e.g., response or confirmation), but this is acceptable for a feedback 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 explain parameters. It only addresses the 'conversation' parameter (include for reproduction), leaving 'message' and 'context' unexplained. This is insufficient for an agent to understand their roles.

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 reports bugs, missing features, or sends feedback. The verb 'report' and resource types are explicit, and it distinguishes from sibling tools which are all unrelated (e.g., authenticate, connect, openfinance tools).

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

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

The description advises to 'Include the conversation array with recent messages for reproduction,' which provides context for when to include extra data. However, it does not explicitly state when not to use this tool or mention alternatives, though sibling tools cover distinct functions making confusion unlikely.

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

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

Annotations already declare read-only and idempotent; description adds specific version output context 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?

Single sentence with clear, front-loaded verb and object; 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 simple read-only tool with no parameters, the description fully specifies its return value without needing output schema.

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 present; baseline 4 per rules for zero-parameter tools.

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

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

The description clearly states it shows MCP platform and adapter versions, distinguishing it from other 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 when to use vs alternatives, but the tool is self-explanatory and has no siblings with overlapping purpose.

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 as true/false, indicating safety and idempotency. The description adds details about return content but not additional behavioral traits (e.g., auth requirements, rate limits). Given the annotations cover the safety profile, the description's contribution is minimal.

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 front-loads the purpose and returns. It is concise with no wasted words, earning its place.

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

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

Given zero parameters and full annotation coverage, the description sufficiently explains what the tool returns. Without an output schema, the description provides enough detail about the return value (installed MCPs, connection status, catalog tool counts).

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

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

The input schema has zero parameters, so the description does not need to explain them. Baseline for 0 params is 4, and the description is appropriately succinct about this.

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

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

The description clearly states the verb 'returns' and the resource 'toolkit state', specifying the exact content: installed MCPs, connection status, and catalog tool counts. It distinguishes itself from sibling tools like authenticate or connect, which perform different actions.

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 it vs alternatives, nor does it provide exclusions or contextual guidance. It is a simple info tool, so the absence of guidance is less critical but still leaves room for improvement.

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