Itaú MCP

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

Annotations show idempotentHint=true, but description adds context: if called with no args, returns a login link; if called with token, it processes authentication. It also explains the permanent non-expiring connection via config file, which is beyond 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?

The description is informative but slightly long. However, every sentence adds value: it explains context, best practice, and usage. Front-loaded with the tool's purpose. Could be slightly trimmed 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?

No output schema exists, but description explains the expected behavior: returns a link when called without token, or processes login with token. For an authentication tool, this is complete and covers the essential 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?

Schema coverage is 0%, but description fully compensates by explaining that 'token' should be a JWT string and how it is used (for session-only login). It adds meaning beyond the schema's bare type definition.

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

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

The description clearly states the tool is for authenticating to MCP.AI for IDE agents. It specifies the two modes: permanent config-based or session-only, and explains what each does. It distinguishes the tool from siblings by focusing solely on 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?

Explicit guidance is provided on when to use each mode: best to add token to config for permanent connection, or paste token for session-only. It tells the agent to call with no args to get the link, or with token to log in. Siblings are diverse, so no conflict.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds context about return values in different states, but does not disclose additional behavioral traits beyond that.

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 unnecessary words, front-loaded with 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?

Given no parameters and no output schema, the description provides adequate context for using the tool. Could mention it's safe to call frequently, but annotations cover that.

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%. Description does not need to explain parameters.

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

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

Description clearly states the tool returns connection status and URLs, with specific behavior for two scenarios. Distinguishes from siblings like 'authenticate' which likely has a different purpose.

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?

Implies when to use (to check connection status) but does not explicitly state when not to use or provide alternatives among siblings.

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

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

The description richly discloses behavioral traits: invoke runs one-off without bloating the toolkit, install makes MCPs permanent, writes require owner/admin, missing credentials return a connect link, insufficient wallet returns a checkout link, and prompt links open without login. This far exceeds the sparse 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 dense paragraph, but it is front-loaded with the purpose and preserves high information density. It could be improved with bullets or section breaks, yet every sentence contributes meaningful guidance.

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 23-parameter tool with no output schema and 14 possible actions, the description covers the core flows, permissions, edge cases (connect link, checkout link), and the prompt-library subsystem. It is remarkably complete for a tool of this complexity.

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

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

With 0% schema description coverage, the description is the only source of parameter meaning. It explains key parameters like action, mcp_id, tool_id, arguments, and prompt_slug through action explanations, but many parameters (limit, immediate, tier_slug, conversation, request_name, report_context, cancel_reason) remain unexplained or only inferable.

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

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

The description clearly identifies the tool as the official mcp.ai marketplace, catalog, and execution layer. It enumerates distinct capabilities (search, describe, invoke, install, prompt library) and differentiates from sibling domain-specific tools like openfinance_* and 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 provides explicit usage guidance: the core flow (search → describe → invoke), when to prefer invoke over install, when install is appropriate, and how to handle credential/payment gaps. It also describes list_tools, subscribe/cancel, report_bug, request_mcp, and the prompt library, giving clear 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 beyond annotations: confirms data removal and return of re-connect URL. DestructiveHint already indicates mutation.

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 covering action, consequence, and return value. No redundant information.

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

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

Adequate for a simple destructive tool but missing parameter explanation. Lacks output schema details.

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 documentation for the 'item' parameter. Schema coverage is 0%, and description fails to explain what 'specific bank' means or how to obtain the 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?

Clear verb (revokes/deletes) and specific resource (bank connection). Distinguishes from sibling tools like listing or getting 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?

Implied usage: disconnect a bank. No explicit when-to-use or alternatives. Lacks prerequisites like checking item status first.

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 false, etc.), the description details synchronous wait up to 60s, polling behavior, return structure with status fields, and how authentication issues are handled. 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 comprehensive but slightly verbose. Each sentence adds value, and it is front-loaded with the main action. Minor redundancy could be trimmed without losing meaning.

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 thoroughly explains return values, error states (needs_action, timed_out), and suggests alternative tool usage. All aspects of the tool are covered.

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

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

Schema coverage is 0%, but the description fully explains both parameters: items (array of selectors, omit for all) and wait (boolean for fire-and-forget). Also documents the return object shape, adding significant value beyond the bare schema.

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

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

The description clearly states the tool forces a bank to re-sync connections and waits for completion. It specifies the resource (connections) and distinguishes itself from sibling tools like openfinance_get_item_status and disconnecting/reconnecting.

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 when to use (stale balance/transaction list), how to use (omit items for all, set wait false for fire-and-forget), and what to do on errors (reconnect_url, re-check with openfinance_get_item_status). Provides clear alternatives and 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?

Beyond the readOnly/idempotent annotations, the description discloses that the value is a snapshot anchored to the last upstream sync, not a live read, and clarifies the meaning of updateDateTime/updatedAt. It also details credit-account error conditions and the structured warning mechanism. However, the final sentence is truncated ('the row DEGRADES to ...'), leaving the exact behavior for 5xx and non-Open Finance cases unspecified, which prevents a 5.

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 core purpose and contains mostly useful behavioral details, but it is a long single paragraph and the final sentence is cut off mid-thought. Some phrasing is also redundant (e.g., 'NOT a to-the-second live read' reinforces the snapshot point). The truncation makes the structure feel incomplete.

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

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

Given there is no output schema, the description partially fills the gap by mentioning rows, updateDateTime/updatedAt, and structured warnings, but it does not describe the full response shape (e.g., balance field, currency, status). The truncated error-handling sentence also leaves a significant behavioral gap for upstream 5xx or non-Open Finance connectors. Overall it is adequate but not 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 0% schema description coverage, the description must compensate. It does state 'Pass account_ids as an array (1–50)', adding the array format and size limit that the schema itself does not mention. But it does not explain the format or source of account IDs, how to obtain them, or behavior for invalid entries, so it only partially compensates for the missing schema descriptions.

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

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

The description opens with a specific verb and resource: 'Returns the latest available balance per account id', and reinforces it with the endpoint URL. It also distinguishes the tool by focusing on balance data rather than transactions or account details, and names related siblings in context. This leaves no doubt about what the tool does.

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

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

The description explicitly tells the agent when to use the tool (latest balance per account) and when to switch to a complementary workflow: if the balance is stale or disagrees with transactions, run openfinance_force_sync and re-read. It also explains when credit accounts return structured warnings instead of errors and how to recover consent issues. This is concrete, actionable usage 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 and idempotentHint, but the description adds critical behavior: batch response format { results, errors } and the provider_incident block warning about unreliable data during provider outages. This goes beyond annotations.

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

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

Four sentences, all essential: purpose, parameter usage, response shape, and data reliability warning. No fluff, 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 retrieval tool with no output schema, the description covers the key aspects: what it returns, how to invoke it, the response format, and a critical caveat about provider incidents. Complete given the context.

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

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

Schema coverage is 0%, but the description compensates by detailing the array constraint (1-50 items) and the response shape, adding meaning beyond the bare schema 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 that the tool returns full account objects with extended creditData, specifying the HTTP endpoint and batch structure. It distinguishes itself from sibling tools like list_accounts by emphasizing detail per 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?

It explicitly instructs to pass account_ids as an array of 1-50 items, providing usage constraints. While it doesn't explicitly contrast with sibling tools, the batch shape and provider_incident warning guide appropriate use.

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

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

Annotation coverage is good (readOnly, idempotent, non-destructive), and the description adds usFe contexts that annotations cannot: the opt-in scan cost, the authoritative totalAmount, the reconciliation logic, the fact that Pluggy returns no paid/status field, and the warning that payments[] usually refers to the previous bill. These behavioral subtleties prevent misinvocation more effectively than annotations alone.

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 definition is long but every sentence earns its place: return fields, opt-in mechanism, basis semantics, authoritative totalAmount, batch shape, and common financial pitfalls. It is organized with in-line labels and warnings, and important usage restrictions are either front-loaded or highlighted with ALL-CAPS, aiding agent parsing.

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 having no output schema, the description enumerates the expected payload shapes, fields, batch shape, and possible transactions_basis values. It also gives the caller all necessary cross-tool references and caveats for correct credential invocation, making it complete for a complex credit-card bill 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 schema has 0% description coverage, so the description carries the burden. It adds clear semantics for bill_ids, account_id, and include_transactions, explaining why account_id is needed for opt-in transactions. The only gap is `transactions_detail`, which is not explicitly described; the enum values are inferable but not elaborated.

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 opens with a specific verb and resource: 'Returns bill-level detail for one or more credit card bills by id' and enumerates the key fields. It also distinguishes itself from openfinance_list_credit_card_bills and openfinance_list_transactions by naming those tools for discoveries and transaction fetch.

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 and granular: tells the agent to pass bill_ids as an array and discover ids via openfinance_list_credit_card_bills; tells when to prefer openfinance_list_clean_card_bills for payment status; tells when to fetch transactions via openfinance_list_transactions. It explains prerequisites, costs, and the `transactions_basis` caveats.

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 and idempotentHint. The description adds value by explaining the reconnect_url behavior (reopens widget without disconnecting or consuming a connection slot) and the return fields. No contradictions.

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

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

The description is concise, well-structured, and front-loads the main purpose. 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 no output schema, the description adequately explains return fields (status, executionStatus, connector metadata, reconnect_url) and bulk response shape. No missing critical information for expected 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?

Schema description coverage is 0%, so description must compensate. It explains 'item' (optional, single bank) and 'item_ids' (bulk), but does not clarify the difference between 'item' and 'item_id', leaving ambiguity.

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

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

The description clearly states it returns the current status of a bank connection, lists examples of status values, and explains the reconnect_url purpose. It distinguishes single vs. bulk calls and is specific about the resource and action.

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

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

Provides clear context: omit 'item' for all banks, pass 'item' for a single bank, and supports bulk via 'item_ids'. It does not explicitly exclude alternative tools but the usage pattern 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. Description adds batch shape `{ results, errors }` and validates loan_ids limits, providing useful context beyond annotations.

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

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

Description is detailed but necessary, front-loading the core functionality and listing key returned fields. Slightly long but 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?

No output schema, but description thoroughly details all major returned fields (interestRates, installments, CET, etc.), making the tool fully understandable for a GET detail 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?

Despite 0% schema coverage, description fully explains the sole parameter `loan_ids` as an array of strings with size 1-50, compensating 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 'Returns full loan contract detail by id (GET /loans/:loanId)' and enumerates specific fields (interestRates, charges, etc.), distinguishing it from sibling openfinance_list_loans which lists loans.

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

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

Explicitly guides to 'Use after openfinance_list_loans to deep-dive on a specific contract' and specifies array size limit (1-50) and batch response shape.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial behavioral context beyond those annotations: connector-dependent `balance` meaning, possible lag in `bankData` fields, `provider_incident` making values unreliable, and `identity_notice` affecting ownership/dedup semantics. No statement contradicts 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 long and dense, but nearly every sentence carries a distinct warning or piece of routing guidance. It is front-loaded with the core purpose and then groups related caveats. Some repetition occurs around openfinance_list_credit_card_bills, and formatting could be tightened with headers, but it remains appropriately detailed for a complex financial data 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 tool's complexity and the absence of an output schema, the description is remarkably complete. It explains return fields, the meaning of `bank` vs `name`, balance caveats, notices, bulk behavior, and how to reconcile stale data. An agent has enough context to invoke the tool correctly and interpret its results safely.

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 needed to compensate. It does explain the two key routing parameters: `item` for targeting one bank and `item_ids` for bulk execution. The `type` parameter is not explicitly described as a filter, though its enum values are visible in the schema, and `item_id` is left implicit. The main invocation logic is covered, but a complete explanation of every optional parameter is missing.

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 opens with a specific verb and resource: 'Returns accounts for a bank connection: BANK (checking/savings) and CREDIT (credit card)'. It clearly enumerates the returned fields and distinguishes itself from related tools like openfinance_list_credit_card_bills by noting what this tool does not provide. This is unambiguous and actionable.

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

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

The description explicitly explains when to omit `item` vs. pass it, when to use openfinance_list_credit_card_bills instead, when a force sync is needed, and how to handle `balance_notice`, `provider_incident`, and `identity_notice`. It gives direct routing guidance and names alternatives, so an agent knows exactly when to invoke this tool versus a sibling.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: caching for the session, single aggregated response with no batch ids, and details about fields' meanings. No contradiction with annotations.

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

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

Three sentences, no fluff, front-loaded with purpose, and each sentence adds essential information (purpose, field details, caching behavior). It is appropriately sized for a no-parameter 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 no parameters, no output schema, the description is complete. It explains the return value, caching, and relationship to an update tool, leaving 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 no parameters, so the description's job is to explain the output. It thoroughly describes each field (id, description, descriptionTranslated, parentId, parentDescription), adding meaning beyond the empty schema.

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

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

The description clearly states the tool returns Pluggy's transaction category taxonomy, explains each field, and mentions its use by a sibling tool 'openfinance_update_transaction_category'. It has a specific verb ('Returns') and resource ('Pluggy's transaction category taxonomy'), and is distinct from siblings that list transactions or accounts.

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

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

The description provides clear context by linking the 'id' field to the 'openfinance_update_transaction_category' tool, implying usage for looking up categories before updating. However, it does not explicitly state when not to use or mention alternatives, so it misses some 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing the behavior of reconnect_url (reopens widget in UPDATE mode) and add_connection_url, which 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 two sentences, front-loaded with the tool's 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 and no output schema, the description completely covers what the tool returns and the behavior of the URLs. It is fully self-contained and leaves no ambiguity.

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

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

The tool has no parameters (schema coverage 100% with empty schema). The description provides semantic meaning for the output fields, which is sufficient. Baseline is 4 for zero parameters.

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

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

The description clearly states the tool returns saved bank connections with specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes itself from sibling tools like openfinance_list_accounts or openfinance_list_transactions by focusing on connections and their URLs.

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 reconnect_url (re-authentication, LOGIN_ERROR, stale data) and notes it does not consume a connection slot or require disconnecting. However, it does not explicitly mention when to use this tool over alternatives like openfinance_get_item_status.

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 the annotations (readOnly, idempotent, non-destructive), the description discloses complex behaviors: how payments are assigned to bills based on cycle dates (not by direct matching), the derivation of payment_status with special cases for past-due unconfirmed, the open_bill availability depending on connector, and bill_grouping_reliability warnings. 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 verbose but well-structured: it starts with core return values, proceeds to important semantic notes about payment assignment, then optional features, connector asymmetry, warnings, and cross-references. Every sentence adds necessary context for safe tool usage, but the length could be slightly reduced without losing essential information.

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

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

Given the tool's complexity (derived fields, cross-bill payment logic, connector asymmetry), the description covers all necessary aspects including edge cases, warnings, and relationships with other tools. It provides enough detail for an agent to use the tool correctly, especially since there is no output schema. The description compensates fully for the lack 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?

The description adds significant meaning to the input schema parameters: it explains the account_id is required, that include_open_bill is opt-in with detailed effects and consequences, and that account_ids enable batched execution. However, it does not explicitly describe the page and page_size parameters for pagination, which are present in the schema but not detailed. Given the 0% schema description coverage, the description compensates well but not fully.

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

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

The description clearly states it returns closed credit card bills for CREDIT-type accounts, listing key fields. It distinguishes from siblings by explicitly referencing when to use openfinance_list_transactions for itemized purchases, and there is a sibling tool openfinance_get_credit_card_bill for a single bill. The verb 'Returns' and resource 'CLOSED credit card bills' are specific and unambiguous.

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

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

The description provides extensive when-to-use and when-not-to-use guidance: it advises using openfinance_list_transactions for itemized purchases, warns against summing transactions by billId, explains the derived payment_status and its limitations, details the opt-in open_bill feature and its connector asymmetry, and instructs to check the bank app for open bills. It also tells agents to cross-check the account echo when multiple banks are connected.

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, non-destructive), the description adds critical behavior: error handling (returns warning instead of throwing), data integrity checks with 'data_integrity_warning' and 'suspect_zeroed' flags, and explicit instruction to not treat suspect zeroed balances as real. This far exceeds annotation context.

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

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

The description is front-loaded with main purpose, then error handling, then data integrity caveats. It is detailed but efficient, with no redundant sentences. However, it could be slightly more concise by omitting some internal details like specific rate 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, the description covers return structure (fields like balance, amount, dueDate), error handling, and data integrity warnings. It provides enough context for an agent to use the tool effectively, though it could explain parameters more.

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%, yet the description does not explain any parameters (item, page, type, etc.). It mentions bulk support with item_ids but provides no details on how to use other parameters. The agent must infer meaning from names alone.

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 the investment portfolio for a connection, listing specific types (FIIs, stocks, ETFs, etc.) and includes data integrity features. It clearly distinguishes from sibling tools like openfinance_list_investment_transactions which handle transactions rather than holdings.

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

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

The description implies usage for retrieving portfolio holdings and mentions bulk support with item_ids, but it does not explicitly guide when to use this tool over alternatives (e.g., openfinance_list_investment_transactions). No exclusion criteria or context for sibling differentiation.

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

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

The description adds significant behavioral context beyond annotations: it details the returned data fields (e.g., agreedRate, expenses) and transaction types. Annotations already indicate read-only, idempotent, non-destructive behavior, and the description aligns with this. However, it does not mention pagination behavior (page/page_size parameters) or limits, which would improve transparency.

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

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

The description is very concise: two sentences in the first paragraph cover purpose and output fields, and a second paragraph covers bulk support. No unnecessary words; all information is directly relevant. Front-loaded with core action ('Returns the movement history').

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 good detail on return fields and transaction types. It mentions the prerequisite (list_investments) and bulk support. However, it omits pagination details, default values, or potential error states. For a read-only list tool with strong annotations, this is nearly complete but could be better.

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 partially compensates by explaining `investment_id` (use from list_investments) and `investment_ids` (bulk support). However, it does not explain `page` and `page_size` parameters, which remain ambiguous. The description adds value for required parameters but lacks full semantic 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 specifies exactly what the tool does: returns movement history for investment positions, listing transaction types (BUY/SELL/TAX/INTEREST/etc.) and fields (quantity, value, netAmount, etc.). It clearly distinguishes from sibling tools like `openfinance_list_transactions` by focusing on investment-specific transactions and explicitly mentions the prerequisite `openfinance_list_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?

The description provides explicit guidance on when to use the tool: after `openfinance_list_investments` to obtain the `investment_id`. It also mentions bulk support via `investment_ids` for batched execution, which informs usage. The context of sibling tools implicitly signals to use this instead of general transaction lists.

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 behavioral details beyond annotations: sequential querying with rate-limit spacing, and response format {results, errors} per connection. Annotations declare readOnlyHint=true, idempotentHint=true, which are consistent.

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 efficient sentences: first states purpose and HTTP method, second details parameter usage and default behavior. No redundant information.

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

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

For a simple list tool with one optional parameter, the description covers purpose, parameter semantics, behavior, and response format. It could mention that for a single loan, use the sibling openfinance_get_loan_detail, but completeness is high.

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 the 'items' parameter. The description fully compensates by explaining that items are connection selectors (item_id uuid, connector_id, or connector_name), one per connection, with explicit omission 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?

Description clearly states this tool lists loan contracts per bank connection, which is distinguishing from sibling list tools like openfinance_list_accounts. The verb 'list' and resource 'loans' are specific.

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

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

The description explains when to pass 'items' (for specific connections) and when to omit (for all linked banks), providing clear usage context. It does not explicitly compare to sibling tools like openfinance_get_loan_detail, but the guidance 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 readOnly, idempotent, and non-destructive behavior. The description goes far beyond annotations by disclosing auto-pagination versus manual pagination, truncation at 5000, the scheduled-row ordering trap, connector-specific PENDING/POSTED variance, sparse billId population, and graceful error responses. This is exactly the kind of behavioral nuance annotations cannot convey.

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 exceptionally helpful but far too long and repeats itself: the billId sparse/inconsistent warning appears twice, once in the general credit card section and once under the rich detail explanation. While it is front-loaded and logically sectioned, many paragraphs could be tightened without losing meaning.

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 and lack of an output schema, the description is extraordinarily complete. It covers pagination behavior, row ordering, scheduled transactions, billId semantics, rich versus raw details, account identity cross-checking, provider incidents, and even troubleshooting via openfinance_get_item_status when sync fails.

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 carries a heavy burden, and it mostly succeeds: it explains ISO date filters, search_queries matching semantics, pagination vs page_size behavior, and detail levels. The main gap is that account_ids (as opposed to account_id) is never explicitly described for multi-account usage, though the account echo discussion partially compensates.

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

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

The description opens with a clear verb, resource, and scope: 'Returns transactions for a bank account (BANK or CREDIT type).' It differentiates itself from related tools by noting it is the ONLY way to get itemized credit card transactions and by contrasting its purpose with openfinance_list_credit_card_bills and openfinance_list_accounts.

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

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

Usage guidance is thorough and prescriptive: it explicitly says when to use this tool, when NOT to use it, and names alternatives, e.g. 'use openfinance_list_credit_card_bills' for standardized open-bill totals and 'use openfinance_list_accounts' for closing/due dates. It also gives practical rules for pagination and for checking scheduled rows, so an agent can decide confidently.

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, destructiveHint), description adds critical behaviors: truncation at 5000/account with 'truncated:true' flag, provider_incident block warning of incomplete data, and details on output structure for different granularities. No contradiction with annotations.

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

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

The description is long but well-structured: starts with the primary benefit, then explains parameters, then special behaviors. Some redundancy exists (e.g., repeating 'you do NOT need to call'), but overall it efficiently conveys complex information. Slightly verbose but clear.

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

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

Given the complexity (9 parameters, no output schema), the description covers all necessary details: return structure (compact summary with por_mes, top_despesas, etc.), raw option, detail enrichment, bulk support, truncation, and provider incidents. It fully compensates for missing schema descriptions.

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 description coverage is 0%, the description thoroughly explains all parameters: item (connector_id/name/item_id), from/to (ISO dates), granularity (monthly vs raw), detail (compact/rich/raw), type (BANK/CREDIT), top_n, and item_ids. It also explains default values and their implications.

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 core purpose: 'Consolidated cash-flow analysis for a whole bank CONNECTION over a period, in ONE call.' It distinguishes itself by explicitly mentioning that it resolves accounts internally, negating the need to call openfinance_list_accounts first, which differentiates 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?

Provides extensive usage guidance: when to use (annual/monthly analysis, cash flow), when not to use (no need to call list_accounts first), how to target one bank vs all, and the effects of different granularity and detail settings. Also mentions bulk support with item_ids.

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, and destructiveHint=false, so the description's main value is in adding behavioral context. It details the return fields: global indicator, degraded components, open incidents, and a 'your_banks_affected' flag. 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 moderately long but well-structured: first sentence states the purpose, second explains usage guidance and what it reveals, third lists return values. Every sentence adds value, though the third 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?

Given no output schema, the description adequately explains the return values (global indicator, degraded components, open incidents, your_banks_affected). It is complete for an agent to understand what to expect and how to use the 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 zero parameters and 100% schema description coverage. With no parameters, a baseline of 4 is appropriate. The description does not need to add parameter info, and it correctly omits it.

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's public status page. It distinguishes itself from the sibling tool 'openfinance_get_item_status' by specifying that it checks provider health, not the user's own connection.

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

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

The description explicitly tells when to use the tool: when data looks incomplete or stale despite a connection showing UPDATED, and when accounts/transactions/balances are missing. It contrasts with 'openfinance_get_item_status' and explains that it reveals upstream outages or known incidents.

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 important behaviors beyond annotations, such as the caveat for non-Open-Finance connectors requiring manual reconnection, plan behavior (PF plan hides PJ banks), and the behavior when keywords are missing (returns a hint). The annotations already indicate read-only, idempotent, non-destructive, and the description complements without contradiction.

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

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

The description is well-structured, front-loading the core action and return values in the first sentence, then adding caveats and plan behavior in subsequent sentences. Every sentence adds value without redundancy or extraneous 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 absence of an output schema, the description comprehensively covers return values, edge cases (empty keywords, plan restrictions), and prerequisites. It provides complete guidance for the agent to correctly invoke the tool and interpret results.

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 by explaining the 'keywords' parameter (array of strings, required despite schema, with examples) and 'include_accounts' (boolean to include accounts). It adds semantic meaning and usage details beyond the schema's type-only definitions.

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

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

The description clearly states the tool's action: 'Searches the available bank connectors by name' and specifies the return fields (connector id, access, audience, linked connections, connect_url). It distinguishes itself from siblings like 'connect' by indicating it should be called before connecting.

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: 'Call this BEFORE connecting' and provides context for when not to use (keywords required, otherwise returns a hint). It implies no alternative search tool exists among siblings.

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

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

The description richly details behavior beyond annotations: it is a PATCH operation that overrides automatic categorization, creates a Category Rule affecting future transactions, and describes batch error handling with per-item errors not failing the whole batch. This adds significant context that annotations alone do not provide.

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

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

The description is fairly long but every sentence adds value: it starts with the core purpose, then input details, side effects, and output shape. It is well-structured and not overly verbose, though it could be slightly more concise.

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

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

The description covers the main aspects: how to call (input shape), what it does (override + teach), return shape, and error behavior. It lacks some operational details like rate limits or auth, but for a batch update tool with side effects, it is adequately 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 0% schema description coverage, the description compensates by explaining that transaction_id comes from list_transactions and category_id from list_categories, and that items is an array with required fields. This adds meaning beyond the raw schema, though it does not specify formats or constraints.

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

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

The description explicitly states the tool 'corrects the category of one or more transactions' and identifies the HTTP method PATCH. It distinguishes from sibling tools like list_transactions and list_categories by specifying the exact IDs needed from them, making the purpose clear and unique.

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

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

The description provides clear context for when to use the tool: 'fix miscategorized transactions and improve categorization accuracy'. It also explains the side effect of creating a Category Rule, which guides usage. However, it does not explicitly mention when not to use or list alternatives, though 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 indicate idempotent and non-destructive behavior, which the description does not contradict. The description adds the detail about requiring a conversation array for reproduction, but it does not explain other behavioral aspects like response format or side effects. It is adequate but not highly informative.

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

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

The description is extremely concise, two sentences that front-load the purpose and then provide a key usage detail. Every word earns its place with no redundancy or wasted text.

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

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

The tool is simple and has no output schema, so the description does not need to explain return values. However, it does not mention any prerequisites (e.g., authentication) or confirmation of submission. It covers the essential usage but misses some contextual details that could help an agent.

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

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

The schema has 0% description coverage, so the description must compensate. It explains the 'conversation' parameter ('include conversation array with recent messages') and implies the 'message' parameter as the report content, but it does not mention the 'context' parameter at all. This leaves significant gaps for a parameter set with three fields.

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: reporting bugs, missing features, or sending feedback. It is specific about the action (report) and the resource (bug/feedback), and it distinguishes well from the sibling tools which are mostly 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 advises including the conversation array for reproduction, which is a helpful usage hint. However, it does not explicitly state when to use this tool versus alternatives or when not to use it. Given the unique purpose among siblings, the guidance is still 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 that it shows specific version details (platform and adapter), which is consistent and 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?

One sentence, perfectly concise with no waste. Every word is meaningful.

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

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

For a simple version display tool with no parameters and clear annotations, the description fully covers what an agent needs to know.

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%). The description adds value by indicating the output contains platform and adapter versions, 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 it shows MCP platform and adapter versions, distinguishing it from sibling tools that handle authentication, finance operations, and other tasks.

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 for version checking, but does not explicitly state when to use or provide alternatives. However, given its simplicity, it is clear that it can be used at any time without side effects.

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, and idempotentHint=true, fully covering the safety profile. The description adds value by detailing the exact contents of the returned state, which is beyond what annotations provide. No contradictions found.

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 the current toolkit state') and then efficiently lists the returned data. Every clause earns its place with no redundancy.

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

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

This is a simple read-only informational tool with no parameters and no output schema. The description fully specifies what will be returned, leaving no ambiguity about the tool's function or result, so nothing additional is 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?

The tool has zero parameters, so the description carries no parameter burden. The baseline for 0 params is 4, and the description adds no unnecessary param information.

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

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

The description uses a specific verb ('Returns') and identifies a precise resource ('current toolkit state') with enumerated contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This clearly distinguishes it from sibling tools like show_version or openfinance_list_accounts.

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

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

The description clearly implies when to use this tool—whenever an agent needs an overview of installed MCPs, connection status, accounts, or tool counts. However, it does not explicitly mention alternatives or exclusions, so it stops short of full guidance.

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