Server Quality Checklist

Tool Scores

• check_consent_statusA
  3.6/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true, and the description aligns by saying 'checks', indicating a read-only operation. The description adds minimal behavioral context beyond the annotation, such as that the tool accesses shared dependencies via ctx, but does not disclose edge cases or what happens if consent is missing. This is adequate but not rich.

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

  Conciseness5/5

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

  The description is extremely concise, using a clear args/returns structure. Every sentence adds value: purpose is stated upfront, parameters are briefly defined, and return behavior is noted. No filler or repetition.

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

  Completeness4/5

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

  For a simple read-only status check with an output schema and readOnlyHint annotation, the description is largely complete. It covers the action, parameters, and return type. It lacks contextual details like typical usage flow or error scenarios, but these are not critical for this tool's simplicity.

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

  Parameters3/5

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

  With 0% schema description coverage, the description provides brief but useful semantics for parameters: subject_id is 'User's CPF or internal ID' and bank is 'Identifier of the participating bank'. However, it does not explain the enum values for bank or provide format examples, 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.

  Purpose5/5

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

  The description clearly states the tool checks the current status of a user's consent at a bank. The verb 'checks' and resource 'consent status' are specific, and it distinguishes from sibling tools like start_consent, revoke_consent, and check_payment_consent_status by focusing on the general consent status endpoint.

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

  Usage Guidelines2/5

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

  The description provides no explicit guidance on when to use this tool versus alternatives such as start_consent or revoke_consent. It does not mention prerequisites, typical scenarios, or exclusions, leaving the agent to infer usage from the name and purpose.

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

• revoke_consentA
  3.6/5.0
  Behavior4/5

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

  Annotations already specify destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds a concrete behavioral detail—'forgets the local token'—and highlights that the action occurs 'at a bank.' This provides context beyond the annotations without contradiction.

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

  Conciseness4/5

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

  The description is concise and well-organized with a clear one-line purpose followed by Args and Returns sections. The inclusion of 'ctx' is extraneous and the Returns line somewhat duplicates what an output schema would convey, but overall the text is efficient and scannable.

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

  Completeness3/5

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

  Given that this is a destructive operation, the description is adequate but not thorough. It covers the basic action and a key side effect, but omits prerequisites (e.g., must the consent exist), error handling behavior, or whether it revokes all consent types. The idempotentHint annotation helps, but more context would improve completeness.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the Args section in the description is essential. It explains subject_id as 'User's CPF or internal ID' and bank as 'Identifier of the participating bank,' which is helpful. However, it also lists 'ctx' as an argument not present in the input schema, causing ambiguity, and the enum values for bank are not described.

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

  Purpose5/5

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

  The description clearly states the tool 'Revokes a user's consent at a bank and forgets the local token.' This uses a specific verb ('revokes'), a resource ('consent'), and adds a distinctive side effect (forgetting the token), which separates it from sibling consent tools like start_consent, complete_consent, and check_consent_status.

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

  Usage Guidelines2/5

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

  The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as the existence of a consent to revoke, nor does it contrast with related tools like check_consent_status or start_payment_consent. Usage is only implied by the name and action.

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

• check_payment_consent_statusA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the return value ('current status') and the context of an 'exact payment consent journey,' but doesn't disclose additional behavioral details like error conditions or rate limits. This is acceptable given the simplicity of a read-only status check.

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

  Conciseness5/5

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

  The description is concise and well-structured with Args and Returns sections. It front-loads the purpose and then lists params and return value. No wasted words, and every sentence earns its place.

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

  Completeness4/5

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

  Given the tool's simplicity (3 simple params, no nested objects, read-only, output schema exists), the description is fairly complete. It explains what the tool does, the inputs, and the return value. However, it misses a note on how this relates to sibling tools (e.g., when to use payment consent status vs generic consent status), which is a minor completeness gap.

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

  Parameters4/5

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

  Schema description coverage is 0%, and the description compensates by explaining each parameter: subject_id as payer's CPF or internal ID, bank as participating bank identifier, consent_id as the exact payment consent journey to query. This provides meaningful semantics beyond the bare schema. The inclusion of ctx is extraneous but not harmful.

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

  Purpose5/5

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

  The description clearly states the tool 'Checks the current status of an exact payment consent journey,' which is a specific verb+resource. It distinguishes itself from the sibling check_consent_status by adding 'payment consent' and 'exact journey,' making the purpose unambiguous.

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

  Usage Guidelines2/5

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

  No guidance is given on when to use this tool versus the sibling check_consent_status or other payment consent tools. The description only implies it's for querying a specific consent journey but does not state exclusions or alternatives.

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

• list_credit_cardsA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, and description adds scope details (including available and total credit limit, Open Finance Brasil). However, it does not disclose any additional behavioral traits such as consent requirements, pagination, or rate limits; it also mentions a ctx arg not present in the schema.

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

  Conciseness4/5

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

  Description is fairly concise with an Args/Returns structure, but the Returns section redundantly restates the first sentence, and the ctx parameter adds an unnecessary line.

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

  Completeness3/5

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

  For a simple listing tool with readOnly annotation and output schema, the core purpose and parameters are covered. Missing is explicit guidance on when to choose this over sibling tools and any mention of consent/authorization context in Open Finance Brasil, leaving some ambiguity.

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

  Parameters4/5

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

  With 0% schema description coverage, the description compensates by clarifying subject_id as User's CPF and bank as Identifier of the participating bank, matching schema's enum. However, the inclusion of ctx, which is not in the input schema, introduces some noise.

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

  Purpose5/5

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

  Description uses specific verb 'Lists' with resource 'credit card accounts of a user at an institution participating in Open Finance Brasil', including limits. This clearly distinguishes it from sibling tools like get_credit_card_bills and list_accounts.

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

  Usage Guidelines3/5

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

  It implies usage context (user at participating bank, listing credit card accounts) but does not explicitly state when to use this tool versus alternatives such as get_credit_card_bills or list_accounts, nor mention any exclusions or prerequisites like consent.

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

• list_accountsA
  3.9/5.0
  Behavior3/5

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

  The readOnlyHint annotation already discloses the read-only nature. The description adds a bit of context ('participating in Open Finance Brasil' and 'all bank accounts'), but it does not disclose additional behaviors such as consent requirements, error conditions, pagination, or what happens if the user has no accounts. With annotations present, the bar is lower, yet the description adds limited behavioral nuance.

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

  Conciseness4/5

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

  The description is well-structured with a concise first line followed by Args and Returns sections. It is not overly long, though the Returns line somewhat repeats the first line. The extra 'ctx' parameter could be seen as unnecessary detail, but overall it is efficient and easy to parse.

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

  Completeness4/5

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

  For a read-only listing tool with an output schema and readOnlyHint annotation, the description covers the core purpose and parameters. It does not mention consent prerequisites or error handling, but these are not critical for a simple list operation. The tool's role among siblings is clear enough, though explicit usage guidance would improve completeness.

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

  Parameters4/5

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

  The input schema has zero description coverage, so the description carries the full burden. It provides useful meaning for the two schema parameters: subject_id ('User's CPF (digits only) or internal ID') and bank ('Identifier of the participating bank'). However, it also lists a 'ctx' parameter not present in the input schema, which could mislead agents into thinking it must be passed as an argument.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb ('Lists') and resource ('all bank accounts'), and includes account types (checking, savings, prepaid), distinguishing it from sibling tools like get_balance or list_transactions. The scope ('of a user at an institution participating in Open Finance Brasil') adds clarity.

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

  Usage Guidelines3/5

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

  The description implies when to use the tool (to retrieve all accounts for a user at a bank), but it does not explicitly mention alternatives or exclusions. It does not state 'use this instead of get_balance' or provide when-not-to-use guidance, which would help an agent choose appropriately among sibling tools.

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

• list_transactionsA
  3.9/5.0
  Behavior3/5

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

  The annotation readOnlyHint=true already indicates a safe read operation. The description adds useful behavioral context, such as the AI categorization feature requiring ANTHROPIC_API_KEY and the role of ctx in providing adapters and categorizer. However, it does not mention consent requirements, rate limits, pagination behavior beyond the parameters, or error handling for missing API keys or invalid date ranges.

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

  Conciseness4/5

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

  The description is front-loaded with a clear one-sentence summary, followed by a well-organized Args block. It is appropriately sized for a tool with 9 parameters, but the inclusion of 'ctx' as an argument (not present in the schema) adds unnecessary noise and could confuse the agent. The structure is otherwise tight and each parameter earns its place.

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

  Completeness3/5

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

  Given the complexity of Open Finance Brasil and the presence of sibling consent tools, the description is adequate but has gaps. It explains the main purpose, parameters, and AI categorization, but does not mention that consent must be established before listing transactions, nor does it address potential edge cases like very large date ranges, pagination limits, or timezone handling. The existence of an output schema covers return values, so that is not a gap.

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

  Parameters5/5

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

  With schema description coverage at 0%, the description fully compensates by providing a clear explanation for every schema parameter: subject_id ('User's CPF'), bank ('Identifier of the participating bank'), date_from/date_to ('Start date of the period'), credit_debit_type ('Restrict to credits or debits only'), page ('Page number (1-based)'), page_size ('Records per page (1-1000)'), and categorize ('If true, categorizes each transaction via AI'). It also documents the ctx argument, though this is not in the schema, and links account_id to list_accounts.

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

  Purpose5/5

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

  The description opens with 'Returns the bank statement of an account on Open Finance Brasil with date and type filters,' which clearly identifies the tool's specific verb, resource, and filtering capabilities. This also differentiates it from sibling tools such as get_balance, list_credit_cards, and initiate_pix by focusing on transaction history rather than balances, cards, or payments.

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

  Usage Guidelines3/5

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

  Usage guidance is implied rather than explicit. The description notes that 'account_id: Account ID returned by list_accounts,' suggesting a prerequisite dependency on list_accounts, but it does not explicitly state when to choose this tool over alternatives or mention exclusions. There is no direct comparison to sibling tools or guidance on scenarios where other lists (e.g., investments, credit cards) would be more appropriate.

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

• list_fundsA
  4.1/5.0
  Behavior4/5

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

  Beyond the readOnlyHint annotation, the description discloses return content (quota quantity/price, gross/net amount) and aggregate totals. It does not mention consent prerequisites or error behavior, but adds useful behavioral context.

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

  Conciseness5/5

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

  The description is well-structured with Args and Returns sections, provides all needed information in a concise manner, and front-loads the primary purpose.

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

  Completeness3/5

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

  The description covers the main purpose, parameters, and return values, but omits important contextual information such as consent requirements (siblings like start_consent exist) and any preconditions or error handling. Given the Open Finance context, this is a notable gap.

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

  Parameters4/5

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

  With 0% schema coverage, the description provides essential parameter explanations: subject_id is the user's CPF and bank is a participating bank with an enum. It compensates for the schema's lack of descriptions, though some details (CPF format) are missing.

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

  Purpose5/5

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

  The description uses a specific verb 'Lists' and clearly identifies the resource as 'a user's investment fund positions' via Open Finance Brasil, which distinguishes it from sibling tools like list_variable_incomes and list_treasure_titles.

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

  Usage Guidelines3/5

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

  The description implies usage for investment fund positions but does not explicitly state when to use this tool instead of list_investments or other list tools. No exclusions or alternative recommendations are provided.

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

• list_pix_keysA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, and the description consistently says 'Lists,' so there is no contradiction. The description adds the environment limitation ('Only available in environment='mock'') and the Open Finance context, which go beyond the annotation. It does not disclose error scenarios or consent requirements, but the output schema reduces the need for return-format details.

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

  Conciseness4/5

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

  The description is well-structured with a one-sentence purpose, a usage notice, and clearly labeled Args/Returns sections. It is front-loaded and free of fluff. Minor deductions for the 'see module docstring' note and the extraneous ctx parameter, but overall it is appropriately compact.

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

  Completeness4/5

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

  Given the tool's moderate complexity, an output schema, and readOnlyHint annotation, the description covers the essential elements: what the tool does, the mock-only restriction, and all parameters. It could strengthen completeness by mentioning that consent must exist for the bank account, especially since sibling consent tools are present, but the description is sufficient for selecting and invoking the tool in the intended environment.

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

  Parameters3/5

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

  With schema description coverage at 0%, the description must compensate. It does explain subject_id as 'User's CPF' and bank as 'Identifier of the participating bank,' but account_id is merely restated as 'Account ID,' adding little meaning. The inclusion of ctx as an argument is confusing because it is not in the input schema, diluting the clarity of the actual exposed parameters.

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

  Purpose5/5

  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: 'Lists the PIX keys (CPF, email, phone, EVP) registered to a bank account via Open Finance Brasil.' This clearly distinguishes it from sibling tools like initiate_pix or list_accounts by naming both the data type and the exact scope.

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

  Usage Guidelines4/5

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

  The description states 'Only available in environment='mock'' which is a clear usage constraint. It implies this tool is for mock testing rather than production, and the context signals show no competing PIX-key-listing sibling, so the primary use case is evident. It does not explicitly name alternatives, but the unique resource makes them unnecessary.

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

• get_credit_card_billsA
  4.3/5.0
  Behavior4/5

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

  Annotations include readOnlyHint=true, which the description respects ('Returns'). The description adds behavioral context beyond the annotation by specifying that it returns both open and past bills and lists relevant fields (total amount, minimum payment, due date). However, it does not mention potential pagination or consent requirements, which would be useful in an Open Finance context.

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

  Conciseness4/5

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

  The description is well-structured with purpose, args, and returns sections. It front-loads the core functionality and provides parameter explanations. Minor redundancy exists (the Returns section restates the opening line), and the extra ctx parameter adds noise, but overall it is efficient and organized.

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

  Completeness4/5

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

  Given the output schema exists, the description need not detail return values. It covers prerequisites and parameter semantics. Missing context includes consent requirements (common in Open Finance Brasil) and pagination behavior, but these are partially implied by sibling tools. Thus it is sufficiently complete for straightforward invocation.

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

  Parameters4/5

  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 explains all three schema parameters: subject_id as 'User's CPF', bank as 'Identifier of the participating bank', and credit_card_account_id as 'ID returned by list_credit_cards'. However, it also lists a 'ctx' argument not present in the input schema, which could confuse an agent about what to pass.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with a specific verb ('Returns'), a specific resource ('bills (open and past) of a credit card'), and context ('via Open Finance Brasil'). It also includes key fields returned (total amount, minimum payment, due date). This distinguishes it from sibling tools like list_credit_cards and list_transactions.

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

  Usage Guidelines4/5

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

  The description implies usage context by noting that credit_card_account_id is 'ID returned by list_credit_cards', which establishes a prerequisite and invocation order. However, it does not explicitly state when to use this tool over alternatives or provide exclusions, so it falls slightly 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.

• list_investmentsA
  4.3/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=true, so the description doesn't need to restate safety. It adds useful behavioral context by naming the data source (Open Finance Brasil Fase 4) and the returned fields (gross amount, net amount, contracted rate, indexer). It stops short of disclosing consent/auth prerequisites, but the read-only behavior is well covered.

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

  Conciseness5/5

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

  The description is front-loaded with a clear purpose, then structured into concise Args and Returns sections. Every sentence adds value, and it avoids redundantly restating the schema enum values.

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

  Completeness3/5

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

  The output schema covers return values, and annotations cover safety, so the description focuses on purpose and parameters effectively. However, it omits the critical prerequisite of establishing an Open Finance consent before listing investments, which is likely necessary given the sibling consent-management tools. It also doesn't clarify that ctx is framework-injected, not a user param.

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

  Parameters4/5

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

  Schema descriptions are missing (0% coverage), and the description compensates by defining subject_id as the user's CPF and bank as a participating bank. The bank enum is self-documenting. The mention of ctx is somewhat confusing because ctx is not in the schema, but it clarifies that it provides access to shared adapters rather than being a user-supplied parameter.

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

  Purpose5/5

  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: 'Lists a user's bank fixed-income investments' and enumerates exact product types (CDB, LCI, LCA, RDB). This clearly distinguishes it from sibling tools like list_funds, list_variable_incomes, and list_treasure_titles.

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

  Usage Guidelines4/5

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

  The fixed-income framing and product enumeration make it clear when to use this tool versus sibling asset-class listing tools. However, it does not explicitly mention that an Open Finance consent must be established first (via sibling consent tools), so exclusionary guidance is incomplete.

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

• list_treasure_titlesA
  4.3/5.0
  Behavior4/5

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

  The readOnlyHint annotation declares read-only behavior, and the description adds value by specifying the data source (Open Finance Brasil Fase 4) and the return contents (quantity, unit price, gross/net amount, aggregate totals). No contradictions detected.

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

  Conciseness4/5

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

  The description is well-structured with a clear summary and Args/Returns sections. It is not overly verbose, though the 'ctx' line is boilerplate. Overall, efficient and front-loaded.

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

  Completeness4/5

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

  The tool has an output schema, so return details are not strictly needed, but the description still provides them. It covers the purpose, parameters, and returns. With readOnlyHint annotation and a simple two-parameter schema, the description is complete enough for an agent to invoke correctly.

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

  Parameters4/5

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

  Schema coverage is 0%, but the description compensates by explaining subject_id as 'User's CPF' and bank as 'Participating bank', adding meaning beyond the schema's 'Subject Id' and 'Bank'. This is sufficient for the two parameters.

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

  Purpose5/5

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

  The description clearly states the tool lists a user's Tesouro Direto positions via Open Finance Brasil Fase 4, including specific fields. The verb 'lists' plus the specific resource (treasury bonds) distinguishes it from sibling tools like list_funds or list_variable_incomes.

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

  Usage Guidelines4/5

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

  While there is no explicit alternative-comparison, the description clearly scopes the tool to treasury bonds (Tesouro Direto), implying it should be used when the asset type is a treasury bond. This provides contextual guidance, though it does not explicitly name when not to use it.

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

• list_variable_incomesA
  4.3/5.0
  Behavior4/5

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

  With readOnlyHint already set, the description adds valuable context beyond the annotation: it discloses that only a gross amount is returned, explains why (real spec publishes no net amount), and clarifies that taxes/fees are reported per-transaction. This goes beyond the annotation's simple read-only signal, though it does not discuss pagination, consent, or error behavior, preventing 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.

  Conciseness5/5

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

  The description is well-structured with a clear opening sentence, a focused explanatory paragraph about net_amount, and labeled Args/Returns sections. Every sentence contributes meaning without redundancy, and the length is appropriate for the tool's complexity.

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

  Completeness5/5

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

  The description fully covers the tool's purpose, output fields, key behavioral nuance (gross vs. net), and return aggregate. With an output schema present and readOnlyHint annotation, the description adds the necessary spec context and differentiators, making the tool's behavior clear and complete for an agent.

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

  Parameters3/5

  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 briefly explains subject_id as 'User's CPF' and bank as 'Participating bank', adding some meaning, but the bank explanation is generic and the enum already lists valid values. The description also mentions a 'ctx' arg that is not in the schema, which could confuse. Overall, partial compensation but with gaps.

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

  Purpose5/5

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

  The description explicitly states it 'Lists a user's variable income asset positions (stocks, ETFs, and other exchange-traded assets)' and specifies the data included: quantity, closing price, and gross amount. It also distinguishes this tool from siblings (list_investments, list_funds, list_treasure_titles) by noting the absence of net_amount, making its 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.

  Usage Guidelines4/5

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

  The description provides clear when-not-to-use guidance by explicitly contrasting with siblings: 'unlike list_investments/list_funds/list_treasure_titles' and explaining the spec-based reason for the difference. It implies use cases (needing variable income positions) without explicitly stating 'use when...', so it earns a 4 rather than 5.

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

• complete_consentA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate this is a non-read-only, non-idempotent operation. The description adds valuable context that the callback URL's parameters are in the fragment (due to FAPI-BR), that it handles both authorization and denial, and that it returns the final consent status. This goes beyond the structured metadata without contradicting it.

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

  Conciseness4/5

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

  The description is well-organized, with a clear opening action, a key practical tip, an Args section, and a Returns section. It is slightly longer than strictly necessary (for example, 'ctx' is an MCP context parameter likely auto-injected and not user-specified), but each sentence contributes useful information.

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

  Completeness5/5

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

  For a single-parameter tool with a moderate complexity and an existing output schema, the description covers all essential aspects: the exact scenario, the critical URL fragment pitfall, parameter specification, and the return value. The tool's context is fully understandable without needing to inspect sibling tools or external docs.

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

  Parameters5/5

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

  The input schema only lists 'callback_url' with no description (0% coverage), so the description carries full responsibility. It precisely explains the parameter's meaning, emphasizes that the full URL (including the # fragment) is required, and clarifies that the user may have authorized or denied consent. This is comprehensive and actionable.

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

  Purpose5/5

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

  The description clearly states the tool's function with a specific verb ('Completes') and resource ('a consent flow'), and further specifies the exact trigger (URL the bank redirected the user to). This distinguishes it from sibling tools like start_consent, check_consent_status, and complete_payment_consent.

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

  Usage Guidelines4/5

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

  The description gives a clear when-to-use context: after the user finishes logging in and authorizing at the bank. It also provides an important implementation note about the URL fragment, which is effectively a usage guideline. However, it does not explicitly mention when not to use it or point to alternatives, so it earns a 4 rather than a 5.

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

• complete_payment_consentA
  4.5/5.0
  Behavior4/5

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

  Annotations indicate non-read-only and non-idempotent behavior. The description adds context by explaining that the tool handles both authorized and denied states and returns the final status, 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.

  Conciseness5/5

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

  The description is concise and well-structured, with a one-sentence summary followed by Args and Returns sections. It stays under 100 words and every sentence adds value, with no redundancy.

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

  Completeness4/5

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

  The description covers what the tool does, when to use it, and its return value, which is sufficient given the output schema exists and annotations are provided. It does not explicitly reference prerequisites or sibling tools, but the flow context makes them implied.

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

  Parameters5/5

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

  The input schema provides zero description for callback_url, but the description explains it thoroughly: 'The full URL the user's browser landed on after authorizing (or denying) the payment consent at the bank.' This fully compensates for the schema gap, and the ctx parameter is also documented.

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

  Purpose5/5

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

  The description clearly identifies the tool's purpose: completing a payment consent flow using the callback URL from the bank. It specifies the exact trigger (after authorization or denial) and the output (final consent status), distinguishing it from siblings like start_payment_consent and check_payment_consent_status.

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

  Usage Guidelines4/5

  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: after the user's browser lands on the callback URL from the bank. It does not explicitly mention alternatives or exclusions, but the wording implies this is the completion step in the payment consent flow.

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

• get_balanceA
  4.5/5.0
  Behavior4/5

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

  The readOnlyHint annotation already declares this as a safe read operation. The description adds context about the specific balance components (available, blocked, automatically invested) and that it returns the current balance, which enriches behavioral understanding without contradicting the annotation.

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

  Conciseness4/5

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

  The description is concise and well-structured with an opening sentence, Args list, and Returns section. It is front-loaded with the primary purpose. The Args/Returns format adds a bit of verbosity but remains efficient and scannable.

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

  Completeness5/5

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

  The tool is simple with three parameters and an output schema. The description covers purpose, parameters, and return value adequately. The mention of account_id linkage to list_accounts adds the necessary context for the interaction flow.

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

  Parameters5/5

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

  The schema provides no descriptions (0% coverage), so the description carries the full burden. It clearly explains each parameter: subject_id as CPF, bank as identifier, and account_id as returned by list_accounts, adding meaning beyond the raw schema.

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

  Purpose5/5

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

  The description clearly states the tool returns the available, blocked, and automatically invested balance of a specific bank account. It uses a specific verb ('Returns') and resource ('balance'), distinguishing it from sibling tools like list_accounts and list_transactions.

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

  Usage Guidelines4/5

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

  The description implies a workflow by noting that account_id is returned by list_accounts, which guides when to use this tool. However, it does not explicitly mention when not to use it or alternatives beyond that hint.

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

• start_payment_consentA
  4.6/5.0
  Behavior4/5

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

  Annotations only indicate readOnlyHint=false and idempotentHint=false. The description adds meaningful behavioral context: it creates a payment consent, builds a FAPI-BR compliant authorization URL, requires the user to open the URL and authorize, and notes that the URL is still returned for manual flow. This goes beyond the annotations to disclose the external side effects and dependencies.

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

  Conciseness5/5

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

  The description is well-structured: it starts with a clear summary, then explains the overall flow, then lists parameters in an organized Args block. Every sentence serves a purpose; the detailed flow explanation is justified by the tool's complexity, and the parameter list is compact yet informative. No redundancy or fluff.

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

  Completeness4/5

  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, multi-step flow), the description covers the essential context: what the tool does, how to use it in sequence, and the user interaction required. It briefly mentions return values ('consent ID and URL'). It doesn't detail error cases or security requirements, but for typical selection and invocation, the description is sufficient.

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

  Parameters4/5

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

  With only 13% schema description coverage, the description compensates by explaining key parameters. It clarifies subject_id ('Payer's CPF (digits only) or internal ID'), amount ('BRL amount serialized with exactly two decimal places'), and description ('max 140 chars'). It also explains the nuanced URL elicitation parameter. This adds practical meaning beyond the raw schema.

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

  Purpose5/5

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

  The description clearly states the tool's specific purpose: 'Starts the Open Finance Brasil Payments API consent flow for one specific PIX payment.' It distinguishes this from siblings like start_consent and complete_payment_consent by emphasizing it creates a consent for a specific payment and then builds the authorization URL.

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

  Usage Guidelines5/5

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

  The description provides explicit sequencing: 'Once redirected back, call complete_payment_consent with the resulting URL, then initiate_pix to actually create the payment.' It also explains when to use request_url_elicitation, giving clear context for when this tool is the appropriate choice.

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

• initiate_pixA
  4.7/5.0
  Behavior4/5

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

  Annotations already indicate idempotent and destructive hints, but the description adds rich context: it explains the role of idempotency_key in preventing duplicate charges, the requirement for an AUTHORISED consent, and the mock mode exception. This goes beyond the annotations, though it does not detail all side effects like account balance changes.

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

  Conciseness4/5

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

  The description is well-structured with an overview, prerequisite details, and a clear argument list. It is longer than strictly necessary but every sentence adds value; the arg descriptions are concise and the return note is useful. Slightly verbose but not wasteful.

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

  Completeness5/5

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

  For a tool with 9 parameters, an output schema, and complex prerequisites, the description is complete. It explains the consent flow, mock mode behavior, idempotency, and the meaning of each parameter, making the tool usable without external context.

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

  Parameters5/5

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

  Schema coverage is only 11%, but the description provides meaningful explanations for nearly every parameter (subject_id, bank, amount, creditor_key, creditor_key_type, debtor_account_id, idempotency_key, description, consent_id). It also clarifies the format for amount and the source for debtor_account_id, fully compensating for the sparse schema.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Initiates a PIX payment via Open Finance Brasil.' This specific verb+resource (initiate payment) distinguishes it from sibling tools like start_payment_consent, which handle the consent flow, not the actual payment.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance: it requires an AUTHORISED payment consent obtained via start_payment_consent + complete_payment_consent, and explicitly warns that a data-sharing consent alone is insufficient. It also clarifies behavior in mock mode, which is critical for correct usage.

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

• start_consentA
  5/5.0
  Behavior5/5

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

  The description discloses key behavioral traits: it creates a consent resource at the bank, builds a FAPI-BR compliant authorization URL, requires the user to authorize in a browser, and returns a consent ID and URL. It also explains the request_url_elicitation behavior. This goes well beyond the minimal annotations and gives the agent a clear picture of side effects and dependencies.

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

  Conciseness5/5

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

  The description is well-structured with a summary, Args section, and Returns note. It is longer than average but every part carries useful information, such as the scope list and the explicit payment-consent distinction. No filler or redundant content appears.

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

  Completeness5/5

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

  Given the complexity of a multi-step consent flow, the description provides a complete picture: how to invoke it, what the user must do, how to finish via complete_consent, and how it relates to payment consent. The presence of an output schema means detailed return types are not required in the description, and the high-level return description is sufficient.

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

  Parameters5/5

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

  Even though schema description coverage is 0%, the description thoroughly explains every schema parameter: subject_id (CPF or internal ID), bank (participating bank), scopes (with explicit examples and exclusion of payments), and request_url_elicitation (with behavior and fallback). This compensates fully for the lack of schema descriptions.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Starts the Open Finance Brasil consent flow for a user at a bank.' It specifies the concrete actions (creating a consent resource, building a PAR+JAR authorization URL) and distinguishes itself from payment consent by saying this is not for 'pix'/payments. This makes it easy to differentiate from sibling tools like start_payment_consent and complete_consent.

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

  Usage Guidelines5/5

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

  The description gives explicit usage guidance: it explains when to use the tool, what the user must do with the returned URL, and that the flow should be completed by calling complete_consent. It also explicitly warns that payment initiation uses a separate dedicated consent flow, steering the agent away from misuse.

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