Sam's Club MCP

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

Describes behavior beyond annotations: explains token is JWT, optional, and two login modes. Annotations indicate idempotent and non-destructive, which aligns with description.

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?

Each sentence adds value, front-loaded with audience. Could be slightly tighter but overall well-structured and informative.

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 explains what happens (returns link or logs in). Adequate for a simple auth tool with one optional parameter.

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

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

Schema has 0% coverage, but description adds meaning: token is optional JWT from browser; calling with no args returns a link. This compensates for missing 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 explicitly states the tool authenticates users for MCP.AI IDE agents, detailing two methods (permanent config or session token). It clearly distinguishes from sibling tools like 'connect' or 'marketplace'.

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 when-to-use guidance: for logging in via browser, copy token, and choose between permanent (config) or session (pass token). 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=true and idempotentHint=true, so the read-only nature is clear. The description adds valuable context about conditional behavior (different returns based on connection state), which goes beyond the annotations. No contradictions.

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

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

Two concise sentences that front-load the main purpose and then explain the conditional behavior. No redundant or unnecessary 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 there is no output schema, the description does a good job explaining the two possible return states (authenticated:true with empty pending[], or connect_urls). It covers the main scenarios but could be more detailed about the exact fields returned.

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% (empty). The description does not need to add parameter information. Baseline for 0 parameters is 4, and the description meets that by focusing on output 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 the tool returns connection status and URLs, with specific output conditions for different scenarios. It distinguishes itself from siblings like 'authenticate' which handles authentication, and the openfinance tools which deal with specific data.

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?

While the description explains the output under different conditions (connected vs missing credentials), it does not explicitly guide when to use this tool over siblings or when not to use it. The usage context is implied but not clearly delineated.

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

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

Discloses key behaviors: invoke works even when MCP not installed, returns connect/checkout links, distinguishes installed_in_toolkit vs installed_in_workspace, and notes write permissions. Does not contradict annotations (readOnlyHint false, openWorldHint true).

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 and well-structured with key points bolded and a clear flow. It is somewhat long but efficiently conveys necessary information without unnecessary verbiage.

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

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

Covers main actions, usage rules, and edge cases (connect/checkout). However, lacks explanation of return format for search/describe/list_tools and does not address all parameters. Reasonably complete given complexity and absence of 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?

Schema description coverage is 0%. While the description explains actions and general flow, it does not describe individual parameters (e.g., immediate, tier_slug, conversation). With 13 parameters, more parameter-level guidance is needed to compensate 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 is the official marketplace for MCPs/tools, with a verb (use, search, describe, invoke) and resource (marketplace). It distinguishes from external registries and explains the core flow.

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 THIS tool FIRST', differentiates invoke vs install, mentions permission requirements for writes, and references sibling tools like report_bug and request_mcp. Provides clear when-to-use and when-not-to-use.

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

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

Annotations already provide destructiveHint=true. The description adds that the bank's data will no longer be available and that it returns a reconnection URL, which clarifies the destructive nature and suggests possible recovery path. No contradictions.

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

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

Three short sentences, each adding value: action, consequence, return value. No filler. Front-loaded with the primary verb, making it efficient for quick comprehension.

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 destructive tool with one parameter, the description covers action, data deletion, and return value. Missing details on error handling or prerequisites, but given the annotations and sibling context, it is reasonably complete.

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

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

The only parameter 'item' has 0% schema description coverage. The description implies it identifies the bank ('for a specific bank') but does not explain the format or expected values, leaving the agent to infer meaning. The description adds minimal guidance 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 specifies the verb 'revokes consent and deletes connection data' and the resource 'specific bank', distinguishing it from siblings like openfinance_list_connections (lists) and openfinance_force_sync (syncs). It leaves no ambiguity about the 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 implies usage for disconnecting a bank but does not explicitly state when to use versus alternatives (e.g., before reconnecting, or when consent needs revocation). It does not mention prerequisites or exclusions, but the return of an add_connection_url provides contextual 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?

Discloses polling behavior up to ~60s, non-destructive nature, and return fields. Annotations (readOnlyHint=false, destructiveHint=false) are consistent. Adds value beyond annotations by explaining what happens during sync and error handling.

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

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

Description is detailed and front-loaded with main action, but slightly verbose. Could be shortened without losing clarity. However, 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?

Covers all necessary context: input parameters, return structure (results, errors), status fields, and edge cases (needs_action, timed_out). No output schema, but description compensates completely.

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, but description fully explains both parameters: `items` as array of selectors (item_id, connector_id, connector_name) with omission syncing all, and `wait` boolean for fire-and-forget. 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?

Describes specific action: force re-sync and wait for completion. Clearly distinguishes from siblings like openfinance_get_item_status by explaining it pulls fresh data without disconnecting. Mentions use case for stale balances/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 when to use (stale data) and when not (needs_action requiring reconnect). Provides alternatives: re-check with openfinance_get_item_status on timeout, and fire-and-forget with wait=false. Covers both normal and exceptional 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 declare readOnly=true and idempotent=true. Description adds that errors are structured and credit accounts may produce warnings instead of exceptions, and specifies the response shape.

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?

Four brief sentences that front-load the core purpose, then add usage details and response shape. 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 one parameter and no output schema, the description covers purpose, input constraints, error handling, and response format, making it 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?

Schema has 0% parameter descriptions, but the description adds crucial constraints (array of 1-50) and behavior for CREDIT accounts, going beyond the schema.

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

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

The description clearly states it returns a real-time balance payload for given account IDs, and includes the API path. It distinguishes itself from siblings like `openfinance_get_accounts_detail` by being balance-specific.

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

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

Describes input constraints (array of 1-50 account IDs) and special handling for CREDIT accounts returning warnings. Provides usage context but does not explicitly compare to alternatives or state when not to use.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety. It adds the batch shape `{ results, errors }` and mentions extended creditData, but does not elaborate on error handling or prerequisites.

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 terse sentences, front-loading the core purpose and parameter constraints. It wastes no words, though the batch shape notation is slightly informal.

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 read-only tool with one parameter and no output schema, the description adequately covers the parameter range and batch shape. However, it does not explain the `results` and `errors` structure or potential error cases, which would improve 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?

The input schema has 0% description coverage for account_ids. The description adds critical context: it specifies the parameter is an array and constrains it to 1–50 items, significantly enhancing schema clarity.

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

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

The description clearly states the tool returns full account objects with extended creditData per id, using GET /accounts/:id. It specifies the batch operation with array of account_ids (1–50), distinguishing it from siblings like openfinance_get_account_balance and 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 explains to pass account_ids as an array of 1–50, implying batch usage. While it doesn't explicitly state when not to use or list alternatives, the sibling tool names provide context for 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?

Discloses critical behavior: Pluggy does not return a paid/status field, explains the Brazilian Open Finance nuance about payments[], and warns against assuming payment status. These details go beyond annotations, which already correctly mark it as 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?

The description is somewhat lengthy but well-structured, front-loaded with the main purpose, then details and warnings. Each sentence adds value, though a slight reduction in verbosity could improve conciseness.

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

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

Completely covers what the tool returns, what it does not, how to get related data, and nuances of the data. No output schema, but the description explains the output shape sufficiently for an agent to understand and use the tool correctly.

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

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

The only parameter (bill_ids) is explained: it must be an array, discovered via openfinance_list_credit_card_bills. The description also mentions the batch result shape. With 0% schema coverage, the description compensates well, though it could add examples.

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 clearly that the tool returns bill-level detail for credit card bills by ID, listing specific fields (financeCharges, payments). It distinguishes from openfinance_list_transactions, which returns itemized transactions, providing clear differentiation from siblings.

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

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

Explicitly guides when to use this tool (after discovering IDs via openfinance_list_credit_card_bills) and when to use alternatives (openfinance_list_transactions for itemized transactions). Also warns about misinterpreting payments and recommends checking payment status via another tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description aligns and adds behavioral context: omitting 'item' returns { count, items } vs single bank data. It does not contradict annotations and provides useful beyond-annotation detail, though it omits authorization or rate limit info.

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 return value, then concise usage instructions. Every sentence earns 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 only one optional parameter, no output schema, and annotations covering safety, the description is fully complete. It explains both usage modes and the expected return structure, leaving no critical gaps.

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

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

The sole parameter 'item' has 0% schema coverage, but the description fully explains its semantics: omitting it returns status for all banks, passing it returns status for a single bank. This adds critical meaning absent from the schema, making the parameter's effect crystal clear.

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

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

Clearly states the tool returns bank connection status (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, and connector metadata. Differentiates two modes: omitting item for all banks or passing item for a single bank. This distinct purpose is well-defined and distinguishes it 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 explicit guidance on when to pass or omit the 'item' parameter, describing the return format for each mode. However, it does not compare this tool to similar siblings like openfinance_list_connections or openfinance_provider_status, leaving some ambiguity about when to choose this over 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, idempotentHint=true, destructiveHint=false. The description adds critical behavioral context: explains that CREDIT balance meaning is connector-dependent, describes creditData fields (balanceCloseDate, balanceDueDate), and clarifies that `name` is the legal entity, not the brand. 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 relatively long but front-loaded with key functionality. Every sentence adds essential value, covering param usage, response fields, and important caveats. Minor redundancy could be trimmed, but overall it is well-structured and efficient for 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?

The tool has no output schema, so the description must provide thorough response context. It does so by explaining key fields (balance, bank, connector_id, creditData fields, etc.), addressing edge cases (connector-dependent credit balance), referencing sibling tool for bill details, and detailing the impact of the `item` param on response structure. It is complete for the tool's complexity (2 params, multiple account types, nuanced 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 input schema has two optional params (item string, type enum) with 0% schema description coverage. The description fully compensates: explains that `item` controls whether to list single or all banks, and `type` filters by account type. It also explains how response includes bank/connector_id/item_id based on `item` usage. This adds complete semantics 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 that the tool returns accounts for a bank connection (BANK and CREDIT types) with detailed fields (balance, number, type, subtype, bankData, creditData, bank, connector_id). It distinguishes between account types and clarifies the meaning of `name` vs `bank`. It also differentiates from sibling tool openfinance_list_credit_card_bills for credit bill 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 explicitly explains when to use `item` (target a single bank) versus omitting it (list all banks). It warns that CREDIT balance is connector-dependent and not to treat as a standard bill amount. It directs users to openfinance_list_credit_card_bills for standardized billing info. It also mentions how the response structure changes based on `item` presence.

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

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

Annotations already mark readOnly, idempotent, non-destructive. Description adds caching behavior and language preference, providing useful context beyond annotations.

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

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

Concise, efficient, front-loaded with purpose. Every sentence adds value: caching, field details, language hint, single response.

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 response structure (id, description, descriptionTranslated, parentId, parentDescription). Covers caching and language preference. Complete for a simple no-parameter 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; schema coverage is 100% (empty). Description does not need to add param info, but it clarifies output structure. Baseline 4 for zero parameters.

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

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

Description clearly states it returns the category taxonomy, cached, and details the fields (id, description, etc.). It distinguishes from siblings by noting its use in openfinance_update_transaction_category and that it's a single aggregated response.

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

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

Provides usage context: cached for the session, single response, and language preference. Implicitly suggests using before category updates. No explicit when-not, but clear enough.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by mentioning the returned fields and the add_connection_url, but does not disclose potential rate limits, authentication requirements, or the behavior when no connections exist.

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 action and resource. Every word earns its place, with no extraneous information. It is highly concise and clear.

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

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

Given the simple list operation, no output schema, and annotations, the description is fairly complete. It specifies the exact return fields and the notable add_connection_url. However, it lacks mention of pagination or limits, which would be useful for a complete understanding.

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 naturally provides no parameter details. As per guidelines, a baseline of 4 is appropriate since no parameter explanation is needed.

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

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

The description clearly specifies the verb 'Returns' and the resource 'saved bank connections', listing exact fields (connector_id, item_id, bank name, add_connection_url). It effectively distinguishes from sibling tools like openfinance_list_accounts and openfinance_list_transactions by focusing solely on connections.

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

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

The description implies usage when needing to view existing bank connections, but provides no explicit guidance on when to use this tool versus alternatives like connect or openfinance_disconnect_bank. No when-not-to-use or prerequisite conditions are stated.

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 numerous behavioral traits beyond annotations: the complex payment allocation logic across bills, derivation of payment_status, connector asymmetry for open bill, that results are bill-level summaries (not transactions), and that it returns a warning if CREDIT_CARDS product is not enabled. Annotations already indicate readOnly, idempotent, non-destructive; description adds rich context without contradiction.

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

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

The description is verbose and lacks structural elements like sections or bullet points. While the detailed content is valuable, it is not concise; the information could be more efficiently organized. The length is justified by complexity, but it still impacts 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, zero schema documentation, and no output schema, the description is remarkably complete. It explains output fields, derivation logic, open_bill structure, connector asymmetry, and edge cases (e.g., PAST_DUE_UNCONFIRMED). Only pagination parameters lack explanation, but that is minor relative to the rich context provided.

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

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

With 0% schema description coverage, the description compensates by explaining include_open_bill in detail and mentioning bulk support via account_ids. However, it does not describe page and page_size parameters explicitly, leaving a minor gap. Overall, it adds significant meaning to parameters beyond schema definitions.

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

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

The description clearly states it returns CLOSED credit card bills for a CREDIT-type account, listing specific fields like dueDate, totalAmount, payments[], etc. It distinguishes from siblings such as openfinance_get_credit_card_bill (single bill) and openfinance_list_transactions (individual transactions), making the tool's purpose unambiguous.

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

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

The description provides extensive usage guidance: when to use this tool (to get closed bills), when to opt-in include_open_bill, how to interpret payment_status, and what to use instead of balance (total_pending_debt). It explicitly warns against assuming payment status from payments[] and advises using openfinance_list_transactions for itemized charges. This covers when-not-to-use and 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 indicate readOnlyHint=true, destructiveHint=false. The description adds valuable context about error behavior: returns { total:0, results:[], warning } instead of throwing 403 or other errors. This goes beyond annotations and helps an agent understand safe usage.

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 reasonably concise and front-loaded with the main purpose. The list of asset types and output fields adds clarity, though it could be slightly more compact. It avoids redundancy and maintains focus.

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 four parameters with no documentation and no output schema, the description fails to cover important aspects like pagination, required parameters, or how to filter by type. It only describes outputs, leaving the agent underinformed for correct invocation.

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

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

With 0% schema description coverage, the description must explain the four parameters (item, page, type, page_size). It provides no parameter information, leaving the agent without guidance on how to supply values or constraints (e.g., type enum values, pagination semantics). This is a critical gap.

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

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

The description clearly states the tool returns the investment portfolio for a connection, listing specific asset types (FIIs, stocks, ETFs, fixed income, mutual funds, retirement, COE) and output fields (balance, amount, rates, etc.). It effectively distinguishes from siblings like openfinance_list_investment_transactions by focusing on portfolio data rather than transactions.

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

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

The description implies use when portfolio data is needed and notes safe error handling (returns warning structure instead of throwing). However, it lacks explicit guidance on when not to use this tool or alternatives, such as openfinance_list_investment_transactions for transaction-level data, which would help an agent choose correctly among many 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it is safe and idempotent. The description adds rich behavioral detail: specific transaction types, included fields (expenses breakdown), and bulk capability. It does not contradict annotations. A minor gap is the lack of pagination behavior details, but overall strong.

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 concise paragraphs with front-loaded information. The first paragraph clearly states purpose and output, the second adds usage hint and bulk support. Every sentence adds value with 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?

The tool has 4 parameters, no output schema, and good annotations. The description explains return fields, prerequisite usage, and batch capability. It lacks explicit error handling or pagination defaults, but for a read-only list tool it covers the essential context. The return format is partially described.

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 compensates partially. It explains the key parameter investment_id (implied required) and introduces bulk support via investment_ids. However, it does not explain page and page_size parameters, leaving ambiguity about pagination. Given the low coverage, the description adds essential context but not fully comprehensive.

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, listing transaction types (BUY/SELL/TAX/INTEREST/AMORTIZATION/TRANSFER) and key fields. It distinguishes from sibling tools by noting usage after openfinance_list_investments 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 provides clear guidance on when to use: after getting investment_id from openfinance_list_investments. It also mentions bulk support via investment_ids. However, it does not explicitly exclude scenarios where other tools (e.g., openfinance_list_transactions) might be more appropriate, but the specific focus on investment movements 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?

Discloses behavioral traits beyond annotations: sequential queries with rate-limit spacing, per-connection results with errors. Annotations already indicate read-only and idempotent, and the description adds operational details without contradiction.

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

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

The description is concise and front-loaded with purpose. Every sentence adds value: purpose, parameter usage, behavior, and return format hint. No wasted words.

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

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

Given the low complexity (one optional parameter, no output schema), the description is fully complete. It covers input options, behavior, and return structure hints, leaving no critical gaps.

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

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

Despite 0% schema description coverage, the tool description fully explains the `items` parameter: it accepts connection selectors (item_id, connector_id, or connector_name) and omitting it lists all. This adds critical meaning beyond the schema's bare 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?

Clearly states this tool lists loan contracts per bank connection, with a specific verb ('list') and resource ('loan contracts'). It distinguishes from sibling tools like openfinance_list_accounts by focusing on 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?

Provides clear guidance on when to use this tool: to list loans per bank connection, with optional `items` filter. Explains that omitting `items` lists all loans across all linked banks. However, no explicit mention of alternatives or when not to use it, but the context of sibling tools makes it 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?

Discloses behavior beyond annotations: error returns, CREDIT PENDING vs POSTED nuances, search aggregation limits, and connection health checks. No contradiction with readOnlyHint=true.

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?

Well-structured with front-loaded purpose, but somewhat lengthy. Each sentence adds value, but could be slightly more concise. Still highly efficient given complexity.

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

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

Extremely complete: covers all parameters, error handling, edge cases, relationships with other tools (bills, item status), and bulk support. No output schema, but description sufficiently hints return format and truncation.

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 date format, pagination max, search_queries semantics (OR matching, case-insensitive), and bulk account_ids. Provides essential meaning for all parameters.

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

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

Clearly states it returns transactions for BANK or CREDIT account types, distinguishing from siblings like openfinance_list_credit_card_bills. Uses specific verb 'Returns transactions' and identifies resources.

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

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

Explicitly tells when to use (for itemized transactions) and when not (for standardized total, use openfinance_list_credit_card_bills). Also provides guidance on filtering, error handling, and bulk execution.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds critical behaviors: internal account resolution, fan-out of transactions, scan cap of 5000/account with truncation flag, compact vs raw output, default granularity, and filter by type. 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?

Description is detailed but each sentence adds value. It front-loads the core purpose and then lists key details. Could be slightly more concise (e.g., listing fields in parentheses), but 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?

Given 6 parameters, 2 enums, no output schema, the description covers input semantics, default behavior, output structure (compact summary fields, raw rows, truncation flag), and use cases. No missing information for a typical agent 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 6 parameters with 0% description coverage, so description carries full burden. It explains item (connector_id/name/item_id, optional), from/to (ISO dates), granularity (monthly/raw with default), type (BANK/CREDIT). However, top_n parameter is not explicitly linked to 'largest N' in description, leaving a minor gap.

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

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

The description states a specific verb+resource: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It clearly distinguishes from sibling tools by noting it resolves accounts internally, eliminating the need for openfinance_list_accounts.

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

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

Provides explicit use cases ('análise anual/mensal', 'fluxo de caixa', etc.), when to omit item (analyze all banks), when to use raw granularity (only when itemized rows needed), and that no prior account listing is required. Also suggests top_despesas/recebimentos for largest entries.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds context about return values (global indicator, degraded components, open incidents, affected banks), which is useful 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 relatively long but well-structured with two sentences that front-load the main purpose and then provide detailed guidance. 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 parameters and no output schema, the description is comprehensive: explains what it does, when to use, what it returns. Fully covers the tool's 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 zero parameters and 100% schema coverage, the description doesn't need to add parameter detail. 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 clearly states it checks the LIVE operational status of the Open Finance provider's public status page, distinguishing it from sibling tools like openfinance_get_item_status. It uses specific verbs and resources.

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

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

Explicitly tells when to use this tool (when data looks incomplete/stale despite connection showing updated) and what it reveals (upstream outage, known incidents). Provides clear use case 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 already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral details: the tool returns a connect_url, honors user plan to filter banks, and returns a hint when no keywords are provided. No contradictions with annotations.

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

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

The description is concise with three sentences, covering purpose, behavior, and constraints. It could be slightly more structured, but front-loads the main action and is free of fluff.

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

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

Given no output schema, the description adequately describes return values (connector id, access, audience, links, accounts, connect_url) and error behavior (hint for no keywords). It covers plan-based filtering. Missing some clarity on the default behavior of include_accounts.

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 provides examples for keywords and mentions include_accounts affects account inclusion. However, it lacks precise syntax for parameters and does not fully describe the effect of include_accounts when false. This is adequate but not exhaustive.

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 'Searches the available bank connectors by name', providing a specific verb and resource. It distinguishes its purpose from siblings by stating 'Call this BEFORE connecting to hand the user a one-click link', which sets it apart from connection-related tools.

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

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

Explicitly states when to use ('Call this BEFORE connecting') and provides a key constraint ('keywords[] is REQUIRED — without it returns a hint'). It mentions plan-based filtering but does not explicitly name alternatives or specify when not to use.

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

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

Annotations indicate a mutating operation. The description adds that recategorizing teaches Pluggy and creates a Category Rule for future similar transactions, and describes batch error handling, offering 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?

The description is dense with information, well-structured, and front-loaded. While lengthy, every sentence adds value, so it earns a 4.

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?

Without an output schema, the description fully explains the return shape (updated, results, errors) and how IDs are sourced from other tools, making it 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?

With 0% schema coverage, the description fully details the `items` parameter structure (array of objects with transaction_id and category_id) and tells where to obtain these IDs, adding 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 corrects transaction categories via PATCH /transactions/:id, referencing related tools for IDs, distinguishing it from sibling tools.

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

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

The description explains when to use it (to fix miscategorized transactions) and what it does (overrides automatic categorization, creates Category Rules). It lacks explicit exclusions or alternatives but provides clear context.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, so the tool is safe and non-destructive. The description adds the behavioral hint of including conversation for reproduction, but does not disclose any additional traits like rate limits or data handling.

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 concise with two sentences, no redundant information. It efficiently communicates purpose and a key usage guideline.

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 bug reporting tool without an output schema, the description is reasonably complete. It covers the purpose and a key input requirement. It could mention the expected response or effect, but given the straightforward nature, this is adequate.

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

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

With 0% schema description coverage, the description must compensate but only mentions the 'conversation' parameter, partially explaining its purpose. The 'context' and 'message' parameters are not described, leaving ambiguity.

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

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

The description clearly states the tool reports bugs, missing features, or feedback, which distinguishes it from sibling tools that focus on authentication, API connections, or financial operations. However, it lacks specificity on the reporting mechanism or resulting 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 provides a guideline to include the conversation array for reproduction, which helps the agent provide useful context. It does not explicitly state when not to use it, but the clear purpose implies appropriate usage given no similar sibling tools.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds that it shows version information, but no further behavioral traits (e.g., output format) are disclosed.

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

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

Single sentence front-loading the purpose. No wasted words; every part earns 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?

For a simple version tool with no parameters and no output schema, the description is sufficiently complete. It could optionally mention output format or structure, but the core purpose is clear.

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 description coverage is 100% (vacuously). The description does not need to add parameter details, so baseline score 3 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?

Clearly states the tool shows current MCP platform and adapter versions. It uses a specific verb and resource, distinguishing it from sibling tools like authenticate or connect which serve different purposes.

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. It is a simple info tool, but the description does not provide context about preferred usage scenarios or any exclusions.

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 safety profile is covered. The description adds that it returns 'state' but no extra behavioral details like rate limits or caching.

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 no wasted words. Front-loads the action ('Returns') and lists specifics efficiently.

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

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

For a tool with zero parameters and no output schema, the description covers the return content adequately. Could optionally mention example use cases, but not 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?

No parameters exist, so schema coverage is 100%. The description correctly implies no input needed, which is adequate.

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 'current toolkit state' and specifies three distinct items: installed MCPs, connection status, and catalog tool counts. This verb+resource combination is unique among siblings.

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

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

No explicit guidance on when to use vs alternatives, but the read-only nature and diagnostic purpose are implied. A clear best practice mention would be beneficial.

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