Bankstatemently

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

Annotations already mark this as read-only and non-destructive. The description adds valuable behavioral context: results are per-currency (never sum currencies), scope defaults to all completed statements, and the scope parameter narrows by accounts/products/date range. This exceeds the annotation baseline.

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

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

The description is two sentences, front-loaded with the core purpose, enumerates fields, and contains no filler. Every sentence earns its place.

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

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

Given the rich input/output schemas and annotations, the description covers the essential aspects: metric types, filter/scope concept, default behavior, and per-currency warning. No critical gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic meaning by explaining aggregation concept, per-currency behavior, and the default scope behavior, which helps interpret the 'scope' and 'metric' parameters beyond their schema descriptions.

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

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

The description clearly states the tool computes a single metric (sum/average/count/max/min) over a filtered set of transactions, which is specific and distinguishes it from sibling tools like list_transactions (raw list) or group_by (grouped output).

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

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

The description provides clear usage context: defaults to all completed statements, can narrow via scope, and warns about per-currency results. However, it does not explicitly mention when to prefer this over siblings like top_n or time_series, nor exclude any alternatives.

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

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

The description goes far beyond the annotations (readOnlyHint, destructiveHint) by disclosing credit consumption, caching behavior (free re-fetches), and the presence of a 'summary' field as the source of truth. This is rich behavioral context that helps the agent set expectations and interpret results.

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

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

The description is concise (three sentences) and front-loaded: the first sentence states the core purpose, and subsequent sentences add essential behavioral details about caching, credits, and the summary field. Every sentence earns its place without redundancy.

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

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

Given the tool's simplicity (one required parameter, output schema present), the description covers all necessary facets: what it does, prerequisites (previously processed), cost implications, caching behavior, and the summary field. The output schema likely documents return values, so no additional explanation is needed.

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

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

The input schema provides 100% coverage with a description for document_id ('Document ID (from convert_statement or list_statements)'). The description adds no further parameter semantics, but the baseline of 3 is appropriate since the schema already documents the only parameter adequately.

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

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

The description clearly states a specific action ('Run AI transaction categorization') on a defined resource ('previously processed document') and its output ('return its category mappings'). It distinguishes itself from siblings by mentioning caching and credit behavior, making it clear this is a categorization-specific tool rather than a listing or aggregation tool.

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

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

The description implies usage context by requiring a 'previously processed document' and mentions that it consumes credits only the first time, with free re-fetches. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough for an agent to infer the correct scenario.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful context about default scope ('all your completed statements') and the ability to override it, but it doesn't detail output behavior beyond 'side-by-side metric comparison' or disclose any limitations, such as pagination or performance constraints. It adds some value but not rich behavioral context.

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

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

The description is two sentences, front-loaded with the core purpose, and includes a helpful example and a clear scoping instruction. Every sentence contributes essential information without redundancy or filler.

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

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

The tool is moderately complex (4 parameters, nested objects, output schema exists). The description conveys the core functionality, how to scope, and gives illustrative examples, which is sufficient for selection. It could be more complete by explaining how filterA/filterB relate to the comparison or what metrics are available, but the detailed schema and documentation partially compensate.

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

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

The input schema has 100% coverage with detailed descriptions for all parameters (e.g., scope, metric, filterA, filterB). The description only mentions 'scope' and 'two filtered groups' without adding details beyond the schema, so it doesn't enhance parameter understanding beyond the baseline. The examples in the description lightly illustrate filter usage but don't add semantic depth.

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

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

The description clearly states the tool's purpose: 'Side-by-side metric comparison for two filtered groups of transactions' with concrete examples (e.g. one category vs another, one month vs another). It uses a specific verb ('compare') and resource ('transaction groups'), distinguishing it from sibling tools like aggregate or group_by which don't emphasize two-group side-by-side comparison.

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

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

The description provides clear usage context with examples of when to use the tool and how to narrow scope ('pass "scope" to narrow to specific accounts/products and/or a date range'). It implies when this tool is appropriate (comparing two groups) but doesn't explicitly state when to avoid it or name alternative tools, so it falls short of a 5.

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

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

Beyond annotations (readOnlyHint false, destructiveHint false), the description discloses key behaviors: batch mode only admits files and returns immediately, consumes credits per page, JSON returns inline data vs other formats returning download links, and the summary field is the single source of truth. It also gives model-specific instructions about translation and not echoing status values.

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

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

The description is long but well-structured, starting with purpose and then systematically covering input methods, batch behavior, output formats, and response handling. Every sentence adds value, though some details repeat schema descriptions. It is appropriately detailed for a tool with multiple parameter modes.

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

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

Given the 7 parameters, nested objects, output schema, and multi-mode behavior, the description covers all essential aspects: input reference options, batch vs single, output formats, download link behavior, summary instructions, credit consumption, and page limits. The existence of an output schema means return values don't need to be detailed here.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaningful context beyond schema: clarifies pdf_file is automatically populated, emphasizes pdf is a last resort, explains upload_ids mutual exclusivity, and details the admission-only batch behavior. This adds semantic clarity beyond the schema fields.

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

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

The description explicitly states the tool converts a bank statement PDF into structured data or a spreadsheet, using a specific verb and resource. It clearly distinguishes from sibling tools like get_statement by explaining the batch admission workflow and directing users to call get_statement for results.

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

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

Provides explicit when-to-use guidance for each parameter mode (pdf_file, pdf_url, upload_id, upload_ids), including when to use request_upload. It also explains when to use get_statement after batch admission and notes output format differences, offering clear alternatives.

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

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

Annotations already mark this read-only, non-destructive, and closed-world. The description goes beyond by specifying return values (extraction accuracy, integrity score, overall score), the held-out error behavior, the scoring consequence of missing originalData (raw-fidelity dimension 0), the 'never fabricate' rule, and the free-to-use cost note. This is rich behavioral context that annotations alone do not provide.

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

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

The description is six sentences, each adding distinct value: main purpose, parameters, return values, published-status constraint, originalData guidance, and catalog prerequisite. It is front-loaded with the primary purpose and keeps every sentence purposeful without redundancy.

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

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

With an output schema present, the description correctly avoids restating return structures. It covers prerequisites (catalog, published status), the alternative data source (get_statement), error behavior, cost, and the critical originalData guidance. For a scoring tool with 4 parameters and a non-trivial evaluation model, this is adequately complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by clarifying the preference for statement_id over content_hash, recommending originalData and how to obtain it (via get_statement with data_mode 'original'), and noting the scoring penalty for absence. This is useful beyond the schema's field-level descriptions.

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

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

The description opens with a specific verb+resource: 'Score parsed bank statement transactions against the Bankstatemently benchmark ground truth.' This clearly states the tool's function and distinguishes it from siblings like rate_statement or categorize_statement. It also names the key inputs (statement_id/content_hash and transactions) and the output type.

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

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

Provides explicit context: only published statements can be evaluated, held-out statements return an error, and it instructs to read the benchmark://catalog first. It also names get_statement as an alternative for fetching originalData. However, it doesn't explicitly contrast with other scoring/rating tools in the sibling list, so it's clear but not a full when-not matrix.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral context: the credit-to-page mapping and the fact that operational limits are reported. It does not contradict annotations and provides insight into what the tool returns beyond a simple balance.

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

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

The description is two sentences with no redundancy. The first sentence states the primary action, the second explains the credit unit and additional limits. Every phrase adds value and is front-loaded with the core purpose.

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

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

Given the tool has no parameters and an output schema exists (so return values are documented elsewhere), the description covers all necessary context: what a credit is, what operational limits are reported, and why this matters before batch processing. It is complete for this low-complexity tool.

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

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

The tool takes no parameters, so there are no parameter semantics to document. Per the baseline for zero parameters, a score of 4 is appropriate; the description focuses on the tool's purpose and output rather than params.

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

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

The description opens with a specific verb and resource: 'Check your current credit balance.' It also clarifies the credit unit (1 credit = 1 page) and additional outputs (plan limits), clearly distinguishing it from sibling tools that process or list statements/transactions.

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

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

The description provides clear context for when to use the tool: 'so you can size a multi-file batch correctly before starting it.' It implies the tool should be consulted before batch operations, but does not explicitly mention alternatives or exclusions. Since no sibling tool directly checks credits, the guidance is sufficient.

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

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

Annotations declare readOnlyHint and non-destructive, and the description adds extensive behavioral context: non-json formats return time-limited download links, the summary field is the single source of truth, translation rules for non-English conversations, and a directive to never echo raw status values. No contradictions.

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

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

The description is lengthy but every sentence serves a purpose for a tool with 5 parameters and significant caveats. Front-loaded with purpose and usage, then proceeds to nuanced instructions; slightly verbose yet justified by complexity.

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

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

Covers when to use, format differences, data_mode semantics, benchmark integration, summary handling, and language behavior. For a tool with output schema and annotations, this leaves essentially no gaps for an agent to misuse it.

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

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

Schema coverage is 100% with rich descriptions, but the description adds useful output_format behavior (inline vs. link) and reinforces data_mode semantics. It somewhat repeats schema text, but the added output_format context and summary-field guidance provide moderate extra meaning.

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

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

States it fetches the full converted data for a previously processed document. The verb 'Fetch' and resource are specific, and it distinguishes itself from convert_statement (which produces the document) and list_statements (which lists metadata).

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

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

Explicitly specifies when to use: after convert_statement returns a 'processing' status, or for re-fetching results. It also ties to evaluate_benchmark by directing data_mode 'original' before submission, giving clear workflow context without ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral details beyond annotations: 'Results are per-currency' and 'Scope defaults to all your completed statements', which clarify default behavior and output grouping. This is valuable but does not, for instance, note whether empty groups are included or sorting behavior.

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

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

The description is three sentences, front-loaded with the core operation and then providing key behavioral/default-scope context. Every sentence earns its place, with no filler or repetitive information.

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

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

Given the rich schema, output schema, and annotations, the description adequately covers the tool's purpose and key default behaviors. However, it omits any mention of the filter parameter, which is a significant part of the tool's scoping mechanism. Still, the schema and output schema fill most gaps, making the description largely complete for an agent using the full tool definition.

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

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

With 100% schema description coverage, the baseline is 3. The description mentions dimension, metric, and scope, adding some meaning (e.g., scope narrows by accounts/products/dateRange), but it fails to mention the filter parameter, which is a distinct way to subset transactions. Since the schema fully documents filter, the description does not need to repeat it, but its omission from the prose slightly reduces the added value.

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

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

The description clearly states the tool's function: 'Group transactions by a dimension (month/category/merchant/account/currency) and apply a metric to each group.' This identifies the specific verb, resource, and enumerates the grouping dimensions and metrics, making it distinct from sibling tools like aggregate or time_series.

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

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

The description gives usage context for scope ('Scope defaults to all your completed statements; pass "scope" to narrow to specific accounts/products and/or a date range') but does not mention the filter parameter as an alternative way to narrow results, nor does it provide explicit when-to-use versus alternatives like aggregate or time_series. It implies usage but misses exclusions and sibling differentiation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the scope 'previously converted' but does not disclose additional behavioral details like ordering, pagination defaults, or response format. 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.

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

The description is a single, front-loaded sentence that conveys the primary purpose and key features without any wasted words. Every word earns its place.

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

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

Given the simplicity of a list tool, the presence of a full output schema (context signal) and annotations (readOnlyHint, destructiveHint), the description is complete. It accurately conveys what the tool does, and the schema covers the parameter details.

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

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

Schema description coverage is 100%, so all three parameters (limit, offset, status) are already documented. The description mentions pagination and status filter but only restates what the schema provides, adding no new semantic meaning.

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

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

The description clearly states the verb 'Browse' with a specific resource ('previously converted bank statements') and mentions key features (pagination, optional status filter). This distinguishes it from sibling tools like get_statement, which likely retrieves a single statement.

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

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

The phrase 'previously converted' gives clear context that this tool is for browsing existing statements, not for uploading or converting new ones. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls slightly short of a 5.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds valuable behavioral details: results are capped at 50 rows, the effective scope is echoed in every response (document count + date range), and each row includes its source document's content_hash for citation. This goes well beyond the annotations.

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

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

The description is three sentences, front-loaded with a concise definition, then the action and cap, then default scope and response metadata. Every sentence adds value with no fluff.

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

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

The tool is complex (3 params, nested scope, many filter fields), but the schema covers all parameters and the output schema describes returns. The description adds essential behavioral context (cap, default scope, response provenance) and is complete enough for an agent to call correctly. It omits explicit mention of the filter parameter, though 'filtered list' implies it.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions the 'scope' parameter conceptually ('pass scope to narrow to specific accounts/products and/or a date range') but adds no syntax or semantics beyond the schema. The 'capped at 50 rows' note relates to limit but is already in the schema as max 50.

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

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

The description defines a transaction precisely, states the action ('Return a filtered list of transactions'), and distinguishes it from sibling list tools by emphasizing transactions are single statement lines across converted statements. This clearly differentiates it from list_statements and list_transfers.

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

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

The description states that scope defaults to all completed statements and that passing 'scope' narrows by accounts/products and/or date range, giving clear context for when to use it. However, it does not explicitly contrast with sibling tools like aggregate or group_by, so it lacks explicit exclusions/alternatives.

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

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

The description goes well beyond the readOnlyHint annotation by detailing behavioral nuances: transfers are only matched when both sides are visible, account-level successions are included, payments to outside parties are excluded, and every response reports the match window used even when no transfers are found. The amountMin parameter's effect on response structure (adding an 'unmatched' bucket) is also transparently disclosed.

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

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

The description is longer than a typical tool description, but every sentence earns its place, covering definition, exclusions, usage guidance, default scope, and amountMin's special mode. It is well-structured but densely packed, and could benefit from slight restructuring (e.g., separating the amountMin behavior) for even easier skimming.

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

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

Given the tool's complexity (nested scope object, output schema, two behaviors with/without amountMin), the description is remarkably complete. It explains the core concept, the match window reporting, the unmatched bucket, and how to narrow scope—leaving little ambiguity for an agent to decide when and how to invoke it.

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

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

Although the schema already provides 100% coverage for the two parameters, the description adds valuable context: scope defaults to all completed statements, and amountMin not only floors transfers but also changes the response by adding an unmatched bucket. The concrete example ('trace transfers over $10,000') helps the agent understand when and why to use amountMin.

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

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

The description clearly states the purpose: 'Match transfers between your own accounts' and precisely defines what constitutes a transfer (two transactions, debit+credit, amount and date aligned), including account successions. It explicitly differentiates itself from list_transactions by stating it is 'THE way' to answer money-moved-between-accounts questions and warns against using list_transactions + arithmetic.

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

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

The description provides explicit when-to-use guidance: 'never try to answer a money-moved-between-accounts question with list_transactions + arithmetic; always call this tool instead.' It also explains when to use amountMin for finding unmatched large movements, and describes the default scope (all completed statements) and how to narrow it via 'scope'.

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

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

The description goes well beyond the annotations by disclosing that calling again updates the existing rating and clears previous feedback, that the stored rating state is returned in the response, and that there is no separate tool to read it back. It also warns that feedback is only accepted when the rating is 3 or below. These are important behavioral traits not captured in the annotations.

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

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

The description is three sentences with the core purpose front-loaded in the first sentence. Each sentence adds essential information: purpose, update/clearing behavior, and the summary field as a source of truth. There is no redundancy or filler.

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

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

The description fully covers update semantics, feedback clearing, the absence of a separate read tool, and the summary field. Combined with the presence of an output schema, an agent has all necessary context to invoke the tool and interpret responses without ambiguity.

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

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

The input schema already provides descriptions for all 7 parameters (100% coverage), so the baseline is 3. The description adds some context about conditional feedback acceptance and use-case tags, but these details are also present in the schema. It does not add significant meaning beyond the schema for individual parameters, though it does reinforce the overall flow.

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

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

The description opens with a specific verb and resource: 'Report how well a previously converted bank statement was parsed' and explains the action of submitting a rating. This clearly distinguishes the tool from siblings like convert_statement and list_statements, and the mention of updating an existing rating adds further specificity.

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

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

The description clearly implies usage after conversion by calling the statement 'previously converted' and explains re-calling behavior, which indicates it is the canonical tool for rating and updating. It also notes there is no separate read-back tool, guiding the agent to rely on this tool's response. However, it does not explicitly name alternative tools or provide exclusions, so it falls just short of a 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses single-use/expiring URLs, the requirement to PUT the PDF before calling convert_statement, and the prohibition on retrying a failed PUT against the same URL. It also explains the free-to-use nature and likely host-blocking errors, which are not evident from annotations.

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

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

The description is lengthy but well-structured with a playbook, troubleshooting, and batching details, all front-loaded around the core purpose. Each sentence serves a functional role for a complex multi-step tool, though some redundancy with the schema's parameter description could be trimmed.

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

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

The description covers all essential context: prerequisites, step-by-step workflow, response shapes, error handling, host configuration, cost implications, and the integration with convert_statement. Given the tool's complexity and the availability of an output schema, this is remarkably complete.

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

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

The schema already documents 'count' with 100% coverage. The description adds value by integrating 'count' into the full workflow (using upload_ids in a single convert_statement call) and by explaining the default single-URL response, which is not fully captured in the schema alone.

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

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

The description opens with a specific verb 'mint' and explicitly names the resource (single-use upload URL) and purpose (pushing a conversation-attached PDF before conversion). It clearly distinguishes this from sibling tools like convert_statement by positioning it as the upload prerequisite.

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

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

It explicitly states 'Use this ONLY when you have no other way to reference the attached file' and contrasts with alternatives (pdf_file/pdf_url). It also provides a step-by-step playbook, including when to check the sandbox first and when to retry with a fresh URL, making the usage conditions unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that scope defaults to all completed statements and can be narrowed, but does not disclose bucket behavior, timezone handling, or output details. This adds modest context beyond the annotations, but not enough for a higher score.

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

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

The description is two sentences, front-loaded with the core function and purpose, with no filler or repetition. Every word earns its place.

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

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

For a tool with 4 params, nested objects, and an output schema, the description provides a high-level summary and default scope behavior. The rich schema descriptions and output schema cover the remaining details, so the description is sufficiently complete 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.

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

The schema has 100% coverage with detailed descriptions for all parameters, including the scope structure, bucket enum, metric enum, and filter. The description only reiterates the scope narrowing capability, adding minimal value beyond the schema.

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

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

The description clearly states the tool computes a time series by grouping transactions into week or month buckets and applying a metric, with the explicit purpose 'useful for trends'. This specific verb+resource+scope distinguishes it from generic sibling tools like group_by or aggregate.

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

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

The description provides context that it is 'useful for trends' and explains the default scope (all completed statements) with the option to narrow via 'scope'. However, it does not explicitly mention when not to use it or name alternative tools, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool's safety profile is known. The description adds behavioral nuance by revealing that scope defaults to all completed statements and that monetary metrics are ranked per-currency, which is not evident from the schema or annotations. No contradictions.

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

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

The description consists of two concise sentences, front-loaded with the core function. Every word earns its place, with no redundant or filler content.

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

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

Given the tool's complexity (5 parameters, nested objects) and the presence of an output schema, the description adequately covers the primary purpose and default behavior. It does not mention the 'filter' parameter, but the schema fully documents it, and the description needn't repeat what structured data already provides.

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

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

Schema coverage is 100% with detailed descriptions for all parameters, so the baseline is 3. The description adds value by explaining the default scope behavior (all completed statements) and how scope narrows via accounts/products and date range, which enhances understanding beyond the schema's static descriptions.

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

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

The description clearly states the tool returns the top N groups ranked by metric in descending order, specifying per-currency handling for monetary metrics. The verb 'Return' and resource 'top N groups' make the purpose specific and distinguish it from sibling tools like 'group_by' or 'aggregate'.

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

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

The description provides clear context by stating that scope defaults to all completed statements and can be narrowed, which implies when to use the scope parameter. However, it does not explicitly compare with alternatives or mention when not to use the tool, so it lacks explicit exclusions.

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