Atacadão MCP

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

The description discloses that calling with no arguments returns a login link, and calling with token authenticates for the session. It mentions non-expiring vs session behavior. Annotations indicate idempotentHint=true and destructiveHint=false, which are consistent. The description adds value beyond annotations by explaining the two modes.

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 paragraph of three sentences. It front-loads the purpose and covers both usage modes efficiently without redundant information.

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

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

Given the simple authentication scenario and no output schema, the description provides all necessary information: purpose, two authentication methods, best practice, and how to call the tool. No additional details are 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?

With schema coverage at 0%, the description fully explains the optional 'token' parameter: providing it means the user has pasted a JWT for session login, while omitting it returns the login link. This adds complete meaning beyond the schema's minimal definition.

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

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

The description clearly states the tool's purpose: authentication for IDE agents (Cursor, etc.). It specifies the resource (access token) and actions (log in, copy token, add to config or paste). It distinguishes from siblings by focusing on a specific use case not covered by other tools.

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

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

The description provides clear guidance on when to use each option: permanent token via config for persistent connection, or session-only by pasting token. It recommends the config approach as 'best'. However, it does not explicitly state when not to use this tool or compare to alternatives like 'connect'.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds value by detailing the different return states (authenticated vs. missing credentials). This provides context beyond the annotations without contradicting them.

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, perfectly concise with no wasted words. Every sentence adds value by describing behavior and return values.

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 effectively covers the return values in two key states. It could mention error handling or partial connections, but for a simple status check tool, it is sufficiently complete.

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

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

There are no parameters (100% schema coverage), so the description need not add parameter info. Baseline score of 4 is appropriate.

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

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

The description clearly states it 'returns connection status and URLs', using specific verb 'returns' and resource 'connection status and URLs'. It distinguishes from sibling 'authenticate' by focusing on status checking rather than performing authentication, with explicit examples of return values.

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 the tool by describing two scenarios: when all providers are connected and when credentials are missing. It implies use for status checking, but does not explicitly state when not to use it or mention alternatives like 'authenticate'.

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

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

Description adds significant behavioral context beyond annotations: invoke runs one-off without permanent addition, returns connect/checkout links for missing credentials or payment, and documents authorization requirements for writes. Annotations only indicate non-read-only and open-world, but description enriches with specific workflows and side effects.

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

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

Description is dense and contains essential information but could be more structured (e.g., bullet points for actions). It is front-loaded with purpose but the length (300+ words) reduces clarity. Every sentence adds value, but formatting could improve scannability.

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 13 parameters and no output schema, the description covers the main workflow and key behaviors (invoke flow, auth links) but lacks details on return values for successful calls, error handling, and parameter format (e.g., arguments JSON structure). Incomplete for a complex tool.

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

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

Schema coverage is 0%, but description partially compensates by explaining the action enum and the general flow. However, many parameters (like arguments, message, limit) lack detailed semantics or format guidance, leaving gaps for the agent.

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

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

Description clearly states it is the official mcp.ai marketplace for discovering and running MCPs/tools. It distinguishes from sibling tools by positioning itself as the first tool to use for capability discovery, and outlines the core actions (search, describe, invoke, install).

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

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

Provides explicit guidance: use this tool FIRST for any capability request; outlines core flow with actions; differentiates when to use invoke vs install; notes that writes require workspace owner/admin. Contrasts with external registry and sibling tools like openfinance 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 provide destructiveHint=true, but the description adds specific behavioral context: it revokes consent, deletes data, and makes data unavailable. It also notes that an add_connection_url is returned for reconnection, which goes beyond the annotation hints.

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

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

The description is two sentences with no fluff. The first sentence states the primary action, and the second covers consequences and return value. It is well-structured and front-loaded.

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

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

For a simple destructive tool with one parameter and no output schema, the description covers the action, consequence, and return value adequately. However, the lack of parameter explanation is a notable gap that reduces 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 one required parameter 'item' with no description, and schema description coverage is 0%. The tool description does not explain what 'item' represents (e.g., bank identifier or connection ID), leaving the agent without essential usage guidance for the parameter.

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

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

The description clearly states the tool revokes Open Finance consent and deletes connection data for a specific bank, using specific verbs ('Revokes', 'deletes') and resource ('bank'). It distinguishes from sibling tools like openfinance_list_connections by explicitly focusing on disconnection and consent revocation.

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 (when disconnecting a bank) and mentions a return URL for reconnection, but does not explicitly state when not to use or compare to alternatives. The context is clear without 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 are present but minimal. The description adds substantial behavioral context: it waits up to ~60s, polls until done, returns specific status fields (status, executionStatus, lastUpdatedAt, synced), and explains outcomes like needs_action and timed_out. No contradiction with annotations.

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

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

The description is thorough but slightly verbose. It front-loads the primary action and includes all necessary details. A minor reduction in length could improve conciseness 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?

Despite lacking an output schema, the description fully explains the return structure ({ results, errors } with detailed fields). It covers parameters, behavior, error states, and recommended follow-up actions, making the tool fully actionable.

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

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

Schema coverage is 0%, so description carries full burden. It explains items parameter as 'array of selectors (item_id, connector_id, or connector_name)' and that omitting it syncs all. It also explains wait parameter effect (blocking vs fire-and-forget) and default 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 verb ('Forces'), resource ('the bank to re-sync one or more connections'), and scope ('NOW and WAITS for it to finish'). It distinguishes from sibling tools like openfinance_get_item_status by explaining the wait-and-poll behavior.

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 ('when a balance or transaction list looks stale'), what it does differently ('pulls fresh data WITHOUT disconnecting/reconnecting'), and provides alternatives (e.g., setting wait:false for fire-and-forget, or using openfinance_get_item_status for re-check after timeout).

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

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

Annotations (readOnlyHint, idempotentHint) indicate safety; description adds real-time nature, error handling for credit accounts (BALANCE_FETCH_ERROR), and response shape, providing 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?

Three sentences with front-loaded purpose, no wasted words.

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

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

Covers purpose, parameter constraints, error behavior, and response structure; simple tool with no complex output schema, so nearly 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 coverage is 0%, but description adds the constraint 'array (1–50)', which compensates and clarifies usage beyond schema 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?

Description clearly states it returns real-time balance per account id, specifies endpoint, and distinguishes from sibling tools like openfinance_list_accounts by focusing on balance retrieval.

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

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

Implied usage (balance retrieval for accounts), but lacks explicit when-to-use guidance or alternatives among 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, idempotentHint, destructiveHint. The description adds value by specifying batch shape { results, errors }, array size limit 1-50, and inclusion of creditData, extending beyond the 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, no wasted words. First sentence states purpose and endpoint, second gives usage detail and return format. Perfectly front-loaded.

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

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

No output schema, but description mentions batch shape and extended creditData, which gives adequate context. Could optionally describe error structure or fields, but not essential for a detail retrieval tool.

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

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

Schema has no parameter descriptions (0% coverage). The description adds crucial semantic info: account_ids must be an array of 1-50 items, and explains the batch response shape. This compensates well for the schema gap.

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

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

The description clearly states the tool returns full account objects with extended creditData per ID, distinguishing it from sibling tools like openfinance_list_accounts and openfinance_get_account_balance which have narrower scopes.

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?

Usage is implied: use when needing detailed account info for specific IDs, but no explicit when-to-use or comparison with alternatives like list_accounts or get_account_balance is provided.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds crucial behavioral details: Pluggy does not return a paid/status field, payments[] may be from previous billing cycle, batch shape {results, errors}, and the correct method to derive payment status. No contradictions.

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

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

The description is dense and informative, with every sentence adding value. It is slightly long but remains efficient. Could be tightened by removing the parenthetical about GET /bills/:id, but overall well-structured.

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

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

Given the complexity of Brazilian Open Finance and the lack of output schema, the description covers return shape (batch {results, errors}), what fields are included, what is omitted, and cross-references sibling tools. It is complete for an agent to use correctly.

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

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

The only parameter (bill_ids) has 0% schema coverage, so description must compensate. It explains that bill_ids should be an array and that it expects IDs discovered from openfinance_list_credit_card_bills. This adds meaning beyond the schema, but could be slightly more explicit about the array 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 explicitly states it returns bill-level detail (financeCharges, payments[]) by ID, and clearly distinguishes that it does NOT return individual transactions, directing to openfinance_list_transactions for that purpose. This provides a specific verb+resource+scope.

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 itemized transactions use openfinance_list_transactions. Also warns about payments[] not indicating paid status and suggests alternative tool to check payment status. This is comprehensive.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only operation. The description adds behavioral context by explaining the return format for single vs. all banks, and lists example statuses, enhancing transparency beyond the annotations.

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

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

The description consists of two concise sentences. The first sentence states the primary purpose and examples of returned statuses. The second sentence explains parameter usage. Every word contributes value, with no unnecessary repetition or 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 the tool's simplicity (one parameter, no output schema, but with annotations), the description covers the return structure for both use cases and mentions included data (status, executionStatus, connector metadata). It does not list all possible status values or error responses, but is otherwise sufficient for a read-only status 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 input schema has one optional parameter 'item' with 0% description coverage. The description fully compensates by explaining that omitting 'item' returns status for all banks (with 'count' and 'items') and passing 'item' returns status for a single bank. This adds essential meaning to the parameter.

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

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

The description clearly states that the tool returns the current status of a bank connection with specific statuses (UPDATED, UPDATING, LOGIN_ERROR) and additional metadata. It distinguishes between returning status for a single bank or all linked banks, making the purpose specific and differentiating 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 clear guidance on when to omit or pass the 'item' parameter to get either all banks' statuses or a single bank's status. It implicitly differentiates from alternative tools (e.g., listing connections), but does not explicitly state when not to use this tool or name 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 and idempotentHint=true. The description adds behavioral details: response structure changes with 'item', field meanings, and credit balance interpretation. It does not contradict annotations and provides useful context beyond them.

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

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

The description is lengthy but well-structured and front-loaded. Every sentence adds necessary information. Could be slightly more concise, but the detail is justified given the complexity of the tool.

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

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

Despite no output schema, the description fully explains the return fields (balance, number, type, bank, etc.), behavior with and without 'item', meanings of fields, and warns about credit balance. It also references a related tool. Complete for a list tool.

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

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

Input schema has no parameter descriptions (0% coverage). The description fully explains both parameters: 'item' (optional, targets single bank or omits for all) and 'type' (enum BANK/CREDIT). It describes the effect of each parameter on the response, adding significant 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 it returns accounts for bank connections, distinguishing between BANK and CREDIT types, and lists fields like balance, number, type, etc. It explains the meaning of 'name' vs 'bank', making the tool's purpose unambiguous and differentiating 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?

Explicitly explains when to omit 'item' (to list across all banks) vs. pass 'item' (single bank). Warns about credit balance being connector-dependent and recommends using openfinance_list_credit_card_bills for standardized amounts. Provides clear context for when to use this tool 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?

Adds value beyond annotations by disclosing caching behavior ('cached for the adapter session') and response structure (single aggregated response, no batch ids). Describes all fields.

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 purpose, includes essential details without fluff. 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?

Given no parameters, no output schema, and annotations covering safety, the description is sufficiently complete for a simple retrieval 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%, so baseline 3 applies. No additional parameter information 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?

Clearly states it returns the transaction category taxonomy, specifying the verb 'Returns' and the resource. Distinguishes from siblings by linking to openfinance_update_transaction_category.

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?

Implicitly suggests usage for category lookup before updating, but lacks explicit when-to-use or when-not-to-use instructions. Alternatives not discussed, but no conflicting 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 provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing a safe, read-only behavior. The description adds context by specifying the exact data returned (connector_id, item_id, bank name) and the presence of an add_connection_url, which is useful 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 a single, front-loaded sentence of 22 words that efficiently communicates the tool's purpose and return values. Every word is necessary, with no filler or redundancy.

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

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

Given no output schema, the description adequately explains the return content (connector_id, item_id, bank name, add_connection_url). However, it does not specify the response structure (e.g., array format, pagination), which would be helpful for an agent. Still, it is mostly complete for a simple list tool with no parameters.

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

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

There are no parameters, and schema coverage is 100%. The description does not need to explain parameters. The baseline for zero parameters is 4, as no additional parameter information is required.

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

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

The description explicitly states it 'Returns the saved bank connections' and lists the specific fields returned (connector_id, item_id, bank name, add_connection_url). This clearly distinguishes it from sibling tools like openfinance_list_accounts 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?

The description implies usage for listing existing connections, but does not explicitly state when to use this tool versus alternatives like connect or openfinance_disconnect_bank. No exclusions or prerequisites are mentioned.

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, idempotentHint, destructiveHint. Description adds critical context: no native paid/status field, payment semantics, derived payment_status, extra scan for open_bill, connector asymmetry. 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?

Long but well-structured with clear sections and important details. Front-loaded with core purpose. Every sentence adds value. Slightly lengthy but appropriate for 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?

No output schema, so description must explain return values. It does: lists fields like dueDate, totalAmount, payments[], payment_status, open_bill, total_pending_debt, payment_status_legend. Also covers warning behavior and connector asymmetry. Fully complete for tool 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?

Input schema has 5 params with 0% description coverage. Description compensates by explaining account_id (required), account_ids (bulk), include_open_bill (opt-in, defaults to false). Does not explicitly describe page/page_size but their semantics are standard. Overall adds significant value beyond schema.

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

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

The description clearly states it returns closed credit card bills for a CREDIT-type account, listing specific fields. It distinguishes from sibling tools like openfinance_list_transactions (itemized purchases) and openfinance_get_credit_card_bill (single bill).

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 (get closed bills) and when not (for itemized purchases, use openfinance_list_transactions). Explains include_open_bill parameter and connector asymmetry. Provides clear guidance on payment status interpretation.

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, destructiveHint), description discloses that the tool returns a warning object instead of throwing on errors, providing valuable behavioral context for 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 a single concise paragraph that front-loads purpose and lists key details. Every sentence adds value, though a more structured format 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?

Good coverage of return format and error behavior, but completely misses parameter descriptions. With 4 parameters and no output schema, the description should at least hint at parameter roles to be fully complete.

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

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

Schema description coverage is 0%, and the description adds no meaning to parameters (item, page, type, page_size). It only lists example fields in results, leaving parameter semantics entirely undocumented.

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 investment portfolio for a connection, listing specific asset types and key fields. It distinguishes from siblings like openfinance_list_accounts and openfinance_list_transactions by focusing on investments.

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

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

Description implies usage (to get investment portfolio) but provides no explicit guidance on when to use this tool vs alternatives like openfinance_list_investment_transactions. It mentions error handling but no when/when-not 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 readOnlyHint, idempotentHint, destructiveHint are false. Description adds valuable detail about returned fields (quantity, value, netAmount, agreedRate, brokerageNumber, itemized expenses) without contradicting annotations. No mention of rate limits or pagination behavior, but overall adds 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 with essential information, front-loaded with purpose, followed by details and usage hint. Every sentence adds value; no redundancy or 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 lists key return fields (quantity, value, netAmount, expenses breakdown) and ties to sibling tool for obtaining investment_id. Lacks pagination details but covers core usage well.

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

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

Schema coverage is 0%, so description must compensate. It explains 'investment_id' (required) and 'investment_ids' for bulk, but misses 'page' and 'page_size' parameters. This leaves a gap in parameter understanding despite partial 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?

Description clearly states it returns movement history for a specific investment position, lists transaction types (BUY/SELL/TAX/etc.), and explicitly directs to use after openfinance_list_investments, distinguishing 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 clear context: use after obtaining investment_id from openfinance_list_investments. Mentions bulk support with investment_ids. Does not explicitly state when not to use or compare to alternatives, but the guidance is sufficient for typical 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 readOnlyHint=true, destructiveHint=false, idempotentHint=true. Description adds sequential execution, rate-limit spacing, and return format '{ results, errors }' per connection, which is beyond annotations.

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

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

Two concise sentences. First sentence states purpose and endpoint. Second sentence details usage. No wasted words.

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

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

For a tool with 1 optional parameter and no output schema, the description covers input semantics, behavior (sequential with rate limiting), and output structure. It is complete enough for an AI agent to use correctly.

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

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

Schema has 0% coverage for the only parameter 'items'. Description explains that it's an array of connection selectors (item_id uuid, connector_id, or connector_name) and that each entry corresponds to one connection. Fully 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?

Description clearly states the verb 'list' and resource 'loan contracts per bank connection', with the endpoint. It distinguishes from sibling list tools by specifying 'per bank connection'.

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

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

Explicitly explains when to pass 'items' for specific connections and when to omit for all connections. Mentions sequential querying with rate limiting, but does not explicitly contrast with 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?

The description discloses key behavioral traits: credit card transactions carry creditCardMetadata.billId linking to bills, pending vs posted varies per connector, search_queries aggregates up to 5000 transactions, error handling returns warning/error instead of throwing, and specific steps when total=0. This goes well beyond the annotations (readOnlyHint, idempotentHint) which already indicate safety.

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

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

The description is long but well-structured, with paragraphs for different aspects (core function, credit card behavior, search, error handling, bulk support). Every sentence adds value, though some redundancy could be trimmed (e.g., mention of ISO format and pagination in multiple places). Still, it's appropriately comprehensive for a complex tool.

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

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

Given the complexity (7 parameters, no output schema, multiple edge cases), the description is remarkably complete. It covers purpose, parameter usage, error behavior, sibling differentiation, and even provides troubleshooting steps. The agent has enough information to select and invoke the tool correctly in various scenarios.

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 schema description coverage at 0%, the description compensates fully by explaining each parameter: account_id (required), from/to (ISO format), page, page_size (max 500), account_ids (bulk), search_queries (case-insensitive substring match, OR semantics, up to 5000 aggregate). It adds crucial semantics missing from 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 transactions for BANK or CREDIT accounts, and distinguishes from siblings by explaining that for CREDIT accounts it is the only way to get itemized transactions, linking to openfinance_list_credit_card_bills. It also covers key features like date filters, pagination, keyword search, and bulk support.

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 states when to use this tool (for itemized transactions) and when to use openfinance_list_credit_card_bills instead (for standardized bill totals). It also provides guidance on handling cases where total=0, including checking connection health and performing a force sync. These are clear usage guidelines with alternatives.

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

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

Discloses important behaviors beyond annotations: scan caps at 5000/account with truncated:true flag, default granularity returns compact summary, and parameter effects (e.g., omitting item analyzes all banks). No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

The description is slightly long but well-structured: starts with purpose, then key differentiators, parameter details, use cases, and data cap. Each sentence adds value, though some details (e.g., listing compact summary fields) could be integrated more concisely. Still, it remains readable and efficient.

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

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

Given 6 parameters, no output schema, and moderate complexity, the description covers all necessary aspects: input formats, default behaviors, data truncation, return structure (compact vs raw, fields like por_mes, top_despesas), and use case examples. No gaps identified.

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 explains all 6 parameters: item accepts multiple identifiers, from/to are ISO dates, granularity defaults to monthly with 'compact summary' vs 'raw', type filters BANK or CREDIT, and top_n controls top expenses/revenues. Adds critical context missing from the schema.

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

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

The description clearly states the tool's purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It specifies that it resolves accounts internally and does not require prior calls to openfinance_list_accounts, distinguishing it from sibling tools like openfinance_list_transactions which likely require per-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?

Explicitly tells when to use: 'Use this for análise anual/mensal, fluxo de caixa, entradas e saídas, maiores gastos/recebimentos.' It also provides guidance on when to use granularity:'raw' and when to omit item for all banks, effectively guiding the agent on tool selection versus 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 provide readOnlyHint=true and destructiveHint=false. The description adds behavioral details: returns global indicator, degraded components, open incidents, and flags incidents affecting connected banks. No contradiction.

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

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

The description is a single paragraph that front-loads the purpose then details usage and returns. It is slightly lengthy but well-structured and packs necessary 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 zero-parameter tool with no output schema, the description fully explains what the tool returns and the use case. It is complete and leaves no gaps 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?

There are zero parameters, so the baseline is 4. The description does not need to add param info, and it doesn't.

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, distinguishing it from the connection-level tool openfinance_get_item_status. It specifies the resource (provider status page) and gives a concrete use case.

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

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

The description explicitly says when to use the tool: when data looks incomplete/stale despite a connection showing UPDATED. It also contrasts with openfinance_get_item_status, though it doesn't explicitly state when not to use it.

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

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

Annotations already indicate read-only and idempotent. The description adds behavioral details: returns a connect URL, honors user plan, requires keywords (returns hint otherwise), and includes accounts flag behavior. 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?

Description is multiple sentences but each sentence adds critical information. Front-loaded with main purpose, followed by details and usage instruction. No wasted words, appropriately sized.

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 covers what the tool returns, how it behaves with and without keywords, and plan filtering. While not exhaustive, it provides sufficient context for an AI agent to use the tool correctly.

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

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

With 0% schema coverage, the description fully explains both parameters: keywords with example usage and requirement, include_accounts with effect on results. Clearly adds value beyond the schema.

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

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

The description clearly states the tool searches bank connectors by name and returns detailed results including a connect URL. It distinguishes itself from sibling tools like 'openfinance_list_connections' by specifying that it only returns matches and never dumps the whole catalog.

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

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

Explicitly instructs to 'Call this BEFORE connecting to hand the user a one-click link', providing clear when-to-use guidance. However, it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations provide no behavioral details (readOnlyHint false, destructiveHint false, no idempotent). Description fully compensates by disclosing that the operation overrides automatic categorization, creates a Category Rule, and teaches Pluggy for future similar transactions. Also describes batch error handling ('per-item errors do not fail the whole batch').

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 front-loaded with purpose and includes all critical details. Slightly verbose but every sentence adds value. Could be slightly trimmed, but still efficient.

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

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

Given no output schema, description provides complete response shape ({ updated, results, errors }). It explains batch behavior, side effects, and source of IDs. No gaps remain for an agent to use the tool correctly.

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

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

Schema has 0% description coverage for parameters. Description adds complete semantic meaning: items is an array of objects, each with transaction_id (from list transactions) and category_id (from list categories). This is essential for correct invocation.

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

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

Description explicitly states 'Corrects the category of one or more transactions' with clear verb (corrects) and resource (transaction category). It also distinguishes itself by explaining the side effect (teaching Pluggy) which is unique among sibling tools, none of which modify categories.

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

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

Provides explicit guidance on when to use (fix miscategorized transactions) and how to obtain required IDs from openfinance_list_transactions and openfinance_list_categories. Also explains the consequence of creating a Category Rule, which helps the agent decide on 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 declare idempotentHint=true and destructiveHint=false. The description adds that the tool reports bugs but does not clarify the idempotency behavior or what happens after submission. It does not contradict annotations, but also does not significantly enhance behavioral understanding beyond them.

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 concise sentence that front-loads the purpose. No wasted words, and every part is necessary.

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 lack of output schema and incomplete parameter descriptions, the description provides the core idea but leaves out details on how to effectively use all parameters. It is minimally complete for a straightforward feedback tool.

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

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

With 0% schema description coverage, the description must compensate. It hints that the 'conversation' parameter should contain recent messages, but does not explain 'message' or 'context' parameters. This provides only partial guidance for the 3 parameters.

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

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

The description clearly states the tool is for reporting bugs, missing features, or sending feedback. The verb 'report' and resource 'bug/feedback' are specific, and the tool is clearly distinct from sibling tools that focus on financial operations.

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

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

The description provides clear context: include the conversation array with recent messages for reproduction. However, it does not explicitly state when not to use the tool or mention alternatives, but the usage is self-explanatory for a feedback 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, and destructiveHint=false. The description adds that it outputs platform and adapter versions, which goes beyond the annotations by specifying the content.

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

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

The description is a single sentence with no wasted words. It is perfectly concise and front-loaded.

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

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

Given the tool has zero parameters and no output schema, the description provides sufficient context. It could optionally detail the output structure, but the current description is adequate for a simple version query.

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

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

No parameters exist (schema coverage 100%), so there is nothing to explain. The description correctly omits parameter details, and the baseline for 0 params is 4.

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

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

The description clearly states the tool shows current MCP platform and adapter versions, which is a specific verb-resource pair. It distinguishes itself from sibling tools that perform operations on financial data 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 usage is self-evident: call when version info is needed. No explicit when-not or alternatives are given, but the simplicity and lack of parameters make such guidance unnecessary.

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

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

Annotations already provide readOnlyHint and idempotentHint. The description adds detail on what is returned (installed MCPs, connection status, catalog tool counts), going 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?

The description is a single sentence that front-loads the action ('Returns') and is free of extraneous words. Every part is 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, the description provides sufficient detail on return fields. However, it could be more specific about the structure (e.g., whether it's a list or object). Still adequate for a read-only info tool.

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

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

With zero parameters, the description does not need to explain parameter meanings. It focuses on the output, adding clarity to what the tool returns. Schema coverage is 100%, so baseline is not a concern.

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 toolkit state, including installed MCPs, connection status, and catalog tool counts. It uses a specific verb ('returns') and resource ('toolkit state'), and distinguishes from sibling tools like 'show_version' and '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?

The description implies usage for checking toolkit state but lacks explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though the context makes it clear this is for read-only status.

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