ExpenseBot

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

The description discloses key behavioral facts beyond the annotations: it 'writes directly to the user's expense spreadsheet after confirmation' and explains the client advance handling (reuses/creates the canonical client group, applies 'Cash advance received', stores as negative expense). This adds meaningful context that annotations (only readOnlyHint/destructiveHint flags) do not cover.

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 highly structured and front-loaded: the first sentence states purpose, then each use case is a clear paragraph, followed by explicit exclusions and an alternative. Every sentence serves a purpose (guidance, exclusion, or alternative) and there is no redundant 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?

Given the tool's complexity (two distinct modes, 12 parameters), the description is remarkably complete. It covers both modes, exclusions, alternatives, and parameter relationships. Since an output schema exists, return-value descriptions are unnecessary. This is a model example of a comprehensive tool description.

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

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

Although schema coverage is 100%, the description adds crucial cross-parameter semantics that the schema alone doesn't convey. It explains that isClientAdvance requires clientName and does not require category, that merchant is derived from clientName for advances, and that total is stored as negative for advances. This helps the agent correctly combine parameters.

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 immediately states the tool's exact function: 'Add an expense without a receipt, or record money a client provided in advance for expenses.' This is a specific verb+resource with two clearly distinguished modes. It also differentiates from siblings by explicitly naming the 'Manual expense link from get_spreadsheet_url' as an alternative and listing excluded transaction types (vendor refunds, reimbursements, etc.).

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 concrete when-to-use guidance for both modes: 'For an ordinary expense, call list_categories first and provide a configured Expense Account' and 'For a client advance, set isClientAdvance=true and clientName.' It explicitly states when NOT to use it ('never for vendor refunds, reimbursements, earned fees, retainers, or generic deposits') and points to an alternative tool when a reviewed form is needed.

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 write/non-read-only (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds behavioral details about the side effect ('Writes to the Income tab'), the default behavior for omitted category ('defaults to Service income'), and the rejection of unknown categories. These go beyond the annotations and schema.

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-loads the main purpose, and each sentence adds essential information: what it does, where it writes, when to use it, and a required prerequisite. No word is wasted.

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 write tool with 12 parameters, the description covers the most important contextual aspects: manual entry, target location, the distinction from auto-detection, and the category prerequisite. Since an output schema exists, return-value documentation is not needed. The inclusion of edge-case behavior (default category, rejection) completes the picture for correct invocation.

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 92% schema coverage, the parameter descriptions themselves cover most fields. The tool description adds value by explaining the category parameter's default and validation ('an omitted category defaults to Service income and an unknown category is rejected') and by giving examples of payment method values ('cash, check, Stripe payout'). This is meaningful semantic enrichment 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 uses the specific verb 'Log an income entry manually' and identifies the resource ('Income tab of the user's expense spreadsheet'). It clearly distinguishes this tool from auto-detection via Gmail/Plaid and from the sibling tools add_income_from_csv and add_income_from_file by emphasizing 'manually.'

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 clear when-to-use context: 'Useful for income that isn't auto-detected from Gmail or Plaid.' It also provides a concrete prerequisite: 'Call list_income_categories first.' However, it does not explicitly name sibling alternatives or state when not to use them, 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?

The description fully discloses the tool's behavior beyond annotations: 'NOTHING is saved in step 1', 'preview expires after 15 minutes', 'expired or unknown previewId never writes', and 'Flagged duplicates are skipped unless the user explicitly keeps them'. It also details the parsing behavior (platform detection, fee handling, refunds).

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 ~150 words but organized by steps, with the main purpose front-loaded. Every sentence contributes essential information—no fluff or repetition. The two-step contract is outlined clearly, making it easy for an agent to parse.

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 (9 parameters, two-step workflow, duplicate handling), the description covers every stage: parsing, preview, confirmation, edge cases (expiry, unknown IDs), and post-confirm actions. The output schema exists, but the description still explains what to show the user, making it 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?

Although the schema already describes all parameters (100% coverage), the description adds vital context: how csvContent can be a file reference, the role of selectedIndexes/keepBothIndexes/rowEdits/tag/bulkNote in step 2, and the step 1/step 2 split for previewId and confirm. This goes 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 opens with a specific verb and resource: 'Import income from a CSV/TSV/text export' and lists concrete sources (Stripe, PayPal, etc.). It also distinguishes itself from the sibling add_income_from_file by noting the 'same two-step contract' but for this file format, making its scope clear.

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 an explicit two-step walkthrough: 'STEP 1 call with csvContent and WITHOUT confirm' and 'STEP 2 call again with confirm: true and the previewId'. It also clarifies when to use the tool (for CSV/TSV/text exports) and what to do after success (show spreadsheetUrl and reviewIncomeUrl), which implicitly rules out alternatives like manual add_income.

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 critical behaviors: step 1 saves nothing, duplicates are flagged and skipped unless keepBothIndexes is passed, previews expire after 15 minutes, and unknown preview IDs never write. This is rich, non-obvious context that annotations alone cannot convey.

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 front-loaded with purpose, then structured by step (STEP 1, STEP 2), and covers essential caveats (expiration, duplicates, URLs). Every sentence adds value for a complex two-step tool; it could be trimmed but the detail is justified.

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 (10 params, two-step flow, output schema), the description is notably complete. It explains inputs, step behavior, return values (previewId, row counts, totals, duplicates, rejected rows, spreadsheetUrl, reviewIncomeUrl), error conditions (expired preview), and post-confirm actions. 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 baseline is 3. The description adds essential two-step semantics: which parameters apply to step 1 vs step 2, the meaning of omitting confirm, how tag pre-fills vs applies, and how selectedIndexes/keepBothIndexes control writes. This goes beyond the schema's per-parameter 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 imports income from attached screenshots, images, or PDFs, with specific file types and size limit. It distinguishes from sibling tools by explicitly excluding CSV (which has a separate add_income_from_csv sibling) and manual entry (add_income).

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 detailed when-to-use guidance via two-step workflow, explaining step 1 (parse/preview) and step 2 (confirm write), and explicitly directs users to a different tool (get_spreadsheet_url) for visually complex reviews. However, it does not explicitly name sibling alternatives for CSV or manual entry, though the file-type scope implies them.

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 a key behavioral side effect beyond annotations: 'The trip writes a row to their expense spreadsheet with the calculated dollar value.' It also reveals a dependency on user configuration (mileage rate and unit), which informs the agent about potential failure modes. This adds genuine context beyond the readOnlyHint/destructiveHint 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 five sentences, longer than strictly minimal, but every sentence carries purpose: audience, prerequisite, side effect, and alternative tool usage. It is front-loaded with the core action and does not waste words, though the final sentence's list of exclusions is a bit long.

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

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

With an output schema present, the description does not need to explain return values. It covers the tool's action, prerequisites, side effects, and alternative use cases, which is sufficient for an agent to decide and invoke it correctly. Minor gaps like error handling are not necessary given the output 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?

The input schema already provides descriptions for nearly all 9 parameters (89% coverage), including 'distance' and 'roundTrip.' The description adds no parameter-level detail beyond what the schema states; it reiterates that distance is in the configured unit, which is already in the schema. 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 opens with 'Log a business mileage trip in ExpenseBot,' clearly stating the tool's specific action and resource. It further distinguishes from siblings by naming 'get_spreadsheet_url' as the alternative for Google Maps route calculation and other advanced features, making the purpose unambiguous.

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

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

Provides explicit usage guidance: it names the target audience (realtors, consultants, contractors) and states a prerequisite (configured mileage rate). It also explicitly says when NOT to use this tool, directing users to 'the Mileage and travel link from get_spreadsheet_url' for Google Maps, mileage settings, repeated trips, import, per diem, or visual review.

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 covered. The description adds behavioral context about what it checks (compliance issues) and that it operates on an existing report, going slightly 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?

Two sentences, front-loaded with the primary use case, followed by concise exclusions. Every word earns its place, with no 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 presence of an output schema and rich annotations, the description fully covers when to use and what the tool does. It also addresses edge cases (not as preflight) and is complete for the tool's complexity.

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

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

Schema description coverage is 100%, and the schema provides detailed descriptions for both parameters, especially userRequest. The tool description adds minimal parameter-specific detail beyond what the schema already states, so 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 clearly states the tool checks an existing report for compliance issues like missing business purpose or policy violations. It distinguishes itself from siblings by explicitly excluding other workflows and contrasting with fix_compliance.

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 conditions ('only when the user explicitly asks'), exclusions (creating/excluding/sharing/billing), and a hard rule against automatic invocation. This is textbook usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context: it searches the public knowledge base, returns a confidence-scored answer plus related questions, and works with or without authentication. This goes beyond the annotations by clarifying auth independence and output 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?

Two sentences, front-loaded with the primary purpose, and no wasted words. Examples are inline and add value.

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

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

For a simple read-only tool with one parameter and an output schema (not shown but signaled), the description fully covers purpose, auth behavior, and return type. Enough information for an agent to invoke it correctly.

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

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

The single parameter 'feature' is fully described in the schema, and the description's examples reinforce the expected value without adding new semantic detail. Schema coverage is 100%, so the baseline of 3 applies.

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 checks whether ExpenseBot supports a specific feature, with examples ('does ExpenseBot support X', 'can it integrate with Y'). It distinguishes itself from sibling tools like search and search_knowledge by focusing on feature support and returning a confidence-scored answer.

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 example queries and states it searches the public knowledge base, giving clear context for when to use it. It does not explicitly mention alternatives or exclusions, but the feature-checking purpose is unambiguous enough to guide 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 readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context beyond annotations: it states this is an advice tool, mentions jurisdiction-dependence, and clarifies scope (deductibility rules only, not refunds). This adds useful behavioral context.

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

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

The description is three sentences, front-loaded with the core purpose, followed by examples and an exclusion with alternative. Every sentence earns its place; no fluff or redundancy.

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

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

The tool has an output schema, annotations, and a description that covers purpose, usage, and exclusions. It doesn't explain return values (but output schema exists) or error cases, but for a relatively simple read-only advice tool, the description is complete enough.

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 only 33% (query is described; category and merchant are not). The description does not compensate for the undocumented parameters—it only gives examples for 'query' but never explains 'category' or 'merchant'. Given the low coverage, the description should have provided more parameter context.

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: looking up tax deductibility for expense types/purchases. It uses a specific verb ('Look up'), names the resource ('tax-deductible... based on user's country/jurisdiction'), and explicitly distinguishes from siblings by calling itself a 'deductibility *advice* tool' with concrete examples.

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 usage guidance: use for deductibility questions (with examples), and explicitly says NOT to use for tax refunds, directing to get_spending_summary instead. This provides clear when-to-use and when-not-to-use context.

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

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

Description goes far beyond annotations, disclosing the preview/confirm flow, premature confirm conversion, undo support, applied/conflicted/failed counts, Notes field preservation, skip behavior for formula notes, idempotency via operationId, and optimistic concurrency via expected values. No contradiction with annotations (readOnlyHint false, destructiveHint true).

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 lengthy, every sentence adds unique operational value. Structured logically from purpose to examples to workflow to constraints to exclusions. No redundancy; each clause 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 complexity (6 params, nested objects, output schema, preview/confirm protocol), the description covers workflow, safety checks, edge cases (formula notes, Notes preservation), limits (100 rows), and fallback. Output schema exists, so return values need not be described. Fully adequate for invocation.

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 83%, yet description adds substantial meaning: operationId idempotency generation, confirm:true conversion, attendeeMode add vs replace semantics, change type vs matching value field requirement, and selection expected values for concurrency. It enhances all parameters beyond raw schema definitions.

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 names a specific verb (correct), resource (expenses), and scope (exact bounded set), and distinguishes itself from siblings by listing exclusions (no duplicate omission, no amount/date changes, no broad Calendar matching). Examples further clarify intent. It clearly differentiates from update_expense and other expense 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?

Explicit workflow: use search_expenses first, then pass expenseId values. Clear when-not-to-use: unsupported or >100-row cleanup directs user to an external URL. Also states constraints (attendee names must come from user, never infer) and disallowed operations, providing strong usage guidance.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, but the description adds rich behavioral detail: it returns a report summary, link, applied filters, and a Report Wizard fallback; explains how scoping to existing groups handles already-assigned expenses; and describes duplicate-report avoidance behavior. No contradiction with annotations.

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

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

Every sentence in the description carries operational value: purpose, tag guidance, exclusion semantics, return contents, scoping behavior, duplicate handling, and explicit negative usage. It is front-loaded with the core function and structured logically from creation behavior to edge cases.

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 8 parameters, complex date-range variants, and output schema present, the description still covers the essential decision points: when to call list_tags, how to interpret personal exclusions, what to return, and what not to do. It is complete for an agent to invoke correctly without additional lookups.

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 88% and parameter descriptions are already solid, but the description adds crucial semantics: explains what 'tags' actually represent, clarifies excludePersonal covers both Tag and Expense Category, and describes how scope affects matching expenses. This goes well beyond the schema's structural definitions.

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 'Create an expense report' and immediately specifies the resource and the range of valid input dimensions (date, client, project, trip, category, merchant). This clearly differentiates it from sibling tools like export_report, share_report, and get_report_details.

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

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

Explicitly instructs when to call list_tags if the group is unclear, provides a concrete example (August except personal -> excludePersonal=true), and directly states what not to do ('do not call check_compliance, get_report_details, or tax/deductibility tools') unless explicitly requested.

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, but the description adds valuable context: the PDF is short-lived, the report must be 'exact authorized', and the in-app link is 'highlighted'. This clarifies the tool's output limitations without contradicting annotations.

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

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

Two well-structured sentences: the first states the core action, the second gives usage guidance. Every word earns its place; no fluff or repetition.

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 single parameter, high schema coverage, and existing output schema, the description fully covers the tool's purpose, usage boundaries, and prerequisite. It lacks nothing essential for an agent to select and invoke it 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?

Schema coverage is 100% and the description repeats that reportId comes from list_reports, adding little beyond the schema. The phrase 'one exact authorized expense report' adds some nuance but is mostly behavioral context rather than parameter syntax.

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 ('Get') and resource ('expense report'), specifying exactly what is returned: a short-lived direct PDF download and an in-app report link. It distinguishes itself from sibling tools by contrasting with the in-app report for other formats.

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

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

Explicitly instructs when to use this tool (for PDF download and in-app link) and when to use the in-app report instead (for CSV, XLSX, receipt ZIP, comments, etc.). Also provides a prerequisite: 'Use list_reports first to find the reportId.'

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 valuable behavioral context: it warns against inventing or modifying the trailing portion of the id, explains the id format rules, and states that the tool returns full text content plus metadata for citation. This goes beyond the annotations and helps avoid misuse.

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

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

The description is moderately detailed but well-structured with bullets for the id types. Every sentence serves a purpose: stating the function, explaining formats, giving caution, and indicating return content. It is not excessively verbose, though it could be slightly tighter by merging the caution with the examples.

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 only one parameter, an output schema exists, and the annotations provide safety context, the description is complete. It explains how to construct/obtain the id, what the id encodes, and what the return value contains (full content + metadata). No additional context is needed for correct invocation.

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 covers the id parameter fully (pattern and description), so the baseline is 3. The description adds further meaning by providing concrete examples for both expense and report id formats, explaining the encoding ('expense:<rowNumber>' vs 'report:<reportId>'), and reinforcing the need to use exact ids from prior calls. This additional guidance compensates beyond schema coverage.

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

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

The description clearly states the tool fetches full details for a specific item returned by `search`, using a specific verb and resource. It distinguishes itself by explaining the two id formats (expense and report) and emphasizing that the id must be used exactly as returned, which clarifies its scope as a unified fetch 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 gives clear context on when to use the tool: after a `search` or `list_reports` call. It instructs the agent to use the id exactly as returned and not to modify it. However, it does not explicitly mention alternatives like `get_expense_by_id` or `get_report_details`, 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.

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

The description adds behavioral context beyond the annotations by specifying that this is a bulk operation affecting all flagged expenses in a report. This complements the destructiveHint=true already provided by annotations, though it doesn't detail irreversibility or effects on un-flagged items.

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

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

A single sentence that is front-loaded with the core action ('Bulk-fix compliance issues') and includes an illustrative example without any wasted words.

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

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

Given that an output schema exists and annotations already declare destructive/write behavior, the description provides enough context for a straightforward bulk-fix tool. It does not address edge cases or overlap with siblings, but the example and schema make the primary intent clear.

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 only 33% (only 'value' has a description). The example clarifies that 'value' could be a business purpose and suggests how 'action' is used, but it does not elaborate on 'set_category' or 'add_tag' or the role of 'reportId'. Thus it partially compensates for the low coverage.

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

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

The description clearly identifies the tool's function: bulk-fixing compliance issues in a report, with a concrete example for clarity. The verb 'bulk-fix' distinguishes it from read-only 'check_compliance' and individual correction tools like 'correct_expenses'.

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 term 'bulk-fix' provides clear context for when to use this tool (for applying a uniform fix across multiple expenses in a report). However, it does not explicitly contrast with sibling tools like 'correct_expenses' or 'update_expense', nor does it state exclusions, so it stops short of full guidance.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description explicitly states it never scans cards, changes review decisions, or adds rows. It also discloses that it returns the most recent items first with a default limit of 25, providing useful behavioral context not evident from annotations alone.

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 four purposeful sentences that front-load the main function. Every sentence adds value—purpose, examples, output behavior, and read-only guarantee—with no wasted words.

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

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

The description covers the tool's purpose, example use cases, output ordering, parameter behavior (dateRange, limit), and safety guarantees. Given the rich annotations, complete parameter schema, and presence of an output schema, the description is fully sufficient for an agent to select and invoke the tool correctly.

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

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

While the schema covers all three parameters (limit, dateRange, clientEmail), the description adds practical meaning by noting the default limit of 25 and that dateRange narrows results. This goes beyond the schema descriptions, which only state types and basic formats, so it earns a score above the baseline.

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 lists card refunds, cashback/rewards, and statement credits already recorded by ExpenseBot. It provides specific examples of user queries, making the purpose very clear. However, it does not explicitly distinguish itself from sibling tools like get_income_summary or get_spending_summary, so it falls slightly short of a 5.

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 clear context for when to use the tool, with example queries like 'did my refund come through' and 'show my statement credits'. It implicitly communicates this is for viewing recorded credits/refunds, but it doesn't explicitly state when not to use it or point to alternative tools, so it lacks exclusions.

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

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

Adds substantial behavioral context beyond the annotations: operation takes 10-30 seconds, runs as a background job polled automatically, and the return shape includes sampleMeta.isTruncated to indicate whether the agent saw the full dataset. These details are crucial for agent expectations and are not present in the readOnly/destructive hints.

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 packed with useful information: purpose, use cases, latency/background behavior, and return shape with truncation indicator. There is no fluff, and the most actionable 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 tool with two parameters (one required), a rich schema, and an output schema present, the description covers all necessary context: what it does, when to use it, how long it takes, how the background job works, and what the response contains including the truncation caveat. Nothing essential 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?

The input schema already provides 100% coverage of both parameters with detailed descriptions, including the dateRange variants and their meanings. The tool description does not add additional parameter-level semantics beyond what the schema offers, 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 action ('Run deeper, multi-step analytics') on a clear resource (the user's expenses) with examples of the exact question types it handles ('why did my spending increase', 'compare Q1 vs Q2'). The 'deeper, multi-step' phrasing distinguishes it from sibling summary tools like get_spending_summary or get_pnl.

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 gives when to use it: 'Use for explanatory questions like...' The examples clarify the intended scenarios. It does not explicitly name alternatives or state when not to use it, but the 'explanatory questions' guidance signals the boundary well enough to warrant above-average marks.

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 valuable context by explaining the return format (headers + values + labeled map) and clarifying that expenseId is the exact Receipt ID in Column Q. No contradiction found.

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 tight sentences: purpose, output format, and safety note. No redundant or filler content; every sentence contributes to understanding.

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 simple and the output format is described, so the existing output schema is sufficient. Minor gap: the schema lists zero required parameters but the description implies at least one must be supplied, without explicitly stating this constraint.

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% and both parameters have detailed descriptions. The description adds the relationship between the two parameters (alternative lookup keys) but little beyond what the schema already 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?

The description uses a specific verb+resource ('Fetch a single expense row') and identifies two precise lookup methods (sheet row number or ExpenseBot expenseId). This clearly distinguishes it from sibling tools like search_expenses or get_expense_splits.

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

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

The description implies usage when a user mentions a specific expense and you need its details. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.

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 meaningful behavioral context beyond annotations: it explains that the tool returns the single parent payment with nested allocation lines, that split lines are never counted as separate expenses, and that the operation is read-only. It also mentions the Review workspace as the editing location, adding context without contradicting the annotations.

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

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

The description is well-structured and front-loaded with the main purpose, followed by critical behavioral detail and useful examples. Every sentence adds value, and the examples are concise and relevant. The length is appropriate for the tool's complexity.

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

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

Given the tool's complexity (5 optional parameters, nested objects, and an output schema), the description is comprehensive. It explains the core concept of split expenses, the parent/allocation relationship, and provides examples. The output schema handles return-value details, so the description effectively covers the necessary context for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, with all five parameters having detailed descriptions in the input schema. The description itself does not add parameter-specific semantics but reinforces the overall purpose. It meets the baseline for high schema coverage without providing extra value beyond what the schema already documents.

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

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

The description uses a specific verb ('show') and clearly identifies the resource ('how an expense was split across categories, clients, properties, or business vs personal portions'). It differentiates from siblings by emphasizing that it returns the parent payment with nested allocation lines and that split lines are never counted as separate expenses, distinguishing it from tools like get_expense_by_id or search_expenses.

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 example user queries that indicate when to use the tool ('how is that expense split', 'what was the business portion of that bill'). It also implies a usage boundary by noting that splits are edited in ExpenseBot's Review workspace, indicating this tool is for viewing only. However, it does not explicitly name alternative tools or state when not to use it.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds valuable context: it enumerates what income categories are covered, notes that security deposits and refunds are excluded from taxable totals (matching T6 routing), and describes the return shape. This gives the agent a clear picture of the tool's behavior and constraints without contradicting annotations.

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

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

The description is moderately long but every sentence earns its place: core function, detailed coverage, exclusions, example queries, comparison support, and return structure. The main purpose is stated first, and the structure is logical and scannable. No filler or redundancy.

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

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

Given the tool's complexity (4 parameters, no required fields, output schema present), the description covers all essential context: what data it returns, which income sources are included, exclusions, example queries, and comparison capabilities. The output schema's existence reduces the need to detail return values, but the description still mentions the return shape, making it complete for an agent to select and invoke 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 already provides 100% description coverage for all parameters, so the baseline is 3. The description enriches parameter understanding by providing natural language examples that map to parameter usage (e.g., 'income YTD' implies a relative dateRange, 'income by source' maps to groupBy) and explicitly mentions supported comparison phrasings. This goes beyond the schema but doesn't fully detail parameter syntax.

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: 'Get income totals, breakdowns, and analytics from the Income tab.' It enumerates specific income types (Schedule C/T2125, Schedule B drill-in, rental income) and breakdown dimensions (source, payment method, category, month, tag), which distinguishes it from sibling tools like get_spending_summary or get_pnl by explicitly scoping to the Income tab and income-specific analytics.

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 multiple concrete example queries ('income YTD', 'income by source', 'rental income by property') and states supported comparison phrasing (YoY, MoM, QoQ), which implies when to use the tool. However, it does not explicitly state when not to use it or name alternatives, so it misses the full 'when/when-not/alternatives' bar.

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 annotation, the description discloses critical behavioral context: pending results are normal and must not trigger duplicate resubmission, returns specific verdicts and counts, and instructs to show spreadsheetUrl and reviewExpensesUrl on completion. This is rich, action-relevant transparency.

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 at about 120 words and each sentence adds distinct value: purpose, usage, timing, behavior, and alternative. It is slightly long relative to the simplest cases, but the complexity of the polling behavior justifies the length.

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 an output schema and complex async behavior, the description covers the full lifecycle: when to call, how to use parameters, what to expect (pending), what to avoid (duplicates), what to show the user, and when to use a different tool. This is complete for the tool's complexity.

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

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

The schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The description reinforces the 'exact ID' usage and mentions polling interval/time allowance, but does not add meaningfully new parameter semantics 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 opens with a specific verb and resource: 'Check the authoritative final outcome of a receipt image/PDF batch'. It clearly distinguishes itself from siblings by naming submit_receipt as the precursor and get_scan_status as the alternative for Gmail scans.

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

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

Explicitly states when to call: after submit_receipt returns submissionId, using the polling interval and time allowance from that response. Also gives an exclusion: 'This is for uploaded receipts; use get_scan_status for Gmail scans.' This is strong usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds valuable behavioral context: country-aware IRS/CRA rates for deduction estimates, the exact return shape with optional fields (deductionEstimate, comparison, sampleMeta), and support for relative comparison phrases. 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 a compact, front-loaded paragraph that wastes no words. It quickly states the domain, lists key breakdown dimensions, includes example queries, mentions comparison support, and specifies the return structure — all in a clear, scannable format.

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 complex dateRange schema is fully explained in the input schema, and the description covers the remaining context: purpose, deduction logic, grouping options, and return format. Given the tool's complexity and the provided output schema, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% with detailed parameter descriptions, so baseline is 3. The description adds extra semantic value by providing realistic natural-language examples for the query parameter and mentioning comparison phrasing which relates to how dateRange can be expressed. This nudges it above baseline.

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

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

The description clearly states the tool provides mileage analytics with totals, breakdowns by month/client/purpose/category, and deduction framing. This distinguishes it from sibling tools like get_income_summary or get_spending_summary, and concrete examples ('mileage this year', 'miles driven for Acme') make the purpose unmistakable.

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

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

The description gives strong contextual usage guidance through example queries and explicitly notes support for YoY/MoM/QoQ comparison phrasing. It does not explicitly name alternatives or state when NOT to use the tool, but the domain-specific wording makes appropriate use clear.

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=true, destructiveHint=false), the description adds useful behavioral context: defaults to last completed month, figures come from user's recorded data, and advisory notes are estimates not tax advice. It does not contradict 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 efficient and front-loaded, with the main function stated first. The example queries add length but are valuable for disambiguation. The advisory note is important. No wasted sentences, though examples 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?

For a tool with an output schema, the description appropriately covers what the tool returns (summary of income, spending, net, categories, merchants, alerts), default behavior, data provenance, and limitations. It is complete for the tool's complexity and lacks significant gaps.

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

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

Schema description coverage is 100% for both parameters. The description restates the default behavior already in the parameter schema ('Defaults to the last completed month') without adding extra meaning beyond the schema. It does not elaborate on clientEmail usage beyond what's 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?

The description clearly states the tool's function: 'Month-end summary of the user's books for one calendar month' with specific components (income, spending, net, categories, merchants, alerts). It distinguishes itself from sibling tools like get_pnl or get_spending_summary by focusing on a comprehensive monthly review with advisory alerts.

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

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

Provides clear context with example user queries ('how did last month go', 'monthly review') and notes the default period (last completed month). While it doesn't explicitly say when not to use it or name alternatives, the examples and scope make usage obvious.

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 discloses important behaviors: the tag-matching requirement, margin rendering as multiplier in loss territory, and YTD default when no date range is given. These are non-obvious and valuable.

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 and information-dense. It front-loads the purpose, then covers prerequisites, examples, supported comparisons, a rendering quirk, and defaults—all without unnecessary padding.

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, return-value details are not needed. The description covers prerequisites, defaults, supported comparison phrasing, and tag conventions, making the tool self-contained for an agent to invoke correctly.

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

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

The schema already provides full descriptions for all three parameters, so the baseline is 3. The description adds meaningful usage context: natural-language query examples, tag-prefix shortcuts, and default date-range behavior, which enriches 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 defines the tool as per-tag P&L with revenue, cost, profit, and margin grouped by tag. It explicitly lists use cases (per-client, per-property, per-event, per-realtor-deal), distinguishing it from the general get_pnl sibling.

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 states the prerequisite that income and expense rows must be tagged with matching labels and gives query examples with supported YoY/MoM/QoQ comparisons. It does not explicitly mention when to avoid this tool or prefer a sibling, but the context makes the intended usage clear.

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 context beyond that: the special margin rendering as a multiplier in loss territory (avoiding '-436.9% margin') and the exact return shape. This enriches the agent's understanding of edge-case 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 five sentences, each with a distinct job: core purpose, example queries, supported comparisons, margin edge case, and return format. It is information-dense with no fluff, front-loads the essential purpose, and earns every sentence.

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 is remarkably complete: it explains what the tool does, how to phrase queries, what comparisons are supported, the unusual margin behavior, and the exact return structure. With an output schema present and annotations covering safety, this description leaves no significant gaps.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds some context by referencing period comparison and example queries, but it does not meaningfully expand on parameter semantics beyond the schema. 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 starts with a specific verb 'Compute' and resource 'Profit & Loss' with explicit synonyms (P&L / net income / margin). It distinguishes itself from siblings like get_per_tag_pnl by focusing on overall P&L from Income plus expense tabs, and provides clear example queries.

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 clear usage context with multiple example queries ('am I profitable this year', 'P&L for Q1') and states supported period comparisons (YoY, MoM, QoQ). It does not explicitly mention when not to use it or name alternative tools, but the examples make the intended use clear.

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 substantial behavioral context: it clarifies it is a log of assistant TOOL CALLS (not document processing), shows success/failure, and discloses return limits (default 20, max 100). This goes well beyond 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 three sentences long, front-loaded with the core purpose, then qualification, use cases, and return behavior. Every sentence earns its place, and there is no redundant 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?

For a read-only audit log tool with three optional parameters and an output schema, the description covers what it returns, limits, use cases, and exclusions. The existence of an output schema means return value details don't need to be in the description. It is complete for the tool's complexity.

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

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

The schema has descriptions for actionId and sinceDays, but not for limit. The description explains limit semantics ('most recent N entries from the audit log (default 20, max 100)'), effectively covering the gap. It adds meaning beyond the schema without over-explaining already documented parameters.

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

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

The description clearly states the tool shows recent user/AI assistant activity in ExpenseBot via this MCP server, specifically listing what is included (tools called, timestamps, arguments, success status). It explicitly distinguishes itself from document processing history, setting it apart from siblings like trace_document. This is a specific verb+resource description with clear scope.

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 use cases ('what did I do this week', 'which tools has my assistant run') and an explicit exclusion ('not the processing history of a document'). This tells the agent when to use it and when not to, effectively pointing toward alternatives for document histories without naming them directly.

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, covering safety. The description adds behavioral context by specifying the scope of returned data (all expenses, totals, compliance status) and explicitly prohibiting preflight/follow-up calls, which is valuable 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?

Two concise sentences: the first defines purpose and output scope, the second provides clear usage restrictions. 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?

For a read-only inspection tool with an output schema, the description adequately covers purpose, when to use/avoid, and what content to expect. The annotations and schema handle safety and parameter details, leaving no significant gaps.

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

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

Schema descriptions cover 100% of parameters, including detailed guidance like 'Do not paraphrase or invent diagnostic intent' for userRequest. The description does not add parameter-level semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as retrieving full details of a specific expense report, enumerating the content (expenses, totals, compliance status). It distinguishes this from sibling tools like list_reports or get_expense_by_id by focusing on the whole report inspection.

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?

Explicit usage guidance is provided: 'Use only when the user explicitly asks to inspect an existing report's details' and 'Never call this as a preflight or follow-up to creating, sharing, or billing from a report; those tools already return the required result and links.' This clearly scopes when to use the tool and points to 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 the bar is lower. The description adds value by noting it returns 'the same live phase and item progress shown by ExpenseBot's in-app status pill,' and by mentioning the 'authoritative' nature of the status. It also repeats 'Read-only,' which is redundant but not harmful. Slightly more detail on behaviors (e.g., polling, caching) could push to 5.

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

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

Four sentences, each serving a distinct purpose: purpose, return details, usage timing, and action guidance. It is well-structured but somewhat dense, especially the second sentence which lists many return fields in a run-on style. Still, 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?

For a zero-parameter status tool with an output schema, the description is complete. It explains not only what the tool returns but also how to present that information to the user (show spreadsheetUrl, etc.). It covers edge conditions like setup/reconnection with gmailScanUrl. No missing context is apparent.

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 zero parameters, the baseline is 4. The description correctly focuses on the return content and usage guidance rather than parameter details, as there are no parameters to explain. Schema coverage is 100% with an empty object, so no additional parameter semantics are needed.

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: 'Check the authoritative status of the user's Gmail receipt scans.' It clearly distinguishes this from sibling tools like scan_gmail or get_recent_activity by focusing on the status of scans and listing concrete status elements (active lock, live phase, progress, completed years).

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

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

Explicitly states when to call: 'Call when the user asks whether a scan is running, finished, stuck, or what it is doing.' It also provides conditional guidance on what to show based on the result (spreadsheetUrl vs reviewExpensesUrl vs gmailScanUrl), which goes beyond simple context.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description mirrors this with 'Read-only.' It adds value by disclosing the return structure ({ message, data: { total, breakdown?, comparison?, sampleMeta? } }) and hinting at optional comparison support, which goes beyond annotation fields.

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: the first states the core action, the second lists supported options, and the third gives the return shape. Front-loaded, efficient, and free of 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 six parameters (all optional), a complex dateRange oneOf schema, and annotations, the description covers the main purpose, grouping, metrics, date ranges, and return format. The natural-language 'query' parameter is not mentioned in the description, and clientEmail/categories are left to schema, but overall it's a well-rounded summary for a read-only reporting 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?

With schema coverage at 50%, the description compensates by mapping 'breakdowns by category, merchant...' to the groupBy enum, 'total, count, or average' to metric, and 'date ranges, period comparisons' to dateRange. It does not explain query or clientEmail, but those have some schema descriptions, so the added semantic value is solid.

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

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

The description uses a specific verb 'summarize' with a clear resource 'recorded expenses' and enumerates breakdown dimensions (category, merchant, month, tag, source, payment method) and metrics (total, count, average). This clearly distinguishes it from income-focused tools like get_income_summary and other analytics 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?

Usage is implied: it's for summarizing the user's recorded expenses. The description lists supported capabilities (date ranges, period comparisons, metrics) but does not explicitly state when to choose this tool over alternatives or when not to use it. No alternative tool names are given.

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 annotation, the description discloses that the tool is read-only and does not create or modify spreadsheet rows. It also reveals behavioral details: links are authenticated, existing forms are opened, and for unavailable Drive folder links, it must not invent or request a folder ID. Edge cases like owner-access handoffs are explicitly addressed.

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 quite lengthy, but it is front-loaded with a clear summary sentence followed by systematic scenario-based guidance. Every major section (spreadsheet, links, income, Gmail, teams) earns its place, though some compression could be possible without losing 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?

The description fully covers the tool's purpose, when to use it, alternatives, exclusions (e.g., direct write tool for unambiguous entries), and edge cases (e.g., owner access, unavailable folder links). Since an output schema exists and parameters are absent, this comprehensive guidance makes the description complete for an AI agent to select and invoke 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 tool has zero parameters, and the schema already covers all 100% of them. The description therefore does not need to explain parameter syntax, but it still adds value by detailing the output structure (links with labels and descriptions) and usage contexts, which is appropriate for a no-parameter tool.

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 user's master ExpenseBot Google Sheet plus authenticated workspace links with labels and usage descriptions. It specifies the exact verb 'Return' and resource (spreadsheet URL/links), distinguishing it from sibling data-retrieval tools like get_pnl or get_expense_by_id.

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 extensive when-to-use guidance, enumerating specific user requests (e.g., 'open, view, check, or edit their spreadsheet', 'manually scan Gmail', 'reconcile') and prefers the tool for link delivery. It explicitly names alternatives, such as using 'the direct write tool' for unambiguous cash expenses and mileage trips, and instructs to choose relevant links instead of listing the entire catalog.

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 the tool as read-only and non-destructive. The description adds valuable behavioral context by naming the underlying Subscription Auditor engine, listing the categories of findings, and specifying the return structure ({ message, data: { recurring, duplicates, priceIncreases, trialConversions, totalMonthlyCost, sampleMeta? } }). This goes beyond annotations without contradicting them.

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 yet information-dense: a clear purpose statement, a set of representative example phrasings, and a defined return shape. There is no fluff or repetition; each sentence earns its place. The structure front-loads the core purpose and then adds examples and output details.

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 complex dateRange schema and the presence of an output schema, the description is sufficiently complete. It covers the tool's purpose, usage context, and return format, while the schema and annotations handle parameter definitions and safety profile. The description adds perspective (e.g., 'suspects' and engine wrapper) without requiring extra explanation.

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% — all parameters (focus, query, dateRange) have detailed descriptions in the schema. The description adds extra meaning by connecting focus categories (recurring, duplicates, price_increases, trial_conversions) to the output fields (recurring, duplicates, priceIncreases, trialConversions), and by giving natural-language examples that map to the query parameter. This supplemental guidance nudges the score above the baseline 3.

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

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

The description clearly identifies the tool as wrapping the Subscription Auditor engine to detect recurring charges, duplicates, price increases, and trial-conversion suspects. It also includes example user queries, which helps distinguish it from generic expense or analytics tools. The verb 'find' and the resource 'user's expenses' make the scope explicit.

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 concrete example user phrasings ('recurring subscriptions', 'duplicate subscriptions', 'price increases', 'trial conversions', 'subscriptions over $20/month'), which strongly signal when to use the tool. However, it does not explicitly mention when not to use it or name alternatives such as get_deep_analytics or get_spending_summary, so it stops short of full exclusion guidance.

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

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

Annotations already declare destructiveHint=true, but the description goes far beyond by disclosing that premature confirm:true is converted to preview, Personal-tagged rows are removed so their marker is never overwritten, already-assigned expenses are excluded to avoid duplicate reports, and confirmed calls return report/Bill Client links. It also warns against unsolicited advice, adding rich behavioral context beyond structured metadata.

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 adds operational value. It front-loads the core purpose and examples, then logically flows through workflow, exclusions, report creation, and boundaries. No filler or restatement of schema fields; all content 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 complex destructive tool with 12 parameters and an output schema, the description is exceptionally complete. It covers the full preview-confirm lifecycle, conflict and exclusion handling, report creation, Personal-tag behavior, and explicit boundaries against invoking unrelated tools. The output schema covers return values, so the description need not repeat them.

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 75%, but the description adds critical semantics: operationId is a stable idempotency key reused across preview/confirm, confirm must be omitted/false first, approveNewGroup should be true only when preview says new group needed, and excludePersonal affects both grouping and report. It explains the two-phase interaction between parameters that the schema alone does not convey.

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 ('Group an exact set of recorded expenses') and enumerates the supported grouping purposes (client, project, trip, job, other user-named). It clearly distinguishes this from related tools like search_expenses and create_report by specifying that exact expenseIds come from search_expenses and that report creation is embedded when requested.

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: use exact expenseId from search_expenses, preview first then confirm, set createReport only on confirmed call rather than a separate broader create_report query, and avoid check_compliance/tax tools unless asked. It also mentions when excludePersonal applies and clarifies that sharing remains a separate action. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context by stating it 'Returns the live list from their spreadsheet,' indicating real-time data and no side effects. This goes beyond the annotations by explaining the source and freshness of data.

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 the primary purpose front-loaded. Every sentence earns its place: the first states what it does, the second provides critical usage guidance. No filler or redundancy.

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

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

For a simple, zero-parameter read tool, the description covers purpose, usage timing, and return value. The output schema likely documents the list structure, so no further return explanation is needed. The description is complete for an agent to select and invoke 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 tool has zero parameters, so the baseline is 4. The description doesn't need to explain parameters; it instead clarifies the return value (a list). This is sufficient given the empty input 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 uses a specific verb ('List') and clearly identifies the resource ('user's configured expense categories and billing accounts'). It also distinguishes itself from sibling tools by focusing on expense categories and billing accounts, and by naming tools that require a category (add_cash_expense, add_mileage_entry, create_report).

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

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

Explicitly states when to use this tool ('BEFORE calling tools that need a category') and provides concrete examples of dependent tools. It also explains the reasoning ('so you pass the user's actual category names, not guesses'), giving clear usage context without needing exclusions.

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

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

The description explicitly states 'Read-only — it does not create, send, or mark invoices paid,' which adds behavioral detail beyond the readOnlyHint annotation. It also clarifies the scope to issued invoices/accounts receivable without contradicting annotations. No rate limits or auth details are mentioned, but they are not required for this simple read-only list 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?

Four short sentences front-load the core purpose, provide natural language examples, and close with a side-effect guarantee. Every sentence earns its place; no filler or repetition of schema fields.

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

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

For a read-only list tool with all optional parameters, a complete output schema, and rich annotations, the description covers purpose, usage examples, status filtering, and side effects. Nothing critical is missing; the schema handles parameter detail and return values.

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 schema already documents all four parameters. The description adds status semantics ('open' default, 'paid', 'all') but this duplicates the schema's enum and default, adding little beyond what is already structured. The example queries imply filtering but don't add parameter-specific detail.

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: 'List the user's issued client invoices (accounts receivable)' and immediately defines the return scope (who owes, how much, due date). It clearly distinguishes this tool from sibling list/search tools, and the example queries reinforce the exact use case.

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 clear context through example questions ('which invoices are outstanding', 'what does Acme still owe me') that illustrate when to use it. It does not explicitly name alternative tools or say when not to use it, but the examples are sufficient for an AI to route invoice-level AR questions correctly.

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 categories are fixed, canonical, and not user-configurable, which provides meaningful behavioral context beyond the structured 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?

Two concise, front-loaded sentences. The first states the core purpose, the second gives usage guidance. No wasted words; every phrase 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?

With an output schema present, the description needn't explain return values. It fully explains what the tool lists, how it differs from similar resources, and exactly when to invoke it, making it complete for this simple read-only 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?

There are zero parameters, and schema coverage is trivially 100%. Per the rubric, 0 params earns a baseline of 4; the description adds no parameter details because none exist, so this 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 uses a specific verb ('List') and resource ('ExpenseBot's fixed income tax categories'), clearly distinguishing from user-configured Expense Accounts and sibling tool 'list_categories'. It precisely states what the tool does.

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

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

Explicitly instructs to use 'BEFORE calling add_income' to pass an exact canonical category, and clarifies these categories are not user-configured, preventing misuse. This provides clear context and an explicit trigger for when to use the 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?

The readOnlyHint and destructiveHint annotations already establish this as a safe read operation. The description adds scope ('user's expense reports') and pagination behavior, but no deeper traits such as auth requirements or rate limits, so value beyond annotations is moderate.

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

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

A single sentence front-loads the verb and object, then packs pagination and filter options without redundancy. Every clause 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 simple list tool with readOnly annotations and an output schema, the description covers core usage adequately. It omits the accountant-specific clientEmail use case, but the schema already describes that parameter, so the gap is minor.

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 only 25% schema description coverage, the description compensates by introducing pagination for page/limit and enumerating status filter values. The clientEmail parameter is already described in the schema, so all parameters have some semantic coverage; still, page/limit specifics are thin.

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 specifies the action (List), resource (user's expense reports), and key behaviors (pagination, status filtering). It distinguishes this from sibling tools like create_report and get_report_details by focusing on listing multiple reports.

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 clearly states the tool's purpose for listing reports with pagination and status filters, giving the agent context for when to invoke it. However, it does not explicitly name alternatives or exclusion criteria, so it falls short of full alternative guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context by explaining that tags represent various entities and giving examples, which helps the agent interpret the returned data. No hidden side effects are disclosed, but none are expected for a list operation.

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 long, each adding value. It front-loads the primary action, then clarifies the domain with examples, and finally provides usage context. No redundant or filler content exists.

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

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

Given the tool's simplicity (no parameters, read-only, clear annotations, and an output schema), the description fully covers what the tool does, what the tags represent, and when to use it. There are no obvious gaps.

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

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

The tool has zero parameters, so the schema coverage is trivially 100%. The description does not need to explain parameters. Per the baseline for 0 params, a score of 4 is appropriate since no parameter semantics are required.

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

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

The description clearly states the tool's function: 'List the user's configured groups' and explains that groups are tags representing clients, projects, properties, and trips. It includes concrete examples and distinguishes itself from siblings like list_categories by defining the tag scope, making the purpose explicit and unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Use this when the user asks what groups/projects/clients do I have? and before filtering, grouping, or reporting when the intended existing name is unclear.' While it does not mention specific when-not-to-use scenarios or alternatives, the provided context is clear and actionable.

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 reinforces this by stating it just returns parsed fields for review. It adds the key behavioral detail that no expense is persisted, exceeding what annotations convey. No contradictions detected.

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

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

The description is only two sentences plus an example, with no superfluous content. It front-loads the core purpose, immediately clarifies the no-side-effect behavior, and uses a concrete example to illustrate usage. 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?

For a tool with a single parameter, an output schema, and clear annotations, the description provides all necessary context: what it does, that it doesn't mutate data, and an example of input/output. No significant information is missing for an agent to select and invoke it 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 input schema already describes the 'text' parameter with an example, providing 100% coverage. The description adds further value with its own example showing how natural language maps to structured fields (merchant, total), giving the agent a richer understanding of expected input and output without needing to see the output schema.

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

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

The description uses a specific verb ('Parse') and resource ('natural language expense description') while clearly stating the output as structured fields. It explicitly distinguishes itself from sibling add tools by noting it does NOT add the expense, making its purpose 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 a clear context for use (parsing for review) and an explicit exclusion ('Does NOT add the expense'), implying when not to use it. However, it does not name alternative sibling tools like add_cash_expense, so it stops short of fully explicit when-to-use guidance.

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

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

Annotations already indicate readOnlyHint=false (a write operation) and openWorldHint=true. The description adds valuable behavioral context by explaining the pipeline (converted to PDF, extracted by AI, added to spreadsheet) and the 25-email limit. This goes beyond what annotations provide, though it doesn't detail failure handling or effects on the original emails.

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 no unnecessary words. The first sentence states the core action, the second explains the process, and the third provides constraints. Information is ordered from most to least important, making it easy to scan.

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 two parameters, an output schema, and annotations covering safety, the description sufficiently covers the prerequisites (Gmail connection), the operational steps, and the limit. It doesn't need to describe return values because an output schema exists. Minor omissions like error handling are acceptable given the tool's moderate complexity.

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

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

Schema coverage is 100% (both parameters have descriptions). The description repeats that Gmail message IDs are passed and implies accountEmail is optional, but adds no additional syntax or format details beyond the schema. Thus it meets the baseline for high schema coverage without adding significant 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 begins with a specific verb and resource: 'Process specific Gmail emails as receipts.' It clearly differentiates from sibling tools like scan_gmail and scan_gmail_years by emphasizing user-provided message IDs rather than scanning. The subsequent explanation of converting to PDF, AI extraction, and adding to a spreadsheet fully clarifies the tool's function.

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 when to use the tool: when the user has specific Gmail message IDs to process as receipts. It also provides constraints (max 25 emails, Gmail must be connected). However, it does not explicitly contrast with alternatives or say when not to use it, 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?

The description discloses key behavioral traits beyond annotations: runs asynchronously, returns immediately, and sends an email summary when done. Annotations only indicate readOnlyHint false, openWorldHint true, destructiveHint false; the description adds meaningful context about execution model. Slightly more detail on side effects (e.g., processing receipts into records) could elevate it to 5, but current coverage is strong.

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 clear sentences, front-loaded with the action, then async behavior, UI analogy, and alternatives. No wasted words; every sentence contributes to understanding.

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 4-parameter tool with full schema description and an output schema, the description covers essential context: default scope, async behavior, alternatives, and progress checking. No critical gaps.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds a little context (default 60 days, max lookback depends on subscription) but doesn't add significant meaning beyond the schema. Baseline 3 is appropriate since schema does the heavy lifting.

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 triggers a background Gmail scan to discover and process receipt emails, with a default 60-day window. It also differentiates from siblings by explicitly referencing scan_gmail_years for past years and get_scan_status for progress, making the purpose unmistakable.

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

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

Provides explicit usage guidance: use for default ~60-day scans, use scan_gmail_years for multi-year ranges, and get_scan_status for progress monitoring. The asynchronous nature and UI analogy further clarify when and how to invoke this 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?

The description discloses critical behavioral traits beyond annotations: it is a long-running background job, years queue and run one at a time, each takes hours, and the user can close the app. It also explains the non-destructive but stateful preview/confirm behavior. No contradiction with annotations (readOnlyHint=false matches the starting of scans).

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 yet information-dense, with every sentence serving a purpose. It is front-loaded with the core purpose and flows logically through the preview/confirm protocol, alternatives, and constraints. No wasted words.

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

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

For a complex tool with background processing, queueing, and a mandatory confirmation flow, the description covers all essential operational aspects: preview behavior, confirmStart requirement, long runtime, user can close app, and the in-progress year limitation. With an output schema present, no return value description 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 already provides 100% coverage with detailed parameter descriptions, including confirmStart's exact semantics. The description adds a usage pattern (preview first, then confirm) and an example, but does not meaningfully expand on the schema's per-parameter meaning. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool's purpose: scanning completed prior years of Gmail for receipts. It uses a specific verb ('scan') and resource ('prior years of Gmail'), and distinguishes from sibling tools by explicitly noting the 'last ~60 days' alternative (scan_gmail).

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: use scan_gmail for recent receipts, use get_scan_status to check progress, and outlines the required two-step preview-then-confirm workflow. It also notes a key constraint (current in-progress year cannot be scanned), giving the agent clear operational direction.

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 safe read-only nature is covered. The description adds useful behavioral context: it returns items with id, title, and url, and instructs to use the fetch tool for full details. This chaining behavior and the integration context go beyond what annotations provide, without contradicting them.

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 four short sentences that each serve a purpose: state the search scope, describe the return format, explain the fetch chaining, and mention the integrations. It is front-loaded with the primary action and avoids any fluff or redundancy.

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

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

The description covers the tool's search scope, return items, chaining to fetch, and integration use cases, while the output schema handles return details and annotations cover safety. It is missing only an explicit distinction from the sibling search_expenses and search_knowledge tools, which would enhance completeness but is not strictly necessary given the broad-scope description.

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

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

The input schema has 100% coverage with a clear description and example for the 'query' parameter. The tool description itself does not add additional parameter meaning beyond what the schema already provides, so the baseline score 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 tool searches the user's ExpenseBot data across expenses, reports, and knowledge base. The verb 'search' and the three explicit resource categories give a specific, unambiguous purpose. This broad scope distinguishes it from narrower siblings like search_expenses and search_knowledge, even though those alternatives are not named.

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 this tool: to search across multiple data types and to power Deep Research and Company Knowledge integrations. It also gives a chaining instruction to use the returned id with the `fetch` tool for details. However, it does not explicitly mention when NOT to use it or name alternatives like search_expenses or search_knowledge, so it falls short of full exclusion guidance.

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

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

Rich behavioral detail beyond annotations: pagination semantics, deterministic matching ('no embeddings or model classifiers'), AND combination of filters, disambiguation with exact expenseId, and the presence of matchedFields/matchReason. This complements the readOnlyHint/destructiveHint annotations with valuable context about state and edge cases.

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 detailed but every sentence earns its place: purpose, pagination, query behavior, disambiguation, and result fields. It is logically organized and front-loaded, with no redundant fluff. The length is appropriate for an 11-parameter search tool with complex behavior.

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 complex search tool, the description covers all key aspects: filtering options, natural-language query, pagination, disambiguation, result contents, and the tie-in to update_expense. It handles edge cases like relative date ranges and clientEmail constraints, and since an output schema exists, not detailing every return field is acceptable.

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 has 100% description coverage, the tool description adds significant meaning: it defines the query field's scope and examples, explains how structured filters combine (AND semantics), describes cursor reuse ('never construct or edit this value'), and clarifies dateRange variant selection ('pick the shape that matches the user's phrasing'). This goes well 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?

Description opens with 'Search and filter the user's expenses' – a specific verb+resource that clearly states the tool's function. It further distinguishes from siblings by focusing on expense rows from a spreadsheet and listing specific filter dimensions (category, merchant, date range, amount, tags).

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 guidance on pagination ('when hasMore is true, call again with nextCursor') and warns against splitting date ranges into overlapping searches. It also explains the optional query parameter as deterministic natural-language recall and notes the clientEmail constraint for accountants, but it does not explicitly contrast with sibling search tools or state when not to use it.

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

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

Beyond the annotations (readOnlyHint=true, destructiveHint=false), the description adds behavioral details: 'Results are query-ranked; request the full answer after identifying the relevant article.' This explains the ranked response behavior and the two-step workflow, which is valuable and not present in the annotations or schema. It does not contradict 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 concise sentences, each earning its place: the first names the resource, the second gives explicit usage timing, and the third explains the response behavior and follow-up action. It is front-loaded with the most critical information and contains 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?

Given the presence of an output schema and strong annotations, the description is complete for its complexity. It tells the agent what the tool searches, when to use it, and how to handle the ranked results. There is no missing critical context for a knowledge-base search 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 coverage is 100% with all parameters described, so the baseline is 3. The description adds semantic value by explaining the intended flow: 'request the full answer after identifying the relevant article,' which directly informs use of the 'fullAnswer' parameter. It also implies that 'limit' controls the number of ranked articles, reinforcing the 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 'Search ExpenseBot's complete product and help knowledge base' with a specific verb and resource, immediately distinguishing it from sibling tools like 'search' and 'search_expenses' which are likely for other data types. It also lists concrete use cases (setup, billing, Gmail, etc.) that make the tool's purpose 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?

The description provides explicit guidance: 'Use this before guessing when the user asks how a feature works, what ExpenseBot supports, or needs setup, billing, Gmail, scan, report, workflow, or troubleshooting instructions.' This gives clear context for when to use the tool, though it does not explicitly state when not to use it or name alternative tools for other search scenarios.

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 mark destructiveHint=true, but the description does not clarify what destructive behavior occurs (e.g., overwriting existing shares). It adds no context beyond what annotations already state.

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

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

A single, front-loaded sentence communicates the essential action without redundancy, earning full marks for conciseness and structure.

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 simple but has a destructiveHint that is unexplained. While the output schema and annotations provide some context, the description leaves gaps about side effects and prerequisites, making it minimally complete.

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

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

With 0% schema description coverage, the description partially compensates by identifying reportId as the expense report and recipients as email addresses, but it does not elaborate on the format or constraints 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 states the specific verb 'share' with the resource 'expense report' and the purpose 'for review or approval', clearly distinguishing it from siblings like export_report or get_report_details.

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

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

The purpose 'for review or approval' implies when to use, but there is no explicit guidance about when not to use it or how it differs from alternatives like export_report or create_report.

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?

While annotations already signal a non-read-only, non-destructive tool, the description adds critical behavioral context: receipt validation, cloud upload, AI processing, and a 1-3 minute delay (longer for PDFs/batches). It also discloses failure modes ('If any file fails validation the whole batch is rejected', 'large base64 payloads are frequently dropped... silently loses the receipt'), which is 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 long but every section earns its place: the opening one-liner summarizes the tool, the 'TO SEND FILES' section gives a step-by-step workflow, and the final paragraph explains metadata column mappings. It uses bolded section headers for scannability and front-loads the primary purpose. Despite its length, it avoids redundancy and repetitive phrasing.

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 (per context signals), the description does not need to detail return values. It covers the main workflow (filesToUpload → upload → uploadRefs), the alternative photo path, batch processing, validation atomicity, and column-level storage semantics. It fully addresses the tool's complexity, including mixed file types and per-file overrides, so 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?

The schema already provides 100% parameter coverage, but the description enriches understanding with practical semantics: 'Only use the photo parameter for a single small image' and 'Batch defaults apply to every file, and each uploadRefs item may override either value for that file.' It clarifies the override/merge behavior across batch and per-file levels, which the schema alone does not fully convey.

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: 'Submit a photo or PDF of a receipt for processing.' It goes beyond a generic verb+resource by providing example user phrasings ('log this receipt', 'expense this') and specifying supported formats and workflow, which distinguishes it from sibling tools like add_cash_expense or parse_expense.

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, prescriptive usage instructions: the 'TO SEND FILES' section mandates the filesToUpload/uploadRefs flow, states 'Do not call this tool once per file', and advises against using the photo parameter for large payloads. It also tells the AI when to use which parameter (photo vs filesToUpload), making the decision process clear.

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 it returns a 'read-only timeline' and mentions 'lineage audit trail', providing context about what the tool does without overstating. It aligns with the annotations and does not contradict them, so it gets a 4.

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 and front-loaded with the core purpose. Every sentence adds meaningful value with no filler or redundancy.

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

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

The tool has an output schema, so the description does not need to explain return values. It provides clear context for when and why to use the tool, mentions the read-only and lineage aspects, and is complete for an agent to select and invoke it 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?

Schema description coverage is 100%, so the schema fully documents all seven parameters. The description does not add significant parameter-level detail beyond what the schema already provides. Therefore, 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 uses a specific verb ('Trace') and clearly identifies the resource ('specific receipt, invoice, forwarded email, Gmail receipt, or PDF in ExpenseBot processing'). It distinguishes itself from siblings by focusing on the processing lineage of documents, which is unique among the listed tools.