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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description only needs to add context beyond safety. It does: warns 'never sum across currencies yourself' and states the default scope ('all your completed statements'). These are meaningful behavioral constraints. It does not describe edge cases like empty results, but given the annotation coverage, this is sufficient.

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

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

Three sentences with zero filler. The purpose is front-loaded, followed by the critical per-currency warning and default scope, then the pointer to get_credits. Every sentence earns its place; nothing is redundant or excessive.

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?

There is no output schema, so the description should clarify what the tool returns. It notes results are per-currency, implying multiple currencies may yield multiple results, but doesn't explicitly state the return shape (e.g., a list of {currency, value}). It covers default scope and how to narrow, and the schema richly documents parameters. The only minor gap is the exact output format, which keeps it from a 5.

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%, with detailed descriptions for scope, filter, and metric. The description adds only a small reinforcement ('pass scope to narrow') that is already implied in the schema's scope description. It does not add new meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb ('Compute'), a clear resource ('transactions'), and enumerates the metric types (sum/average/count/max/min). It explicitly distinguishes from get_credits by saying that is not a transaction, and the phrase 'single metric' differentiates from grouped aggregation siblings like group_by. The purpose is unmistakable.

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

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

Provides explicit guidance on when to use scope (to narrow by accounts/products/date range) and clearly points to get_credits as the alternative for quota/credits questions. It does not mention when to prefer group_by, top_n, compare, or time_series, but the 'single metric' phrasing implies those are for multi-metric or grouped output. That gap keeps it from 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?

The description discloses important behavioral details beyond the annotations, such as credit consumption on first use, caching with free re-fetches, and the presence of a 'summary' field as the source of truth. This is valuable for an agent deciding whether to call the tool.

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

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

The description is concise, with two sentences that lead with the primary action and then provide key follow-up details about caching and the summary field. There is no redundant or vague wording.

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

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

The description covers the core function, credit behavior, and response hint about the summary field. However, it does not specify the format of the category mappings or elaborate on error cases (e.g., document not found). Given the tool's simplicity, this is acceptable but not fully exhaustive.

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

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

The single parameter document_id has a description that explains it comes from convert_statement or list_statements, providing useful provenance. This goes beyond the basic type declaration and helps the agent know exactly what value to supply.

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: running AI transaction categorization on a previously processed document and returning category mappings. It distinguishes itself from sibling tools like convert_statement and list_transactions by focusing on categorization.

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

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

The description does not explicitly state when to use this tool versus alternatives. It implies it should be used after convert_statement (since it requires a processed document), but it does not mention when not to use it or how it compares to list_transactions or other analysis tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds behavioral context about the default scope ('all your completed statements') and that scope can narrow accounts/products and date ranges. This is useful but not extensive; it does not mention output format or edge cases like empty filters. Given the annotation coverage, a 3 is appropriate.

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 long, front-loaded with the core purpose and examples, followed by the scope default and customization. Every sentence earns its place; there is no redundant information.

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

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

For a read-only comparison tool with a rich schema covering all parameters, the description adequately explains what it does and the default behavior. The only minor gap is that it does not hint at the output format (e.g., a side-by-side table), but since there is no output schema, the agent can infer the result from the tool's purpose. The complexity of nested filter/scope objects is well-handled by the schema.

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

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

Schema description coverage is 100%, so all parameters are well-documented in the schema itself. The description adds little beyond the schema, only briefly mentioning 'scope' and the two filters. Since the schema already explains each field and its semantics, the description does not need to repeat them. Baseline of 3 is correct.

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: side-by-side metric comparison of two transaction groups, with concrete examples (category vs category, month vs month). It distinguishes itself from sibling analysis tools like aggregate, group_by, and time_series by explicitly mentioning the comparison aspect. The verb 'compare' is unambiguous.

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

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

The description provides clear context on when to use the tool (comparing two groups) and explains the default scope (all completed statements) with an option to narrow it via 'scope'. However, it does not explicitly mention when not to use it or suggest alternative tools for single-group analysis, which would strengthen guidance further.

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

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

Annotations only indicate readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description adds substantial behavioral disclosure: credits consumed per page, page limit depends on plan, batch mode is admission-only and returns immediately without waiting, output format differences (json inline vs download link), the presence of a summary field as ground truth, language translation rule, and instruction to never echo raw statuses. This goes far beyond what annotations imply and fully informs the agent of side effects and response semantics.

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?

Although long, every sentence carries load-bearing information. It is logically structured: purpose → file reference options (ordered by preference) → batch behavior → output format handling → summary instruction → credits. There is no repetition or filler. The most decision-critical constraints (auto-attachment, batch no-wait) are front-loaded. This is dense but appropriately so for a complex tool.

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

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

The tool has 7 parameters, nested objects, multiple output formats, batch mode, credit consumption, and no output schema. The description covers every operational aspect: how to reference files (single and batch), what the response contains (accounts/transactions/metadata + summary), how to interpret format-specific returns, when to call get_statement, credit costs, and page-limit caveats. Nothing an agent needs to correctly invoke and interpret the tool is missing.

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%, yet the description enriches every parameter beyond its schema entry. For pdf_file it explains 'do not construct this yourself'; for pdf_url it clarifies 'public HTTPS'; for upload_id it ties it to request_upload; for upload_ids it explains batch admission and mutual exclusivity; for output_format it details that json is inline while others yield time-limited links; for pdf it marks it as last resort. This added meaning is critical for correct usage and is not present in 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?

Description opens with a specific verb and resource: 'Convert a bank statement PDF into structured data or a spreadsheet.' It clearly distinguishes from siblings like get_statement (fetching conversion results) and list_statements (listing), and the batch/duplicate admission behavior further differentiates it from single-file conversion. No ambiguity about what the tool accomplishes.

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, nuanced guidance on when to use each file reference method: pdf_file arrives automatically (never encode), pdf_url for public HTTPS, upload_id only when no attachment reference exists, pdf as last resort, and upload_ids for batch (with mutual exclusivity stated). It also tells the agent how to handle results (use get_statement per document_id for batch, present download links normally) and instructs to rely on the summary field as source of truth. This is comprehensive routing and alternative selection.

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 destructiveHint=true and readOnlyHint=false, so the mutation risk is known. The description adds valuable context beyond annotations: it clarifies that the operation is non-destructive to stored data/artifacts, marking the document as dismissed rather than deleting it. This is a meaningful behavioral disclosure that prevents an agent from overestimating the destructiveness.

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

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

Three sentences, each earning its place: the action and scope, the exact usage condition, and the critical non-delete clarification. The most important information is front-loaded.

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

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

For a single-parameter tool with full schema coverage and annotations indicating destructiveness, the description is nearly complete. It explains the effect on list_statements results and clarifies data preservation. It could mention whether the dismissal is reversible, but that is a minor gap given the simplicity of the tool.

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

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

Schema description coverage is 100%, so the single parameter document_id is already fully documented in the schema. The description adds no additional parameter-level detail, but with full coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the verb ('Hide'), the resource (failed/rejected/cancelled documents), and the effect (excluded from future list_statements results). It also explicitly distinguishes itself from a delete operation, which differentiates it from sibling tools like convert_statement or get_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 description gives explicit when-to-use guidance: 'Use this only when the user asks to clear a terminal failed/rejected/cancelled conversion from their history.' It also states what it is not ('This is not a delete'), which helps an agent avoid misusing it as a deletion tool.

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

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

Beyond the annotations (readOnly, non-destructive), the description discloses additional behavioral aspects: it is free (no credits consumed), held-out statements return an error, and omitting originalData scores that dimension 0 rather than fabricating values. These details make the tool's side effects and scoring behavior explicit.

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 substantial but every sentence serves a purpose: stating the function, identifying inputs, specifying constraints, and giving warnings. No redundant filler or repetition. It is information-dense while remaining readable and well-structured.

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 (multiple parameters, nested objects, and nuanced scoring rules), the description covers all essential aspects: the need for published status, the role of originalData, the error behavior, and the free usage. It provides enough context for an agent to call the tool correctly without additional information.

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 covers all parameters (100% coverage), the description adds meaningful semantics: it explains the preference order between statement_id and content_hash, and elaborates on the originalData parameter's purpose and consequences of absence. This goes beyond the schema's basic field descriptions and clarifies the intent behind each key parameter.

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

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

The description uses the specific verb 'Score' and clearly states the resource (parsed bank statement transactions against the benchmark ground truth). It also distinguishes itself by mentioning the accepted identifiers (statement_id or content_hash) and the required transactions, making the tool's purpose unmistakable even without the name.

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

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

The description provides explicit guidance on when to use the tool: only for statements marked published:true in the catalog, and it instructs to read the benchmark://catalog resource first. It also advises preferring statement_id over content_hash and recommends fetching originalData via get_statement, giving clear directions for correct usage.

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 context beyond that: it reports not just the quota but also operational limits (max pages per upload, max upload size, daily spend cap), clarifying what the query returns for batch sizing. No contradictions with annotations.

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

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

The key distinction and purpose are front-loaded in the first sentence. The 'Use for' enumeration and operational-limit details add value for an agent handling natural-language queries, though a couple of phrases could be tightened. No wasted or redundant sentences.

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 zero-input, read-only tool with no output schema, the description fully covers the concept (credits = pages), the exact resource (quota, not transactions), and common use cases. An agent can confidently decide when to invoke this tool and what to expect from 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?

The schema has zero parameters, so there is nothing to document. Per the baseline for 0-parameter tools, the description did its job by explaining the semantics of the returned data (credits, limits, conversion to pages) rather than any input 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 states a specific resource ('remaining Bankstatemently credits — the processing quota') and explicitly disambiguates it from 'credit/debit transactions'. The '1 credit = 1 page' exchange rate and the mention of plan operational limits make the tool's scope unmistakable, even distinguishing it from sibling tools like list_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 gives explicit natural-language triggers ('Use for: how many credits do I have, remaining pages, plan limits, quota, how many pages can I upload') and a clear when-not ('NOT credit/debit transactions'). It stops short of naming an alternative sibling tool for transaction queries, but the exclusion is sufficient.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: json returns inline data, other formats return time-limited links, the summary field is the source of truth, translation rules, and data_mode projections. No contradictions with annotations.

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

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

The description is long but every sentence carries essential information. It front-loads the primary purpose and usage context, then details format and data_mode behaviors. While it could be tightened, the complexity of the tool justifies the length, and there is no 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?

There is no output schema, so the description must explain return values. It does: json returns inline data, others return download links, summary is always present. It covers data_mode projections and pagination parameters are in the schema. However, it doesn't explicitly discuss pagination behavior (e.g., when to use offset), relying on the schema's limit/offset descriptions, which is a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds beyond schema: limit defaults (500, capped at 2000, 500 for original), offset usage, data_mode defaults per format, and the interaction with output_format. It clarifies the 'original' mode's role in evaluate_benchmark, which the schema hints at but doesn't fully explain.

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 fetches 'full converted data for a previously processed document,' distinguishing it from convert_statement (which processes) and list_statements (which lists). It also explicitly positions it as the follow-up after a processing status, giving a precise verb and resource.

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 provides explicit when-to-use guidance: 'Use this after convert_statement returns a processing status, or to re-fetch results.' It also details the workflow for evaluate_benchmark (fetch original data) and explains format-specific behavior, giving the agent clear context for choosing this tool over siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds behavioral context beyond that: 'Results are per-currency' and the default scope behavior (all completed statements). It does not describe output shape, but given the read-only nature, this is acceptable.

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 redundant words. The primary purpose is front-loaded, and the scope nuance is added in the second sentence. Every clause contributes value.

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

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

For a tool with 4 parameters including nested objects (scope and filter) and no output schema, the description is somewhat thin. It mentions scope but not filter, which is a significant narrowing mechanism. It also doesn't hint at the return format beyond per-currency grouping. Given the complexity, more context about filter and output would be helpful.

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 every parameter is documented in the schema. The description adds minimal new meaning—it restates the dimension list and scope behavior already present in the schema. It does not clarify how metric interacts with dimension or how filter works, but since schema covers parameter details, a baseline 3 is appropriate.

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

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

The description states a specific verb ('group') and resource ('transactions'), enumerates the valid dimensions (month/category/merchant/account/currency) and metrics, and notes the per-currency result behavior. This clearly distinguishes it from sibling aggregation tools like aggregate or time_series, which have different grouping semantics.

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 useful scoping guidance ('Scope defaults to all your completed statements; pass "scope" to narrow...'), but it does not explicitly mention alternatives or when to prefer a sibling tool. It also omits the filter parameter entirely, which is another way to narrow results, so an agent may not realize filter exists.

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 annotations already declare readOnlyHint, making it safe. The description adds details about pagination and optional status filtering, going beyond the annotations to describe expected 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 a single concise sentence that directly conveys the purpose and key features without unnecessary words.

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

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

Given the absence of an output schema and the simple listing nature of the tool, the description sufficiently sets expectations. It does not detail return format, but that is not critical for a browse operation.

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 covers all parameters with descriptions (limit, offset, status). The tool description only restates pagination and status filter, adding no new semantic information 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 action (Browse) and resource (previously converted bank statements), and also mentions pagination and status filter, distinguishing it from other tools like convert_statement or get_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 description implies usage for listing previously converted statements, which differentiates it from converting or retrieving single statements. It does not explicitly name alternatives, but the context is clear enough.

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 as read-only and non-destructive. The description adds valuable behavioral detail: a 50-row cap, that scope defaults to all completed statements, and that responses include the evaluated scope (document count and covered date range) plus a content_hash per row for citation. This goes beyond the annotations to describe response structure and limitations.

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 compact given the tool's complexity, with five sentences that each add value: definition, core action, scope behavior, response metadata, and an alternative tool pointer. It is front-loaded with purpose and avoids repeating schema details. Slightly dense but well-organized and efficient.

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

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

For a tool with no output schema, the description partially compensates by stating the 50-row cap, the response's scope metadata, and the content_hash citation feature. It does not enumerate all return fields or pagination behavior, but the schema covers input thoroughly, and the description gives enough for an agent to call it correctly and interpret results at a high level.

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 every parameter has a description. The tool description adds context about scope defaults and the return format, but it does not explain individual parameter semantics beyond the schema. It reinforces that 'scope' narrows to accounts/products and date ranges, but the schema already conveys this. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Return'), a clear resource ('a filtered list of transactions'), and a scope ('across your converted statements'). It defines what a transaction is (one line on a statement) and differentiates itself from get_credits by naming the sibling explicitly. The purpose is unmistakable and distinct from siblings like list_statements or 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 explicitly directs the agent to use get_credits for credit/quota questions, and clarifies that scope defaults to all completed statements with optional narrowing. It does not exhaustively cover all sibling distinctions (e.g., list_transfers), but the guidance is clear and actionable for the most common alternative.

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 readOnlyHint and destructiveHint annotations, the description details the tool's behavior: it returns matched pairs, optionally generates an 'unmatched' bucket when amountMin is set, and reports the match window used. This goes well beyond annotation-only disclosure.

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

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

The description is well-structured but somewhat verbose. It repeats the core definition of a transfer several times and could be tightened without losing meaning. However, the information is logically organized and each sentence serves a purpose, so it remains easy to follow.

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

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

Given the complexity of the matching logic and the absence of an output schema, the description fully covers what the tool returns: matched pairs, the optional unmatched bucket, and the match window. It also addresses edge cases (payments to outside parties) and provides context relative to sibling tools.

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?

Both parameters (scope and amountMin) are thoroughly explained in the description. The schema provides detailed descriptions for nested fields (accounts, dateRange), and the description complements with usage semantics such as 'Scope defaults to all your completed statements' and 'Omit amountMin for the ordinary reconciled-pairs answer.' Coverage is complete.

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's purpose: "Match transfers between your own accounts." It clearly distinguishes transfers from payments to outside parties and contrasts with list_transactions, making the tool's role unambiguous.

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

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

The description provides direct usage guidance: "THE way to answer any 'was money moved between my accounts' / 'did I transfer X' question" and explicitly warns against using list_transactions. It also explains when to use amountMin versus omit it, giving clear conditions for each usage mode.

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

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

The description discloses key behaviors beyond the annotations: it states that re-calling updates the existing rating without clearing feedback, that the response includes the stored rating state, and that every response contains a 'summary' field to use as the single source of truth. This adds significant context that annotations do not provide, and there is no contradiction.

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

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

The description is compact, front-loaded with the core purpose, and each sentence adds value—covering update semantics, return behavior, and the summary field. No redundancy or filler; it is efficiently written.

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 7 parameters but only 2 required, and no output schema, the description adequately covers what the agent needs: it explains the response contains the stored rating state and a 'summary' field, and clarifies update semantics. This is sufficient for an agent to call it correctly without further lookup.

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 the baseline is 3. The description adds some context about feedback being conditionally accepted and the update behavior, but most parameter details are already in the schema. It does not meaningfully compensate beyond what the schema already explains, so a 3 is appropriate.

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

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

The description states a specific verb and resource: 'Report how well a previously converted bank statement was parsed' and clarifies it involves submitting a rating. It distinguishes from siblings by noting there is no separate tool to read your rating back, making its role unique among the listed tools.

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

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

It gives clear context on when to use it (for rating a conversion) and clarifies that calling again updates the rating, which is useful for repeated submissions. It does not explicitly mention when not to use it or name alternatives like evaluate_benchmark, but the description implies the specific scenario (rating a converted statement) sufficiently.

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 minimal annotations, the description discloses that the URL and token are single-use and expire quickly, that no credits are consumed by this step, and that a failed PUT must not be retried against the same URL. This gives agents clear expectations about the operation's side effects and limitations.

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 nearly every sentence carries operational value, including the playbook, error handling, and batching instructions. It is organized and readable; the length is justified by the complexity of the workflow.

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?

Even though there is no output schema, the description fully covers the expected response fields (upload_id, upload_url, and batches of uploads), the exact HTTP PUT step, the relationship to convert_statement, and failure handling—so an agent has everything needed 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?

Though there is only one parameter, the description significantly enriches the schema by explaining what count does, why batching is preferable, what the uploads response array contains, and what occurs when count is omitted.

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—minting a single-use upload URL for a conversation-attached PDF—and explicitly distinguishes this tool from alternatives by saying to use it only when no pdf_file/pdf_url equivalent exists.

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 explicit when-to-use and when-not-to-use guidance, a numbered playbook, retry rules, batch usage via count, and troubleshooting steps for blocked outbound requests. It also names the follow-up tool, convert_statement, and explains how upload_id must be used.

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

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

Annotations already indicate readOnlyHint true and destructiveHint false. The description does not add information about side effects, authentication requirements, rate limits, or other behavioral aspects beyond what annotations provide. It simply describes the computation, which is consistent with being read-only.

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, consisting of two sentences that efficiently convey the core functionality and a key default behavior. It is well-structured and to the point, without unnecessary detail.

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

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

The description gives the essential idea but omits details about the output format (e.g., the structure of the time series result) and does not mention the filter parameter, which is part of the input schema. Given the tool's complexity and lack of an output schema, more context would be helpful for a complete understanding.

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 provides descriptions for all parameters. The description adds value by explaining that scope defaults to all completed statements and that it can narrow by accounts/products or date range, but this is a minor enhancement since the schema already describes scope. Other parameters like filter are not mentioned in the description, so it does not significantly improve parameter understanding.

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, and notes it is useful for trends. This is specific and distinguishes it from other aggregation tools by focusing on temporal bucketing.

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 some usage context (e.g., scope defaults to all completed statements, can narrow by accounts/products or date range) but does not explicitly compare with sibling tools like aggregate, group_by, or compare. It mentions usefulness for trends but lacks guidance on when to prefer this over alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral details: descending order, per-currency handling for monetary metrics, and the default scope. These go beyond what annotations provide and help the agent understand the tool's output semantics.

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

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

Two sentences with no filler. The core purpose is front-loaded, followed by the per-currency nuance and the default scope behavior. Every word earns its place, and the structure is highly efficient.

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

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

Given the tool's complexity (5 parameters, nested objects, enums) and the absence of an output schema, the description is concise but covers the key behavioral nuances: default scope and per-currency handling. The schema fills in parameter details, so the description is sufficient for an agent to call the tool correctly, though it could mention how multiple currencies interact in non-monetary metrics.

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%, meaning all parameters already have detailed descriptions in the schema. The description mentions 'scope' but only restates what the schema says about narrowing by accounts/products or date range. It adds no new semantic meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and resource: 'Return the top N groups ranked by metric (descending)'. It specifies the grouping concept and adds a distinctive per-currency behavior for monetary metrics. This distinguishes it from siblings like aggregate or group_by, which focus on aggregation without the top-N ranking emphasis.

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 a clear default scope ('all your completed statements') and how to narrow it via the 'scope' parameter. However, it does not explicitly compare this tool to alternatives like time_series or compare, nor does it state when to prefer top_n over them. The intended use case (top N ranking) is implied but not contrasted with siblings.

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