Server Quality Checklist

Tool Scores

• calculate_mwrB
  3.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the transparency burden. It explains the computation method (bisection over signed cash flows), mentions synthetic initial/terminal NAV, and lists outputs including convergence diagnostics and warnings. This gives a good sense of behavior, though it does not explicitly state whether the operation is read-only or has no 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.

  Conciseness5/5

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

  The description is compact and front-loaded with the tool's identity and purpose. It packs computation method, prerequisites, and outputs into a short paragraph without unnecessary filler or repetition.

  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 what the tool calculates, how it computes, prerequisites, and return values. It is missing parameter format/usage details and does not provide explicit selection criteria versus calculate_twr or other sibling tools. This is adequate for basic understanding but not fully complete for confident invocation.

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

  Parameters1/5

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

  The input schema has two string parameters, period_to and period_from, with zero description coverage in the schema. The description does not explain the expected date format, whether the range is inclusive, or whether the parameters are optional/required. Since there is no schema description and no parameter explanation in the text, an agent cannot reliably construct valid inputs.

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

  Purpose4/5

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

  The description clearly defines the tool as computing money-weighted return (MWR/IRR) and explains its core purpose: reflecting the timing of cash flows. It also names the expected return fields, which makes the purpose concrete. However, it does not explicitly contrast with calculate_twr, so differentiation from that sibling is only implicit.

  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 gives a prerequisite ('Requires ≥ 2 XPerformance imports') and states the computation approach, which implies when the tool can be used. It does not explicitly say when to prefer this over calculate_twr or other portfolio analysis tools, so the guidance is not fully explicit.

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

• calculate_allocation_driftA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It states that the tool returns drift and suggestions, implying a read-only operation, but it does not explicitly mention side effects or confirm no modifications are made. This is adequate but not fully explicit.

  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, using two sentences to cover purpose, parameter details, and output. Every sentence adds value with 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?

  For a tool with no output schema, the description sufficiently describes the return (per-class drift in percentage points and BRL, plus BUY/SELL suggestions). It omits details about error handling or edge cases, but these are not critical for a basic understanding. The description is complete enough for an agent to invoke the tool 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?

  The description explains the only parameter, 'target_path', as an optional override for the default location. It also clarifies the 'tolerance_pp' field in the config file, adding semantic meaning. The description does not specify the default location, which is a minor gap.

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

  Purpose4/5

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

  The description clearly states the tool's core function: comparing current portfolio allocation to a target file and returning per-class drift with BUY/SELL suggestions. It is specific and easily distinguishable from sibling tools, though it could be slightly more explicit about the expected output format.

  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 provides guidance on optional parameters: 'target_path' to override the default and 'tolerance_pp' as a field in the target file to treat drifts within a band as 'ok'. However, it does not explicitly state when to prefer this tool over siblings like 'get_portfolio_summary' or 'suggest_buys', leaving some inference required.

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

• suggest_buysA
  3.7/5.0
  Behavior5/5

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

  The description discloses its internal behavior: it composes drift and screening, surfaces non-screenable classes in skipped_classes with a reason, and requires outbound_enabled. It also includes a disclaimer that output is educational, not investment advice. This provides good transparency.

  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 reasonably concise and well-structured. It starts with the main purpose, then elaborates on the process and output, and ends with a requirement and disclaimer. It is slightly redundant but generally efficient.

  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 provides a good overview of the tool's inputs, process, and output, including the skipped_classes behavior and the outbound_enabled requirement. However, it omits any explanation of the two parameters, which are the only inputs an agent would pass. This gap affects completeness.

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

  Parameters1/5

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

  The schema provides no descriptions for top_n and target_path (0% coverage), and the description does not mention or explain these parameters. Since the description fails to compensate for the missing schema information, it provides no semantic guidance for the 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's purpose: suggest BUY actions for underweight asset classes based on the advisor profile. It uses a specific verb ('Suggest'), identifies the resource (underweight asset classes) and provides context on the process (drift + screening). It also distinguishes non-screenable classes, giving a clear scope.

  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 mentions a prerequisite (outbound_enabled=true) and outlines that it composes drift and screening, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The guidance is implied rather than explicit, leaving some ambiguity.

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

• calculate_twrA
  3.8/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the methodology (Modified Dietz between imports, geometric chaining), the requirement of ≥2 imports, and the output structure (period_return, annualized return, per-sub-period breakdown, quality warnings). This is transparent about what the tool does and what it returns. It does not mention side effects (likely none) or read-only status, but for a calculation tool this is less critical.

  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: it leads with the core purpose, then explains the methodology, requirements, and output in a logical flow. Every sentence adds meaningful information without fluff. It is front-loaded with the key concept and avoids unnecessary details.

  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 tool's purpose, methodology, requirements, and return values, which is substantial. However, it completely omits any explanation of the two optional parameters, which is a significant gap since the schema itself offers no descriptions. Without knowing what period_from and period_to do, an agent cannot confidently invoke the tool correctly. The lack of parameter semantics reduces overall completeness.

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

  Parameters1/5

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

  The input schema has two parameters (period_to, period_from) with no descriptions, and schema description coverage is 0%. The tool description does not mention these parameters at all, leaving the agent without any hint of their meaning, format, or whether they are date filters, limits, or something else. Since the description must compensate for the schema's lack of detail and it does not, this is a major gap.

  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 calculates a time-weighted return over XPerformance import history, explicitly distinguishing it from money-weighted return by noting it removes the effect of contributions/withdrawals. The verb 'calculate' and resource 'time-weighted return' are specific, and the mention of GIPS compliance adds precision. It effectively differentiates itself from the sibling calculate_mwr without needing to name it explicitly.

  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 when to use this tool: when you need a pure portfolio performance metric that excludes cash-flow timing effects. It also states a hard prerequisite (≥2 XPerformance imports) that tells the agent when the tool is applicable. However, it does not explicitly name calculate_mwr as the alternative or give a direct 'use this instead of X' statement, so it is not fully explicit.

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

• import_extract_csvA
  3.8/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden. It discloses idempotency (re-import updates instead of duplicating) and mentions the return content (counts, warnings, preview). However, it does not clarify whether new positions are created if they don't exist, or any permission requirements or error conditions for a mutation tool. It provides useful but incomplete 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 two sentences with no fluff. It front-loads the primary purpose and idempotency, then briefly states return values. Every sentence earns its place, and the structure is easy to scan.

  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 tool with one parameter and no output schema, the description covers the essential usage details: what input it expects, the idempotent behavior, and the nature of the return. It does not cover error scenarios or prerequisites beyond the file path, but these are minor for a straightforward import tool. The description is largely complete for an agent to call it correctly.

  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 100% and the sole parameter file_path already includes the format details (CSV from XP, Posicao Consolidada, Extrato). The description repeats this information but adds no new meaning about the parameter, such as format constraints or path requirements. Baseline 3 is appropriate given the schema's completeness.

  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 action (import), the resource (a CSV exported from XP Investimentos), and even specifies the export types (Posicao Consolidada, Extrato). It also notes the idempotent behavior and what it returns, so an agent can immediately understand what the tool does and how it differs from sibling import tools that handle PDFs.

  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 it (when you have a CSV from XP) but does not explicitly contrast it with alternatives like import_xperformance_pdf or import_bank_extract_pdf. There's no 'when not to use' or mention of conditions that would select another tool. The guidance is inferred from the resource type rather than stated.

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

• get_portfolio_summaryA
  4/5.0
  Behavior3/5

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

  The description explicitly states 'Zero outbound HTTP' and 'No inputs', which provides some behavioral clarity. However, with no annotations present, it does not explicitly confirm read-only behavior or lack of side effects, leaving some ambiguity.

  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 dense but not verbose; it packs all relevant output details into a compact list without unnecessary filler. Each clause adds useful information.

  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 lack of an output schema, the description does a good job listing the major return components and units (%, BRL). It does not specify exact data types or nested structures, but for a summary tool it provides sufficient context for an agent to understand what will be returned.

  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 tool has zero parameters and the schema is empty; the description explicitly confirms 'No inputs,' which matches the schema. Since there are no parameters to document, the baseline score of 4 is appropriate.

  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?

  Clearly states the tool's purpose with a specific verb ('get') and resource ('portfolio summary'), and enumerates the exact outputs (total value, per-class breakdown, top 5 positions, P&L, FGC coverage, maturity buckets, reconciliation gap). It is easily distinguished from sibling tools like get_positions or get_cash_flows.

  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 obtaining an aggregate portfolio overview and reconciliation metrics, but it does not explicitly state when to prefer this tool over siblings or when not to use it. Usage guidance is only implicit through the listed return values.

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

• get_positionsA
  4/5.0
  Behavior3/5

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

  No annotations are provided; the description explains the returned fields but does not mention side effects, costs, or limits. Since this is a read operation, the lack of destructive-behavior warnings is acceptable but still incomplete.

  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 succinct and well-structured, covering core functionality and return fields without unnecessary verbosity.

  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 provides sufficient context for a straightforward listing operation, including the meaning of returned values; minor gaps exist around edge cases but are not critical.

  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?

  The single parameter asset_class is documented via its enum values but no description is given beyond the filter mention; the schema carries the possible values, and the description adds minimal extra context.

  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?

  Clearly states the tool lists all positions in the portfolio, with an optional filter by asset class, distinguishing it from related portfolio tools.

  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 it describes what the tool does and the optional filter, it does not explicitly contrast with sibling tools like get_portfolio_summary or suggest_buys, though the scope is clear enough.

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

• import_bank_extract_pdfA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does well by disclosing filtering, idempotency, and persistence to the cash_flows table. It does not mention potential side effects like file validation errors or partial imports, but the core behaviors are transparent.

  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 structured in short, information-dense sentences. Every sentence adds value—import source, filtering criteria, idempotency, and persistence—without unnecessary elaboration.

  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 single parameter and lack of output schema, the description covers essential context: source, filter behavior, idempotency, and destination table. It could be slightly more complete by mentioning what happens on duplicate files or invalid PDFs, but the provided context is strong.

  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?

  The single parameter file_path has 100% schema description coverage and the description repeats the essential detail that it is an absolute path to an XP PDF. The description does not add significant new meaning beyond the input schema, so baseline is appropriate.

  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 clearly states the tool imports PDFs from XP's Conta Digital Extrato and specifies the exact filtering logic (transfers between digital and investment accounts, APORTE/RESGATE). It also clarifies idempotency and persistence, leaving no ambiguity about the tool's purpose.

  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 explains what the tool does and its idempotent behavior, but it does not explicitly compare against sibling import tools like import_xperformance_pdf or import_extract_csv. There is no direct guidance on when to choose this tool over alternatives.

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

• get_market_dataA
  4.1/5.0
  Behavior4/5

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

  It discloses caching with SQLite, the permission requirement, and partial error handling. It also mentions TTL override. These are important behaviors not in the schema or annotations.

  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?

  Three sentences, front-loaded with the primary action, then requirement, then error behavior. No wasted words.

  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?

  It explains key behaviors and constraints, but without an output schema, it doesn't specify the full return shape. It gives enough for basic use, but could mention what the response contains beyond errors.

  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?

  The schema only documents one of three parameters, and the description adds details for tickers (1-50) and cache_ttl_minutes (override), but leaves 'include' unexplained. Since coverage is low, it partially compensates but not fully.

  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 action (fetch quotes and/or fundamentals), the source (brapi.dev), the range (1-50 tickers), and a prerequisite (outbound_enabled=true). It distinguishes this from other tools like get_crypto_quote by focusing on general market data and multiple tickers.

  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?

  It provides specific usage conditions: requires outbound_enabled=true and explains partial failure behavior. It doesn't explicitly contrast with alternatives but the condition and multi-ticker scope give enough guidance.

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

• screen_assetsA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses network behavior ('Fetches the universe and per-ticker quote+fundamentals from brapi.dev (cached)'), merging behavior ('Profile's excluded_classes/excluded_tickers are merged with the call's exclude_tickers'), and output nature ('Output is educational analysis, not investment advice'). This provides substantive insight into side effects and constraints, though it stops short of explicitly stating read-only or idempotency.

  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 three sentences, with the first sentence front-loading the core purpose. The subsequent sentences deliver essential behavioral details without fluff. It is compact and information-dense, though slightly longer than necessary.

  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 no output schema and no annotations, the description covers the main operational aspects: purpose, data source, caching, exclusions, and output disclaimer. It does not detail the exact return structure, but the phrase 'output is educational analysis' gives a sense of what to expect. The criteria parameter's internal fields are named (sort_by, filters, limit) which helps. Overall, it is fairly complete for a ranking tool.

  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 only 33% (only asset_class has a description). The description adds meaning to otherwise undocumented parameters: it specifies that 'criteria' contains sort_by, filters, and limit, and explains that exclude_tickers is merged with profile-level exclusions. This compensates for the sparse schema and helps an agent understand what each parameter controls.

  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 'Rank' and a clear resource 'B3 assets' with enumerated asset classes (FII, ACAO, ETF). It also specifies the action is against criteria. This distinguishes it from sibling tools like get_market_data or suggest_buys, which are retrieval or suggestion tools, making the purpose unmistakable.

  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 screening/ranking assets but does not explicitly mention when to use this tool versus alternatives or when not to use it. There is no direct contrast with sibling tools like suggest_buys or get_market_data. The intent is inferable but not explicitly stated, so guidance is implied rather than provided.

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

• set_crypto_positionA
  4.1/5.0
  Behavior4/5

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

  The description discloses key behaviors: it fetches external quotes, stores a snapshot, flows into portfolio summary and allocation drift, and that quantity=0 removes the holding (idempotent). It also notes re-running refreshes the value and that no cost basis/P&L is recorded. The term 'Outbound-gated' is a hint but not fully explained, and rate limits are not covered.

  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 information-dense but not overly verbose. It front-loads the core purpose and then adds necessary behavioral details. Each sentence adds value, and the structure flows logically from purpose to side effects to limitations.

  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 no output schema, the description adequately explains what happens on invocation: it stores a snapshot, updates downstream summaries, and handles removal. It covers the essential context an agent needs to decide and execute the tool, though it does not mention return values or error scenarios, which are minor gaps.

  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 already cover the basics (ticker symbol, quantity amount). The tool description adds meaning by specifying that ticker is a crypto symbol in the context of BRL, and crucially explains that quantity=0 removes the holding, which is not in the schema. This goes beyond the schema's baseline coverage.

  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 verb 'Manually track' and the resource 'crypto holding', and explains the mechanism (fetches BRL quote, stores snapshot). It distinguishes itself from the sibling get_crypto_quote by describing the position-setting action rather than just quote retrieval.

  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?

  While the description implies when to use it (to record a crypto position), it does not explicitly contrast with alternatives like get_crypto_quote or state 'use this when...'. The downstream effects are mentioned, but there is no direct usage guidance beyond the functional description.

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

• get_crypto_quoteA
  4.2/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and does well: it discloses 15-minute caching, outbound-gating, per-ticker partial failure, and the fact that this is quote-only rather than a portfolio operation. This is strong behavioral transparency.

  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 compact and to the point, with no filler or redundant wording. Every sentence adds meaningful information about scope, behavior, or failure semantics.

  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 scope and partial failure well, but it omits the meaning of cache_ttl_minutes and provides no output-shape information. Since there is no output schema, the lack of return-value context leaves some ambiguity for an agent.

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

  Parameters2/5

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

  The tickers parameter is reasonably described in the schema, but cache_ttl_minutes only has a type and no description. The description mentions '15-minute cache' but never explains that the parameter overrides this TTL, leaving its semantics undocumented. Schema coverage is only 50% and the description does not compensate for the missing 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 clearly specifies the tool fetches spot crypto quotes in BRL via Mercado Bitcoin, with concrete examples (BTC, ETH, SOL). It also distinguishes scope by noting crypto is not yet a tracked portfolio asset class, which helps separate it from portfolio-related siblings.

  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?

  It provides practical usage context: quote-only, BRL-denominated, cache behavior, outbound-gated, and partial failure tolerance. It does not explicitly name an alternative for non-crypto market data, but the 'Quote only' and 'not yet a tracked portfolio asset_class' phrasing conveys appropriate boundaries.

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

• import_xperformance_pdfA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses idempotency (re-import updates existing positions), that it returns import counts, warnings, and a preview, and it implies mutation via 'updates existing positions'. It doesn't cover permissions or error handling, but it covers key behavioral traits beyond the schema. This is a solid disclosure.

  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?

  Three sentences with zero waste. The purpose is front-loaded, and each sentence adds distinct information: what it imports, what it extracts, and its idempotency/return behavior. Concise and well-structured.

  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 single-parameter tool with no output schema and no annotations, the description covers the essential details: what it does, what it extracts, idempotency, and return preview. It lacks explicit return format details (e.g., structure of counts/warnings), but the mention of preview up to 10 positions is sufficient. It's adequate but not exhaustive.

  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?

  The only parameter file_path is fully described in the schema ('Absolute path to the XPerformance PDF'). The description adds the context that it's XP's official report, but that's redundant with the schema. Since schema coverage is 100%, the baseline is 3; the description does not add significant semantic meaning beyond what the schema provides.

  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 states a specific verb ('Import') and a specific resource (XPerformance PDF, XP's official portfolio report). It distinguishes from sibling import tools like import_extract_csv and import_bank_extract_pdf by specifying the exact report type and the fields extracted. The purpose is unambiguous.

  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 clear context: this tool is for XP's official portfolio report, which implicitly tells the agent when to use it over other import tools. However, it does not explicitly mention alternatives or conditions to avoid using it, so it lacks explicit exclusions. It's clear enough but not exhaustive.

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

• get_advisor_profileA
  4.3/5.0
  Behavior4/5

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

  The description discloses expected return behavior (exists:false when unconfigured) and error reporting (schema errors in errors array), which is helpful given there are no annotations. It does not cover side effects, but the tool is read-only by nature.

  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 two sentences, direct, and includes only essential information. It is well-structured and easy to parse.

  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 simple nature of the tool and the absence of an output schema, the description adequately explains the return behavior and error handling. An agent can correctly invoke and interpret the result without additional context.

  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?

  There are zero parameters, so the baseline score of 4 applies. No parameter descriptions are needed.

  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 reads the advisor profile from a specific file path, and distinguishes it from sibling tools that set or manage other data. The purpose is unambiguous.

  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 (when you need to read the advisor profile) but does not explicitly state when to prefer this tool over siblings like 'set_advisor_profile' or when not to use it. No explicit alternatives are mentioned.

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

• get_cash_flowsA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description must convey behavior. It states the operation is a 'list' (implying read-only), describes sorting by flow_datetime and aggregation of totals, which is transparent. It does not explicitly mention side effects, but the read-only nature is strongly implied.

  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 two sentences, concise and highly informative. It front-loads the core purpose and then adds specific details about sorting and aggregation, with no wasted words.

  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 gives a good summary of the output: rows sorted by flow_datetime and aggregate totals. It does not enumerate every field, but given no output schema, this is sufficient for an agent to understand what will be returned.

  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 schema has no parameter descriptions, but the description explains the purpose of the filters ('optional date range and kind filters') and the limit ('up to limit rows'). This covers the parameters adequately, though it does not specify formats or constraints individually.

  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 cash flows (APORTE/RESGATE) with filters, distinguishing it from sibling tools like get_transactions and get_dividends. The specific resource and action are unambiguous.

  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 mentions optional filters (date range, kind) and a limit parameter, giving a clear sense of when to apply them. It does not explicitly contrast with alternatives, but the specialized 'cash flows' scope makes the intended use evident.

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

• get_dividendsA
  4.4/5.0
  Behavior5/5

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

  The description explicitly states 'Zero outbound HTTP' and 'Read-only', which are important side-effect disclosures despite the absence of annotations. It also reveals output behavior (sorted by pay_date DESC, includes gross/tax/net) providing a transparent view of what the tool does.

  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 two sentences with no redundancy. All key information (filters, sorting, currency, side effects) is packed efficiently without 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 there is no output schema, the description provides a reasonable overview of the output: rows sorted by pay_date, with gross/tax/net in BRL. It does not enumerate all returned fields or specify data types, but for a list operation this is sufficient. The absence of a stated output schema is partially mitigated by the clear mention of the main fields.

  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?

  The schema provides no descriptions for the six parameters, and the description only partially explains them. It names the filters (ticker, asset_class, kind, date-range) and explains 'limit' rows and sorting, but does not define allowed values, formats (e.g., date format), or the meaning of 'kind'. This adds some meaning but leaves substantial 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 clearly states the verb 'List' and the resource 'dividend/JCP payouts', distinguishing it from siblings like get_transactions and get_cash_flows. It is specific and unambiguous about the tool's primary function.

  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 notes optional filters (ticker, asset_class, kind, date-range) and a limit, but does not explicitly state when to choose this tool over alternatives. It implies usage for dividend-specific queries but lacks an explicit when-not condition. Still, it provides enough context for typical use.

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

• set_advisor_profileA
  4.4/5.0
  Behavior4/5

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

  The description discloses that the operation overwrites the existing profile, which is a key behavioral trait. It also mentions a conditional requirement (accept_disclaimer=true when outbound_enabled=true). It does not mention error cases or side effects beyond overwriting, but the core behavior is transparent given no annotations exist.

  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 a single, well-structured sentence that packs all essential information without redundancy or fluff. Each clause contributes to understanding the tool's function, parameters, and constraints.

  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 set operation with no output schema, the description provides sufficient context: it names the file path, required and optional fields, and a conditional dependency. It lacks explicit success/error behavior, but that is not critical for a write tool. The description is complete enough for an agent to invoke it 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?

  The schema only shows 'profile' and 'accept_disclaimer' with minimal type info. The description compensates by enumerating the required and optional fields inside the profile object, and explaining the conditional need for accept_disclaimer. This covers most semantic meaning, though it stops short of providing examples or edge-case validation rules.

  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 action ('save (overwrite)') and the specific resource (advisor profile at a path). It is distinct from sibling tools like get_advisor_profile, which reads the profile, and other data import tools. The purpose is unambiguous.

  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 when the advisor profile needs to be created or updated, but does not explicitly state 'use this when you want to change the profile' or contrast with read-only alternatives. However, the overwrite semantics and context make the intended use clear enough.

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

• get_transactionsA
  4.6/5.0
  Behavior5/5

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

  The description explicitly states 'Read-only' and 'Zero outbound HTTP', making side effects and safety clear. With no annotations provided, this transparency is especially valuable.

  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 compact and front-loaded, conveying the core action and all relevant attributes in two sentences. No filler or redundant wording is present.

  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 mentions return ordering, currency, and row limiting, which is useful given the lack of an output schema. It does not specify exact response fields, but the description is sufficient for a straightforward listing tool.

  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?

  Although the schema has no per-parameter descriptions, the description explains the meaning of the ticker, asset_class, date-range, and limit parameters. This gives enough semantic context for callers to use them effectively.

  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 trade transactions, identifies key filters (ticker, asset_class, date-range), and specifies sorting and currency. This makes the primary purpose immediately understandable.

  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 fully defines what the tool does and its optional parameters, making it suitable for retrieving transaction data. It does not explicitly contrast with sibling tools like get_dividends or get_cash_flows, but the domain is clear enough for most use cases.

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