Banco do Nordeste do Brasil MCP

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

Describes two login methods and token handling beyond annotations. Explains permanent config vs session-only paste. Annotations already indicate idempotency and non-destructiveness, and description adds authentication-specific behavior.

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

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

Concise and well-structured: first sentence states purpose, then explains two usage scenarios. No unnecessary words; 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?

For a simple tool with one optional parameter and no output schema, the description is complete. Covers all relevant aspects: authentication flow, token options, and session persistence.

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

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

Schema has one parameter 'token' with no description. Description explains token is a JWT from browser and that omitting it returns a link. Adds essential meaning beyond schema for a tool with 0% schema coverage.

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

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

The description clearly states it is for authentication: logging in via browser, copying token, and either setting permanent config or pasting token for session. It is specific and distinguishes from sibling tools by focusing on token-based authentication.

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

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

Provides clear usage: call with no args to get login link, or with token to authenticate. Compares permanent vs session methods. However, lacks explicit guidance on when to use this vs siblings 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, idempotentHint, and destructiveHint, indicating safe behavior. The description adds value by detailing state-dependent behavior (e.g., returning connect_url when credentials are missing), which goes beyond what annotations provide. It does not contradict any 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 extremely concise, using two sentences to convey the primary purpose and key scenarios. Every sentence adds value, and the main action ('Returns connection status and URLs') is front-loaded. 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 covers two important states (all connected vs credentials missing). However, it does not mention intermediate states (e.g., partial connections) or error conditions. Still, for a simple status check, it is fairly complete.

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

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

The tool has zero parameters, and the schema coverage is 100% (no properties). According to the rubric, a baseline of 4 is appropriate when there are no parameters. The description does not need to add parameter semantics.

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

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

The description clearly states the tool 'Returns connection status and URLs.' It explains two distinct scenarios (all providers connected vs credentials missing), which provides a specific, actionable understanding of the tool's purpose. It distinguishes itself from siblings by focusing on status retrieval rather than authentication or other actions.

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

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

The description does not provide any guidance on when to use this tool versus its siblings, such as 'authenticate' or other connection-related tools. There is no mention of prerequisites, when not to use it, or alternatives. The usage context is only implied by the tool's functionality.

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 only indicate non-read-only and open-world, but the description adds critical behavioral details: invoke works without installation, returns connect/checkout links on auth/payment failures, writes require owner/admin, and the one-off install behind invoke. It also explains what actions do (subscribe/cancel, report_bug, etc.) with no contradiction to 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?

Despite its length, the description is well-structured and information-dense, starting with a high-level definition, then the core flow, then key caveats, then usage guidance, then the prompt library. Every sentence contributes meaningful operational detail 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?

For a tool with 23 parameters, 14 actions, and no output schema, the description covers the primary workflow, edge cases (credentials, wallet empty), permissions, and the prompt library. It omits details on some secondary parameters (e.g., immediate, tier_slug) and does not describe response formats, but the core selection and invocation logic 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?

With 0% schema description coverage, the description carries the burden. It clarifies the meaning of action enum values, tool_id, arguments contextually, and prompt-related parameters (prompt_vars, prompt_slug). However, some parameters like limit, query, immediate, tier_slug, conversation, and cancel_reason are not explicitly addressed, though their names are self-explanatory.

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 runner, with a specific core flow (search → describe → invoke). It distinguishes itself from sibling openfinance tools by focusing on cross-MCP discovery and invocation rather than a specific domain.

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 prescribes when to use invoke vs install ('prefer invoke for a single/occasional use', 'Use install only to make an MCP PERMANENT'), describes the search/describe→invoke flow, and covers alternatives like list_tools, report_bug, request_mcp, and the prompt library operations. This goes well beyond vague 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 indicate destructiveHint: true, and the description adds context: it revokes consent, deletes data, and returns a re-connection URL. This goes beyond the annotation flag and informs the agent of the data impact.

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 (two sentences) and front-loaded with the primary action. It could be slightly more structured but efficiently conveys the 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?

The description covers the main effect and return value but omits details about the parameter and response structure. For a simple tool with no output schema, this is adequate but leaves gaps for a first-time invoker.

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 single required parameter 'item' has no description in the schema or the tool description. The description implies it identifies the bank but does not specify format or examples, which is critical 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?

The description clearly states the tool revokes consent and deletes connection data for a specific bank, making the bank's data unavailable. It also mentions a return value, distinguishing it from other 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?

No guidance is provided on when to use this tool versus alternatives (e.g., openfinance_list_connections or openfinance_get_item_status). The description does not mention prerequisites or situations to avoid using 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?

Discloses that it performs a PATCH request, polls up to ~60s, returns final status fields, and handles errors like needs_action with reconnect_url. Since annotations only provide basic hints (readOnlyHint: false, destructiveHint: false), the description adds rich behavioral context.

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

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

The description is well-organized and front-loaded, but slightly verbose. Each sentence adds value, though some redundancy exists (e.g., explaining 'without disconnecting' twice). Still highly efficient for the complexity.

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

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

Despite no output schema, the description completely explains return object fields (status, executionStatus, lastUpdatedAt, synced, needs_action, reconnect_url, timed_out). It also provides system context like 'UPDATE mode' and slot consumption. Perfectly adequate for agent decision-making.

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

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

Schema has 0% description coverage, but the description fully explains both parameters: items as array of selectors (item_id, connector_id, etc.) with omission syncing all, and wait boolean with default true and fire-and-forget behavior. All parameter semantics are thoroughly defined.

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 forces a bank to re-sync connections and waits for completion. It specifies the action (force sync), resource (one or more connections), and distinguishes it from sibling tools like openfinance_get_item_status which is for checking after timeout.

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

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

Explicitly states when to use ('when a balance or transaction list looks stale'), what it avoids (reconnecting/disconnecting), and provides alternatives ('re-check with openfinance_get_item_status' for timeout, set wait:false for fire-and-forget).

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. The description adds significant context: error handling for CREDIT accounts (BALANCE_FETCH_ERROR with warning), degradation behavior when institution is unavailable (realtime: false, warning), and response shape. 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 paragraph that starts with the main purpose and then adds constraints and edge cases. All sentences add value, though it could be slightly more concise. Structure is clear 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 no output schema, the description includes the response shape. It covers input constraints, error handling, and degradation. It could mention if authentication is required, but that is likely handled by the authenticate sibling tool. Overall, well-rounded.

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 only defines account_ids as an array of strings with 0% coverage. The description adds meaningful constraint: 'Pass account_ids as an array (1–50)', which clarifies the allowed array size and format beyond the schema.

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

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

The description clearly states the tool's purpose: 'Returns real-time balance payload per account id'. It specifies the verb (returns), resource (balance payload), and scope (per account id). This distinguishes it from sibling tools like openfinance_list_accounts or openfinance_get_accounts_detail.

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, including handling of CREDIT accounts and temporary unavailability. It describes expected behaviors but does not explicitly state when not to use or mention alternative tools.

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

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

Beyond annotations (readOnlyHint, destructiveHint), the description discloses important behavior: the potential provider_incident block making credit limits and balances unreliable, and warns not to present those values as real. It also mentions the batch result shape.

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

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

Every sentence is necessary and well-structured, starting with the core purpose, then usage detail, then a crucial warning. No superfluous 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?

Given the tool has one parameter, no output schema, and annotations cover safety, the description covers return shape, non-deterministic behavior, and usage constraints. Minor omission: no mention of error handling or rate limits, but overall adequate.

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

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

The single parameter account_ids is described with a constraint (array of 1–50 items) beyond the schema. Schema description coverage is 0%, so the description adds value, though it could specify ID format or that they are 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 clearly states that the tool returns full account objects with extended creditData for given IDs. It uses specific verb and resource, and distinguishes from sibling tools like openfinance_list_accounts which presumably return a list without full details.

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

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

The description specifies that account_ids must be an array of size 1–50 and mentions batch shape and provider incident handling. However, it does not explicitly state when not to use this tool (e.g., instead of list accounts for basic info).

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?

Disclosures beyond annotations include that it does NOT return individual transactions, the batch shape { results, errors }, the note about Pluggy not returning paid status, and the nuanced behavior of payments[]. No contradiction with annotations.

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

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

Description is lengthy but every sentence adds value; front-loaded with core behavior, then details. Could be slightly more concise, but no superfluous content.

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

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

Comprehensive for a tool with no output schema: describes output fields, addresses edge cases (Nubank sparse billId), warns against using transactions to reconstruct total, and cross-references sibling tools. Fully adequate for agent decision-making.

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?

Schemas have 0% description coverage, but the description adds essential context: instructs to pass bill_ids as an array and to discover ids via openfinance_list_credit_card_bills first. 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?

Clearly states it returns bill-level detail for credit card bills by id, explicitly listing returned fields (financeCharges, payments) and distinguishing from transaction retrieval. The verb 'returns' and resource 'bill-level detail' 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?

Provides explicit when-to-use (after listing bills via openfinance_list_credit_card_bills), when-not-to-use (not for individual transactions), and alternatives (openfinance_list_transactions). Also advises on interpreting payments[] in Brazilian Open Finance 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?

The description adds behavioral details beyond the annotations: it discloses that the tool returns status, executionStatus, connector metadata, and reconnect_url, and that it supports bulk execution via item_ids. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are consistent. The description enriches the behavioral understanding without contradicting the annotations.

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

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

The description is concise, with two well-structured sentences. The first sentence covers the primary function and output details, and the second adds bulk support. Every word serves a purpose, and the information is front-loaded. No unnecessary content.

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

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

Given the complexity of three optional parameters and no output schema, the description sufficiently covers the main use cases: single item, all items, and bulk via item_ids. It lists key output fields and the reconnect_url behavior. However, it does not specify the format of the response (e.g., JSON structure) or edge cases like invalid item IDs, which might be expected for completeness. Still, for a read-only status tool, it provides adequate context.

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

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

The input schema has three parameters (item, item_id, item_ids) with 0% description coverage. The description mentions omitting `item` for all banks and passing `item` for a single bank, and mentions bulk support via item_ids. However, it does not explain the difference between `item` and `item_id`, nor does it specify the format or constraints (e.g., string length). The description provides some meaning but leaves ambiguity, and with no schema descriptions, it should have clarified each parameter more thoroughly.

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 that it returns the current status of a bank connection, including specific status values (UPDATED, UPDATING, LOGIN_ERROR, etc.), executionStatus, connector metadata, and reconnect_url. It distinguishes between single-item and all-items retrieval, and mentions bulk support with item_ids, making it clear and distinct from siblings like openfinance_list_connections which likely lists connections without status details.

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

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

The description provides clear usage context: when to omit `item` for all banks vs. pass it for a single bank, and explains the reconnect_url functionality for re-authentication without disconnecting. However, it does not explicitly state when not to use this tool or suggest alternatives (e.g., when a full list of connections is needed instead of status). Overall, the guidance is strong but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true; description adds batch shape '{ results, errors }' and confirms read-only nature.

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

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

Single efficient sentence front-loads purpose, then lists fields, then usage guidance. No fluff.

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

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

Simple tool with one parameter, no output schema; description covers all needed info: usage, batch shape, response structure.

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

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

Schema has 0% description coverage; description compensates by explaining 'Pass loan_ids as an array (1-50)', adding array bounds and purpose.

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 states 'Returns full loan contract detail by id', lists specific fields, and explicitly distinguishes from sibling (use after openfinance_list_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?

Clearly says 'Use after openfinance_list_loans to deep-dive on a specific contract' and gives parameter guidance (array of 1-50).

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 (readOnlyHint, idempotentHint, destructiveHint), the description discloses important behaviors: the 'name' field is the legal entity not the brand, CREDIT balance meaning is connector-dependent, presence of provider_incident and identity_notice blocks, and deduplication guidance for identity_notice. This adds significant value.

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

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

The description is lengthy but well-structured, starting with main purpose, then details, caveats, and bulk support. Each sentence adds value, though it could be slightly more concise. It is front-loaded with the core functionality.

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 fields, response structure (results array), and special cases (provider_incident, identity_notice). It also covers usage variants and references sibling tools. Very 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?

While schema description coverage is 0%, the description explains the usage of `item` and `item_ids` (bulk) in detail. However, the `type` parameter is only implied through the list of account types, not explicitly stated as a filter. The `item_id` singular parameter is not explained. Overall, good compensation but with a minor gap.

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

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

The description clearly states 'Returns accounts for a bank connection: BANK (checking/savings) and CREDIT (credit card) with balance, number, type, subtype, bankData, and creditData'. It identifies the specific resource (accounts) and distinguishes from sibling tools like openfinance_list_credit_card_bills.

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 when-to-use and when-not-to-use guidance: 'OMIT `item` to list accounts across ALL linked banks at once' vs 'Pass `item` to target a single bank'. It also directs users to openfinance_list_credit_card_bills for standardized bill amounts, and explains the 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds caching behavior and that it's a single aggregated response, enhancing transparency 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, focused and front-loaded. No extraneous information, but could be slightly more structured (e.g., bullet points for 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 input or output schema, the description is complete: explains purpose, return structure, caching, and links to sibling tool. All essentials covered for a simple listing 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 in input schema (0 params, 100% coverage). Description adds meaning by explaining the structure of each entry: id, description, descriptionTranslated, parentId, parentDescription. This compensates for lack of output schema.

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

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

Description clearly states it returns Pluggy's transaction category taxonomy, names the endpoint (GET /categories), and mentions caching. It distinguishes from siblings by noting 'Single aggregated response — no batch ids.'

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

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

Implies usage via mentioning 'categoryId used by openfinance_update_transaction_category', but lacks explicit when-to-use or alternatives among siblings. No when-not statements.

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: explains that reconnect_url reopens in UPDATE mode for existing connections, does not consume a slot, and describes the output fields. 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 a single paragraph with multiple sentences, but it is relatively concise and front-loaded with key information. Could be slightly more structured (e.g., separate lines) but overall 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 parameters and no output schema, the description explains the output fields and the usage of the URLs. It is fairly complete, though it does not mention pagination or limits, which is a minor gap.

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 and schema coverage is 100%. Baseline for 0 params is 4; the description does not need to add param info.

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 and lists specific fields (connector_id, item_id, bank name, reconnect_url, add_connection_url). It distinguishes its purpose from sibling tools by explaining the special 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, MFA, LOGIN_ERROR, stale data) and notes it does not consume a slot or require disconnecting. However, it does not explicitly state when not to use this tool or mention 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 extensive behavioral details: derived payment_status logic, open bill availability conditions, connector asymmetry, bill grouping reliability warnings, and the extra scan for open bill. Annotations already indicate read-only and idempotent; description adds context without contradiction.

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

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

The description is very long but well-structured, starting with the main output then diving into detailed semantics. While verbose, the complexity of the domain justifies the length; could be slightly more concise but retains 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?

Completely covers all aspects: return fields, derived fields, edge cases, connector differences, warnings, cross-references to other tools, and opt-in behavior. No gaps for an agent to misuse given the domain 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?

Despite 0% schema description coverage, the description explains each parameter (account_id, account_ids, include_open_bill, page, page_size) in detail, including the opt-in nature and batch feature. Adds meaning far beyond parameter names.

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 and derived data. It distinguishes from siblings like openfinance_get_credit_card_bill (singular) and openfinance_list_transactions (individual transactions).

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

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

Provides explicit guidance on when to use this tool (for closed bills, not open bills), when to use alternatives (openfinance_list_transactions for line items), and important caveats like connector asymmetry and opt-in for open bill. Includes detailed do's and don'ts.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description discloses cross-checking for mass zeroing, data_integrity_warning, and how to treat suspect rows. It adds value without contradicting annotations.

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

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

The description is verbose with two paragraphs and detailed data integrity rules. It front-loads the main purpose but could be more concise. Some sentences are long.

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 provides rich context: response structure, error handling, data integrity warnings, and bulk support. Lacks parameter documentation, but compensates with overall tool behavior.

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 only explains item_ids (bulk support) and indirectly the type parameter by listing types in text. Other parameters (item, page, page_size) are not described, leaving significant 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 investment portfolio for a connection, listing specific asset types (FIIs, stocks, etc.) and response fields. It distinguishes from sibling tools like openfinance_list_accounts or openfinance_list_investment_transactions by focusing on portfolio 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 explains it is for connections with INVESTMENTS product enabled, how errors are handled (returns structure instead of throwing), and provides detailed guidance on handling data integrity warnings. However, it does not explicitly contrast with sibling tools like openfinance_list_investment_transactions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it returns specific fields and transaction types, but does not elaborate on other behavioral aspects like pagination or authentication requirements.

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 plus a bulk support note. It front-loads the core purpose and is free of fluff.

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

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

Given no output schema, the description lists return fields and transaction types, and mentions the prerequisite relationship with openfinance_list_investments. It lacks details on pagination behavior and error conditions, but overall is fairly complete for a read-only list tool with good annotations.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions investment_id and investment_ids (bulk), adding meaning to those parameters. However, it does not describe page or page_size parameters, leaving some semantics unclear.

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

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

The description clearly states it returns movement history for an investment position, listing transaction types (BUY, SELL, etc.) and fields. It distinguishes from sibling tools like openfinance_list_investments by specifying that this is for details of a specific investment.

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: 'Use after openfinance_list_investments to get the investment_id.' It also mentions bulk support for batched execution, giving clear context. However, it does not explicitly state when not to use it or alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral traits: sequential querying with rate-limit spacing and return format `{ results, errors }` per connection. 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 (3 sentences), front-loaded with the core function, and well-structured. Every sentence adds value with no waste.

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

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

For a simple list tool with 1 parameter, no output schema, and strong annotations, the description is complete. It covers purpose, parameter semantics, behavior, and return format.

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

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

Schema has 0% description coverage, so the description compensates well. It explains `items` as an array of connection selectors (item_id uuid, connector_id, or connector_name) and describes behavior when omitted, adding meaning beyond the schema.

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

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

The description clearly states it lists loan contracts per bank connection, referencing the GET /loans endpoint. It distinguishes itself from siblings like openfinance_get_loan_detail by focusing on listing, not details, and specifying connection-level operation.

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

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

The description explicitly explains when to omit `items` (list all banks) and when to pass it (specific connections). It implies usage context but does not explicitly compare with sibling tools like openfinance_list_accounts.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds rich behavioral context: auto-pagination up to 5000 items, truncation, manual pagination behavior, upstream error handling (returns object with warning/error), detail level effects, response structure (account echo block), provider_incident block, cross-checking account identity. 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 long but well-structured into sections (CREDIT specifics, pagination, detail levels, etc.). Every sentence adds value given the tool complexity. Slightly verbose but not wasteful; a minor trim could improve readability 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 the tool's complexity (8 parameters, no output schema, many sibling tools), the description is thorough: covers purpose, usage guidelines, behavioral details, parameter semantics, error handling, response structure, cross-references to sibling tools (openfinance_list_credit_card_bills, openfinance_list_accounts, openfinance_get_item_status, openfinance_force_sync). No significant gaps.

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

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

Schema has 8 parameters with 0% description coverage. The description explains all parameters in detail: account_id (required), from/to (ISO YYYY-MM-DD), pagination parameters (page, page_size) with behavior when omitted, detail enum (compact/rich/raw) with effects, search_queries (array, substring match), account_ids (bulk). Adds meaning beyond schema (e.g., auto-pagination default, detail row enrichment).

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 accounts (BANK or CREDIT). It distinguishes from sibling tools like openfinance_list_credit_card_bills by specifying it is the only way to get itemized credit card transactions, and from openfinance_list_transactions_by_item by context. The verb 'returns' and resource 'transactions for a bank account' 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?

Provides explicit when-to-use guidance: for CREDIT accounts it is the only way to get itemized transactions; warns against using billId for summing; explains pending vs posted; advises using openfinance_list_credit_card_bills for standardized totals. Includes exclusions (do not reconstruct bill total by billId) and alternatives (openfinance_list_credit_card_bills, openfinance_list_accounts, openfinance_get_item_status). Also covers pagination modes and bulk support.

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), the description reveals important behaviors: internal fan-out of accounts, default compact summary, raw granularity option, capping at 5000/account with truncation flag, and potential provider_incident block affecting data completeness. It also notes that reconnecting does not fix provider issues. 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 lengthy (nearly 400 words) but well-structured and front-loaded with the core benefit. Each sentence adds value given the tool's complexity (9 parameters, multiple enums, warnings). Slightly verbose due to repetition (e.g., 'fluxo de caixa' phrase), but still appropriate for the information density.

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 thoroughly describes return values: total entradas/saídas/saldo_liquido, monthly evolution, top expenses, per-account breakdown, and for raw granularity, consolidated transactions with optional enrichment. It covers truncation and provider incidents. With 9 parameters and no output schema, this is a complete and informative description.

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 each parameter: 'item' accepts connector_id, connector_name, or item_id; omitting it analyzes all banks; 'from'/'to' are ISO dates; 'granularity' values and their output types; 'detail' options (compact, rich, raw) and what they enrich; 'type' filters BANK/CREDIT; and 'item_ids' for bulk. This adds essential meaning beyond the raw schema.

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

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

The description clearly states the tool provides consolidated cash-flow analysis for a bank connection over a period, resolving accounts internally and fanning out transactions. It distinguishes from siblings by explicitly noting that users do not need to call openfinance_list_accounts first. The verb 'list' and resource 'transactions_by_item' are well contextualized.

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 when-to-use guidance, such as using this tool instead of separate account listing calls, and specifying use cases like 'análise anual/mensal', 'fluxo de caixa'. It explains when to choose granularity ('monthly' vs 'raw') and detail ('rich' vs 'raw'), and warns about truncation at 5000/account and provider incidents. It also covers the option to omit 'item' for all linked banks.

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. The description adds significant behavioral context: returns global indicator (none/minor/major/critical), degraded components, open incidents, and a custom 'your_banks_affected' field. It also states it checks the provider's public status page, implying no side effects. 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 paragraph with three sentences, each adding value: purpose, usage guidance, output details. It is slightly longer than minimal but well-structured and efficient. 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 output schema and no parameters, the description completely covers the tool's behavior: what it returns (global indicator, degraded components, open incidents, your_banks_affected) and how the information is obtained (public status page). It also sets context for when to use it, making it self-contained for an agent.

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

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

The schema has 0 parameters, so the baseline is 4. The description implicitly confirms no parameters are needed by stating the tool checks provider status without requiring input. It does not need to add parameter-level semantics since none exist.

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 'Checks' and resource 'LIVE operational status of the Open Finance provider'. It distinguishes from the sibling 'openfinance_get_item_status' by explaining the provider vs connection status difference, and provides specific usage scenarios when data is incomplete or stale despite an updated 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 tells when to use: 'whenever data looks incomplete or stale even though a connection shows UPDATED'. It also clarifies what it helps differentiate: provider-side problem vs reconnection need. No when-not-to guidance is needed as it's a safe read-only check.

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

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

Annotations indicate readOnlyHint and idempotentHint, but the description adds context about caveats for credential connectors, plan-honoring behavior, and the hint return when keywords missing. This goes beyond annotations, though some behavioral aspects are implied.

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 provides rich detail. While slightly long, every sentence adds value. Could be trimmed slightly but remains effective.

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

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

Covers search behavior, plan rules, caveat handling, connect_url generation, and parameter requirements. With no output schema, it sufficiently describes what the tool returns and how to use it.

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

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

Despite 0% schema description coverage, the description explains keywords[] with examples and notes include_accounts triggers account returns. This adds significant meaning beyond the raw schema.

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

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

The description clearly states it searches bank connectors by name, returns specific fields (id, access, audience, connections, connect_url), and provides a one-click link. It differentiates from siblings like 'connect' and 'authenticate' by focusing on search and link generation.

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, warns about caveats for non-Open-Finance connectors, explains plan behavior (PF hides PJ banks), and notes that keywords[] is required else returns a hint. Provides clear when-to-use and when-not-to-use guidance.

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

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

Discloses important behavioral traits beyond annotations: that it overrides automatic categorization, teaches Pluggy by creating Category Rules, and per-item errors do not fail the whole batch. No contradiction with annotations (which are neutral).

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 efficient, with no redundancy. Information is well-organized: purpose, usage, side effects, response. Could be slightly more concise, 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?

Given the complexity (batch update with side effects) and no output schema, the description thoroughly covers response shape (updated, results with fields, errors) and error behavior. Leaves no critical gaps.

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

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

Despite 0% schema description coverage, the description fully explains the 'items' parameter: array of { transaction_id, category_id } with sources. This compensates completely, adding meaning beyond the raw schema.

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

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

The description clearly states the tool corrects transaction categories (PATCH /transactions/:id), with a specific verb ('corrects') and resource ('category of transactions'). It distinguishes itself from sibling tools like openfinance_list_transactions and openfinance_list_categories by focusing on updates.

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

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

Provides clear guidance on where to obtain transaction_id and category_id (from list tools), explains the side effect of creating Category Rules, and states the batch shape. Lacks explicit when-not-to-use guidance, but context is sufficient given 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 indicate idempotentHint=true and destructiveHint=false. The description adds behavioral context by requesting conversation data for reproduction, which is valuable beyond the annotations. However, it does not elaborate on other behavioral traits like response handling or potential 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?

The description is concise with two sentences. The first sentence states the purpose, and the second provides essential usage guidance. No unnecessary words 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 the tool's simplicity and the presence of annotations, the description covers the core purpose and key usage. However, it lacks full parameter documentation (especially for 'context' and 'message') and does not describe the return value or error handling, leaving some gaps.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It clarifies the 'conversation' parameter as an array of recent messages, but does not explain 'context' or 'message'. This partial compensation justifies a score of 3.

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

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

The description clearly states the tool's purpose: 'Report a bug, missing feature, or send feedback.' It uses a specific verb ('Report') and identifies multiple resources, effectively distinguishing it from sibling tools that are primarily related to Open Finance 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 explicit guidance on how to use the tool: 'Include the conversation array with recent messages for reproduction.' This gives clear context for usage. However, it does not explicitly exclude any scenarios or compare to alternative tools, but no sibling tool serves a similar purpose.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context that it shows platform and adapter versions, which is consistent and sufficient. 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, front-loaded sentence with no wasted words. It efficiently conveys the tool's 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 the tool's simplicity (no parameters, no output schema), the description is complete and sufficient for an AI agent to understand and invoke 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?

No parameters exist, which is indicated by 100% schema description coverage. The description does not need to add parameter details, so baseline 4 is appropriate.

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

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

The description clearly states the tool shows current MCP platform and adapter versions, with a specific verb and resource. It distinguishes from sibling tools that focus on authentication, connections, or other 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 implies usage when version information is needed, but does not provide explicit when-to-use or when-not-to-use guidance. Since the tool is simple and self-explanatory, this is acceptable but not explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds contextual detail about what the state includes but does not disclose potential latency, caching, or authorization limitations. It adds some value beyond annotations but not substantially.

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

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

A single, front-loaded sentence that immediately states the return value and lists the key components. No wasted words; every clause adds meaningful detail.

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?

With no parameters and no output schema, the description fully specifies what the tool returns (installed MCPs, connection status, accounts, catalog tool counts). This is complete for a simple state-inspection tool, especially given the strong annotations.

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

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

The tool has zero parameters, so there is nothing to explain. The schema coverage is 100% by definition, and the baseline for 0 params is 4. The description correctly focuses on the output rather than inputs.

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 a clear resource ('current toolkit state'), then enumerates the exact contents: installed MCPs, connection status, connected accounts, and catalog tool counts. This fully distinguishes it from siblings like show_version or openfinance_provider_status.

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

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

The description implies usage for checking overall toolkit status, but it does not explicitly state when to prefer this tool over alternatives (e.g., openfinance_provider_status for provider-specific status). No exclusions or alternative guidance are provided, so the guidance is implied rather than explicit.

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