Banco do Nordeste do Brasil MCP

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

Beyond annotations (idempotentHint=true, destructiveHint=false), the description adds that calling with no args returns a link and that passing a token sets it for the session. This discloses behavioral modes but doesn't detail 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?

The description is front-loaded with the purpose and then details the two usage methods. It is moderately concise; every sentence adds value but could be slightly more streamlined.

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

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

For a simple tool with one optional parameter and no output schema, the description covers main usage scenarios well. It lacks error handling details but otherwise provides sufficient context for 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?

The input schema has 0% description coverage with one undocumented string parameter. The description fully compensates by explaining the token is a JWT and that omitting it returns a login link, adding complete 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 authenticates for MCP.AI in IDE agents, specifying the action (log in via browser token) and the resource (MCP.AI). It distinguishes from siblings like 'connect' by focusing on token-based authentication.

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

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

The description provides clear context on when to use the tool: for initial login, with two methods (permanent config or session-only token). It does not explicitly state when not to use, but the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description adds value by detailing the two possible response states (authenticated:true with empty pending[] vs. connect_url). This provides useful behavioral context beyond what annotations offer.

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-loaded with the main purpose, and every sentence adds value. No wasted words.

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

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

Given no parameters, no output schema, and clear annotations, the description covers the two possible response states sufficiently for an agent to understand expected outputs. It could optionally list exact fields, but it is fairly complete.

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

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

With zero parameters and 100% schema coverage, the description does not need to add parameter semantics. The description is adequate for the tool's simplicity.

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, distinguishing between when all providers are connected versus when credentials are missing. It specifies the resource (connection status) and differentiates from sibling tools like authenticate.

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

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

The description implies when to use the tool—to check connection status and obtain URLs if needed. It does not explicitly state when not to use it or list alternatives, but the context is clear given the 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?

Describes key behaviors beyond annotations: invoke works even without installation, returns connect/checkout links when needed, write operations require workspace owner/admin. No contradiction with 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 relatively long but well-structured with front-loaded purpose and clear workflow explanation. Almost every sentence adds value, though some redundancy could be trimmed 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 the tool's complexity (13 parameters, no output schema, multiple actions), the description covers all major aspects: discovery, execution, installation, billing, feedback, and edge cases like auth/payment. Provides a comprehensive mental model for the agent.

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

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

Schema coverage is 0% with 13 parameters. While the description explains the `action` enum and some parameters (mcp_id, tool_id, arguments) implicitly through the workflow, it does not add semantic meaning for limit, query, immediate, tier_slug, conversation, request_name, report_context, request_details. Insufficient compensation for low schema coverage.

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

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

The description clearly identifies the tool as the official marketplace and primary catalog for discovering and running MCPs/tools. It distinguishes itself from siblings by stating it should be used first before any external or generic registry.

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 on when to use this tool: 'When the user wants a capability... use THIS tool FIRST'. Details the core flow (search → describe → invoke) and contrasts invoke (one-off) vs install (permanent), including prerequisites like credentials or payment.

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

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

Annotations already indicate destructiveHint is true. The description adds specifics: data will no longer be available, returns add_connection_url for reconnection. 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 sentences, front-loaded with main action. No unnecessary words. Efficiently conveys key information.

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

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

For a tool with one undocumented parameter and no output schema, the description should explain the parameter and return value structure. It mentions the return URL but not its format or contents. Incomplete.

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

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

Schema description coverage is 0%. The description fails to explain the 'item' parameter (e.g., what it represents or how to obtain it). No value added over 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 action: revokes consent and deletes connection data for a specific bank. It differentiates from sibling tools by describing a unique destructive operation.

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

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

No guidance on when to use this tool versus alternatives (e.g., other openfinance tools). It implicitly suggests use for disconnecting a bank but lacks explicit context or exclusion criteria.

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

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

Annotations are minimal (readOnlyHint false, destructiveHint false). Description adds significant behavior: waits up to 60s, polling mechanism, timed_out flag, and return field semantics. 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 moderately lengthy but well-structured with critical information front-loaded. Every sentence adds value, though some could be condensed slightly.

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 return shape, key fields, and error states. Covers timeout, polling, and sibling tool reference for re-check. 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?

Schema coverage is 0%, but description explains both parameters: wait (boolean for fire-and-forget), items (array of selectors or omit for all). Adds meaning beyond schema by clarifying valid selectors (item_id, connector_id, connector_name).

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 bank re-sync and waits for completion, using specific verb 'forces' and resource 'connections'. It distinguishes from siblings like openfinance_get_item_status by mentioning it as a fallback for timed_out condition.

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 (stale balance/transactions), what it does (pulls fresh data without disconnecting), and when-not-to-use (needs_action means reconnect). Also explains fire-and-forget via wait: false, giving clear context and 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 tool is safe. The description adds valuable context about CREDIT accounts potentially returning a structured warning instead of throwing an error, and outlines the response shape with results and errors.

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 well-structured sentences: purpose and endpoint first, then input guidelines, then error handling. Every sentence adds value without redundancy.

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

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

Given the tool has a single parameter and no output schema, the description covers purpose, parameter constraint, error behavior, and response structure. Minor gap: no explanation of the fields inside each result object, but acceptable for a balance 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?

With 0% schema coverage, the description partially compensates by stating the array type and a size limit of 1-50. However, it does not explain what the account IDs represent (e.g., from which list) or their format.

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 'balance payload per account id', including the exact endpoint. It distinguishes from sibling tools like openfinance_list_accounts by focusing on real-time balance for specific IDs.

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

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

Provides input guidelines: account_ids as an array with size limit (1-50) and mentions error handling for credit accounts. However, does not explicitly state when to use this tool versus alternatives like openfinance_list_accounts.

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

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

The description adds context beyond annotations: batch shape { results, errors } and extended creditData. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so description complements them without contradiction.

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

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

Three concise sentences: purpose, usage, output shape. 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?

Complete for a simple tool: describes input (array of IDs, size limit), output (batch with results/errors, extended creditData), and behavior (GET /accounts/:id). No missing aspects.

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; the description adds the size constraint (1–50) and implies the array format. It meaningfully supplements the schema.

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

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

The description clearly states it returns full account objects with extended creditData per ID. It distinguishes from siblings like openfinance_list_accounts (which returns a list without details) and openfinance_get_account_balance (which returns only balance).

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 provides input constraints: pass account_ids as an array of 1–50 items. It implies use when you need detailed data for specific accounts, but could explicitly mention when to use instead of list_accounts.

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

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

Adds context beyond annotations: notes batch shape { results, errors }, states Pluggy does not return a paid/status field, explains that payments[] may reflect previous bill payments. Annotations already indicate readOnly, idempotent, non-destructive; description complements well.

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 relatively long but each sentence serves a purpose. Could be slightly more concise, but for a domain-specific tool the detail is warranted. Front-loaded with core purpose and return fields.

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

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

Given no output schema, description fully covers return shape, what is included/excluded, and critical behavioral notes about payments and paid status. Very complete for a single-parameter tool with complex semantics.

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?

Only one parameter (bill_ids) with 0% schema coverage, but description instructs to pass as array and explains how to obtain ids via sibling tool. Provides enough semantic meaning for correct usage.

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

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

The description clearly states the tool returns bill-level detail for credit card bills by id, listing specific fields (financeCharges, payments) and explicitly stating what it does NOT return (individual transactions). This distinguishes it from sibling tools like openfinance_list_transactions.

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

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

Provides explicit guidance: use openfinance_list_credit_card_bills first to discover ids, and for transactions use openfinance_list_transactions with appropriate date range. Also explains the payment timing nuance and recommends checking paid status via openfinance_list_credit_card_bills.

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, so the tool is safe. The description adds valuable behavioral context: the return format when 'item' is omitted (count, items) versus passed (single status and metadata). This goes beyond annotations without contradiction.

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

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

Two sentences with no wasted words. The main purpose is stated first, then the two usage modes are explained concisely. Structure is 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?

For a status-check tool with no output schema, the description adequately hints at return structure (count, items for all; status, executionStatus, metadata for single). However, it could be more explicit about the exact fields returned for a single bank.

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

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

The schema has 0% description coverage for the single parameter 'item'. The description fully compensates by explaining that 'item' identifies a specific bank connection and that omitting it returns all connections. This is clear and 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?

Description clearly states the tool returns the current status of a bank connection, listing possible status values like UPDATED and LOGIN_ERROR. It distinguishes two modes: all banks versus a single bank, which differentiates it from sibling tools like openfinance_list_connections.

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

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

The description provides usage guidance for the two modes (omit or pass 'item') but does not explicitly contrast with sibling tools or state when to use this tool over others. Usage context is implied but lacks explicit exclusions or alternatives.

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

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

Annotations already indicate read-only and idempotent. The description adds critical context: the meaning of 'bank' vs 'name', the connector-dependent nature of credit card balances, the aggregation behavior when 'item' is omitted, and the structure of response fields. 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 relatively long but efficiently packed with essential information. It is logically structured: main function first, then naming clarifications, then usage guidance, then caveat about credit balances, then differentiation from sibling tool. Every sentence adds value, though slight trimming could improve 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 complexity (2 parameters, no output schema), the description is remarkably complete. It covers return fields, parameter effects, important caveats (credit card balance interpretation, naming conventions), and directs to the appropriate sibling tool for more specific credit card bill data.

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

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

With 0% schema description coverage, the description fully compensates. It explains the 'item' parameter (omit vs pass, effect on response structure) and implicitly the 'type' parameter (filtering by account type). Adds meaning 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 it returns accounts for bank connections with specific fields (BANK and CREDIT types) and differentiates from siblings like openfinance_list_credit_card_bills by explaining their distinct purposes. It tells the agent exactly what the tool does and how it differs from other 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?

Explicitly states when to omit 'item' (list across all banks) and when to pass it (single bank). Also warns against misinterpreting credit card balance as the current bill and directs to a specific alternative tool for standardized amounts. Provides clear actionable 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, idempotentHint=true, destructiveHint=false. The description adds valuable context: the response is cached for the adapter session and is a single aggregated response (no batch IDs). This goes beyond the annotations.

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

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

The description is concise (three sentences) and front-loaded with the main purpose. Every sentence adds value: the source API, caching, field descriptions, and the nature of the response. 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 fully explains what is returned (id, description, descriptionTranslated, parentId, parentDescription) and the caching behavior. It covers all relevant aspects for a simple no-parameter tool with rich annotations.

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 description coverage is 100%. The description adds no parameter-level info but compensates by explaining the output structure (fields and their meanings). Baseline score of 4 for zero parameters 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 returns 'Pluggy's transaction category taxonomy' and specifies it's cached for the adapter session. It distinguishes from sibling tools by explaining the content (id, description, parentId) and that it's a single aggregated response, no batch IDs.

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

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

The description does not provide explicit guidance on when to use this tool versus alternatives like openfinance_list_transactions or other list tools among siblings. It mentions caching but lacks context on when to refresh or rely on this data.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true, ensuring agents understand it is a safe read operation. The description adds behavioral context by specifying the exact returned data and noting that add_connection_url is used to link additional banks, which is helpful beyond annotations.

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

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

The description is a single sentence that front-loads the main action ('Returns the saved bank connections') and follows with specific details. No unnecessary 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?

Given the tool has no parameters and no output schema, the description adequately covers its purpose and return values. It could mention that authentication is implicitly required, but that is likely understood. Minor gap: no mention of pagination or limits, but for a list tool this is sufficient.

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

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

The tool has no parameters, and schema description coverage is 100%. The description adds complete context about what the tool returns, fully compensating for the lack of parameters. Baseline 4 is exceeded because the description explains the output meaningfully.

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 saved bank connections and lists key fields (connector_id, item_id, bank name, add_connection_url). This clearly distinguishes it from sibling tools like openfinance_list_accounts which return different 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?

The description does not provide explicit guidance on when to use this tool versus alternatives. While the purpose is clear, it does not compare to siblings or specify prerequisites. A score of 3 reflects adequate clarity without proactive usage advice.

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 extensive behavioral traits beyond annotations: payment semantics (pre-payment vs. cross-bill payment), derived payment_status with explicit logic, open bill derivation with connector asymmetry, and bulk support. It also clarifies that results are bill-level summaries, not individual transactions. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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, front-loading the main output and then addressing important semantics. Each section adds value, though some redundancy exists (e.g., reintroducing open_bill fields). It could be slightly more concise, but overall it is appropriately detailed.

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

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

Given the complexity of the tool and the absence of an output schema, the description is remarkably complete. It covers return fields, derived payment_status, open bill opt-in behavior, connector asymmetry, and provides links to related tools. The description leaves no major unanswered questions for an AI agent.

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

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

The input schema has 0% description coverage, so the description must compensate. It explains include_open_bill and account_ids in detail, but page and page_size are only mentioned in the schema without any description in the text. While the required account_id is implied, the omission of pagination parameter semantics leaves a gap. Thus, it falls short of the baseline 4 for 0 params.

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 CLOSED credit card bills for a CREDIT-type account, listing specific fields like dueDate, totalAmount, and payments[]. It distinguishes itself from siblings like openfinance_get_credit_card_bill and openfinance_list_transactions by specifying its scope (bill-level summaries) and linking to the latter for itemized transactions.

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

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

The description provides explicit guidance on when to use this tool versus alternatives, such as using openfinance_list_transactions for itemized purchases. It also includes do-not-use guidance regarding the payment_status derived field, warning against assuming a bill is paid based on payments[]. Additionally, it explains the conditions for the include_open_bill parameter and notes that the tool returns a warning if the CREDIT_CARDS product is not enabled.

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. Description adds that it returns a structured error object ({ total:0, results:[], warning }) instead of throwing on 403, which is valuable 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?

Single paragraph that is reasonably concise for the information conveyed, though the listing of asset types and fields could be more structured (e.g., bulleted list). No unnecessary repetition.

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?

Describes return fields comprehensively and notes error handling. However, lacks output schema and parameter explanations, which are important for a complete understanding of the tool's usage.

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

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

Input schema has 4 parameters (item, page, type, page_size) with 0% schema description coverage. The description does not explain any parameter meanings or usage, missing an opportunity to guide agent parameter selection.

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 data for a connection, listing specific asset types (FIIs, stocks, ETFs, etc.). This distinguishes it from sibling tools like openfinance_list_accounts or openfinance_list_transactions.

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

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

Indicates when to use (for investment portfolio from broker/bank with INVESTMENTS enabled) and mentions handling of missing feature errors. However, does not explicitly state when not to use or provide alternative tools for non-investment data.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by detailing the returned fields (quantity, value, expenses, etc.) and bulk support, but does not mention authentication or error 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 compact with two paragraphs: first for purpose and field details, second for bulk support. It is front-loaded and efficient, though the field list could be slightly condensed.

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

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

The description provides good context (prerequisite tool, bulk support) and leverages annotations for safety. However, it lacks details on pagination defaults, error handling, and rate limits, which would enhance 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?

With 0% schema description coverage, the description must compensate. It explains investment_id and investment_ids but omits page and page_size parameters, leaving pagination behavior ambiguous.

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 an investment position, listing specific transaction types and fields. It distinguishes itself from sibling openfinance_list_investments by explicitly mentioning use 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 provides clear usage context: use after openfinance_list_investments and supports bulk with investment_ids. However, it does not explicitly state when not to use or alternative tools.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description adds that queries are sequential with rate-limit spacing and returns per-connection results and errors. Provides useful behavioral context.

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

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

Two sentences, no fluff, front-loaded with purpose. 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 one parameter, no output schema, and simple use case, the description covers purpose, parameter semantics, usage guidance, and behavioral details. No gaps remain.

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

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

The input schema has 0% coverage for parameter description. The description fully explains that 'items' are connection selectors (item_id, connector_id, or connector_name) and omitting fetches all. Compensates entirely for missing schema description.

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 it lists loan contracts per bank connection, referencing the specific API endpoint. It distinguishes from sibling tools by clarifying the per-connection listing behavior and the use of items parameter.

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 explains when to pass items (for specific connections) and when to omit (list all). Also describes sequential querying with rate-limit spacing. Does not explicitly exclude alternative tools, 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?

Adds significant behavioral details beyond annotations: describes pending/posted variance, error return structure, max 500/page, search aggregation limits, and bulk support. No contradiction with readOnlyHint and idempotentHint.

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?

Long but well-structured, with clear sections per topic. Front-loaded main purpose. Every sentence adds value, though could be slightly more concise without losing information.

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

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

Covers almost all necessary context: account type differentiation, filter usage, pagination and truncation, error handling, sibling tool references. Missing explicit return structure hint, but error return part is described. Overall fairly complete 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?

With 0% schema description coverage, the text thoroughly explains all parameters: from/to as ISO dates, pagination limits, search_queries semantics (case-insensitive substring, OR), account_ids for bulk. Compensates fully 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?

Clearly states it returns transactions for bank accounts (BANK or CREDIT type). Distinguishes from credit card bills tool by mentioning billId linking. Implicitly differentiates from investment transaction tools.

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

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

Provides explicit guidance: for CREDIT accounts, this is the only way to get itemized transactions; advises using openfinance_list_credit_card_bills for standardized totals. Details pending/posted behavior variance and error handling instructions. Recommends checking connection health when total=0.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds crucial behavioral details: scan caps at 5000 transactions per account and truncation flag, which are not in annotations. No contradiction.

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

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

Front-loaded with purpose but moderately lengthy. Contains redundant explanations (e.g., Portuguese terms like 'entradas e saídas'). Some sentences could be merged for brevity, but all content is relevant.

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 details the return structure: compact summary fields (total entradas/saídas, por_mes, top_despesas, by_account) and truncation behavior. Covers all parameter interactions and use cases adequately.

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

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

Schema coverage is 0%, so description must compensate. Explains all 6 parameters: ISO date format for 'from'/'to', targeting via 'item', enums for 'type' and 'granularity' with their effects. Implicitly mentions 'top_n' via 'top_despesas'/'top_recebimentos' but not explicitly described. Still adds significant value.

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 verb 'Consolidated cash-flow analysis' and resource 'whole bank CONNECTION over a period'. Distinguishes from sibling tools (e.g., openfinance_list_transactions, openfinance_list_accounts) by stating it resolves accounts internally, eliminating the need for separate account calls.

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 like 'análise anual/mensal', 'fluxo de caixa', and clarifies behavior when 'item' is omitted (analyze all banks). Notes when to use 'raw' granularity for itemized rows. Lacks explicit 'when not to use' but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: it returns a global indicator, degraded components, open incidents, and flags incidents affecting connected banks. It also clarifies that it checks provider health separately from connection status. 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 fairly long but each sentence adds value: it specifies purpose, usage context, return values, and contrast with sibling. It is front-loaded with the main action and then provides details. Could be slightly more concise, but it packs necessary information 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?

The tool has no output schema, so the description must explain return values. It does so thoroughly: 'Returns the global indicator (none/minor/major/critical), degraded components, open incidents, and — when you have banks connected — flags the incidents that affect YOUR connected banks in `your_banks_affected`.' This covers all expected outputs 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?

The tool has zero parameters, so the baseline is 4. The description does not need to elaborate on parameters. It focuses on what the tool does and returns, adding value beyond the empty schema.

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

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

The description clearly states the tool checks the live operational status of the Open Finance provider, distinguishing it from the sibling tool openfinance_get_item_status which checks connection status. It uses specific verbs ('checks') and resource ('provider status'), and explicitly separates provider health from connection health.

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: 'whenever data looks incomplete or stale even though a connection shows UPDATED (accounts/transactions/balances missing, a bank not returning everything)'. It also contrasts with the sibling tool, explaining that this reveals upstream outages or incidents, helping differentiate provider-side problems from connection issues.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description adds key behaviors: plan-based filtering (PF hides PJ), the behavior when keywords are empty (returns a hint), and that it returns a ready connect_url. 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, well-structured paragraph front-loads the purpose, uses examples, and every sentence adds value (behavior, required use case, return fields). No fluff.

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

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

Given no output schema, the description fully covers return fields (connector id, access, audience, connections, accounts, connect_url) and edge case behavior (empty keywords). Aligns with sibling tool context as a pre-connect search.

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 keywords as an array of strings (with examples) and include_accounts as triggering account inclusion. Adds meaning beyond the bare schema, though could be more precise about data types.

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 'Searches the available bank connectors by name' and enumerates the returned fields (connector id, access, audience, etc.), distinguishing it as a search tool from sibling tools like connect or list operations.

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

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

Explicitly says 'Call this BEFORE connecting to hand the user a one-click link to the right bank' and notes that keywords are required (without it returns a hint), providing clear when-to-use context, though it doesn't explicitly exclude 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?

Beyond annotations, discloses that it overrides automatic categorization, teaches Pluggy by creating a Category Rule for future similar transactions, and that per-item errors do not fail the batch. This is critical 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?

Efficient and front-loaded: starts with core action, then includes input, side effects, and output format. Every sentence adds value without redundancy.

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

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

Covers all necessary aspects: purpose, input format, source of IDs, behavioral side effects, and output shape. No gaps given the tool's 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?

Although schema coverage is 0%, the description compensates by explaining the sources of transaction_id and category_id, the array structure, and the side effect. It adds meaning beyond the raw schema.

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

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

Clearly states the tool corrects transaction categories, specifies it's a PATCH operation, and distinguishes from sibling list tools by focusing on mutation.

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 the agent to get transaction_id from list_transactions and category_id from list_categories, and advises using it to fix miscategorized transactions. Does not explicitly state when not to use 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 non-destructive and idempotent behavior. The description adds the requirement to include the conversation array but does not disclose other behavioral aspects like authentication needs or server response. It provides marginal additional value.

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

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

Two sentences that are front-loaded and concise. The first sentence effectively states the purpose. Could be slightly more structured but is efficient overall.

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-report tool with 3 parameters and no output schema, the description is adequate but lacks details like expected outcome or any confirmation. It is minimally complete but could be more informative.

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 mentions 'conversation array' for reproduction, adding meaning beyond raw schema, but doesn't explain 'context' or 'message' beyond their names. It partially compensates but is insufficient for the low coverage.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' This is specific and distinguishes it from siblings, which are all about OpenFinance or authentication.

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

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

The description advises to 'Include the conversation array with recent messages for reproduction,' providing clear guidance on what to include. While no explicit when-not-to-use is given, the sibling tools are unrelated, so usage context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, so the description adds the specific output (platform and adapter). No contradictions. It could mention caching or stability but not required for this simple tool.

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

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

Single sentence, perfectly concise, 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?

As a parameterless version tool, the description completely covers what the tool does. No output schema needed.

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

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

No parameters exist, so description adds no parameter info beyond schema. Baseline score of 4 is appropriate given 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?

The description clearly states it shows MCP platform and adapter versions, which is specific and unambiguous. No sibling tool does this, so it's well-differentiated.

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 it's for checking versions, and given the sibling tools are mostly finance and auth operations, the usage context is clear. However, it lacks explicit guidance on when not to use it.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description enhances transparency by specifying the exact data returned (installed MCPs, connection status, catalog counts), exceeding annotation scope.

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, no wasted words. Clearly front-loaded with the main purpose.

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

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

Despite lacking output schema, the description fully informs the agent of return contents. For a simple read-only tool with no params, this is 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?

No parameters exist. Schema coverage is 100%. Baseline for 0 params is 4. Description adds no param info, which 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 'Returns the current toolkit state: installed MCPs, their connection status, and how many catalog tools each exposes.' This specifies the verb (returns), resource (toolkit state), and detailed contents, distinguishing it from siblings like openfinance tools or authenticate.

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

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

The description implies use when wanting overall toolkit status, but provides no explicit guidance on when to avoid or which alternatives (e.g., show_version for just version) to consider. Lacks when-not or comparative context.

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