ExpenseBot

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

The annotations only declare readOnlyHint=false, openWorldHint=false, destructiveHint=false, so the description carries the behavioral burden. It discloses the direct side effect ('writes directly to the user's expense spreadsheet after confirmation'), the negative-expense representation, and the canonical client-group reuse/creation behavior. It stops short of explaining what 'confirmation' actually entails, but adds meaningful behavioral context well beyond the minimal annotation set.

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 (~180 words) but every sentence carries unique information: mode distinction, side effect, preconditions, exclusions, and the alternate route. It front-loads the primary purpose and is logically organized, though the paragraph density is high enough that the key disambiguation could have been slightly tightened.

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 a 12-parameter tool with two distinct call patterns, no output schema, and a very large sibling list, the description is exceptionally complete: it covers preconditions, exclusions, alternative routes, and client-advance specifics. It does not describe the return value or what the agent should expect after a successful call, and the 'after confirmation' flow remains ambiguous, since there is no output-schema fallback to cover these.

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 each parameter. The description adds inter-parameter wiring that the schema cannot: category is only required for the ordinary-expense path, isClientAdvance=true requires clientName and ignores category, and merchant is derived from clientName for advances. This conditional semantics is genuinely additional value beyond the schema.

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

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

The description opens with a specific verb-resource pair ('Add an expense without a receipt') and immediately distinguishes the second mode ('record money a client provided in advance'). It explicitly scopes the tool and even names what it is not (never vendor refunds, reimbursements, earned fees, retainers, generic deposits), making sibling disambiguation easy.

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

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

Provides explicit when-to-use guidance for both modes, an explicit precondition ('call list_categories first and provide a configured Expense Account'), a hard list of exclusions, and a named alternative (Manual expense link from get_spreadsheet_url) with the specific conditions that should trigger it. Nothing is left to inference.

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, the description discloses a concrete write target (Income tab of the spreadsheet), the category validation behavior (unknown category rejected), and the default category. The non-destructive hints and title are not contradicted. It does not describe the return value or whether the entry is immediately visible, but the disclosed side effect is the main behavior an agent needs.

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 carry the action, side effect, use-case, prerequisite, default, and validation behavior with no filler. The most decision-relevant content 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 mutation tool with 12 parameters and no output schema, the description covers the workflow and critical validation behavior well enough for an agent to call it correctly. It could go a bit further by describing what the successful call returns or by explicitly differentiating itself from the file/CSV income siblings.

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 high at 92%, so the schema already explains most parameters; 3 is the baseline. The description adds genuinely valuable semantics beyond the schema: categories must come from list_income_categories, an omitted category defaults to Service income, and unknown categories are rejected. It also gives payment-method examples that map to accepted input values.

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: 'Log an income entry manually' and states it writes to the Income tab of the user's expense spreadsheet. It also distinguishes itself from the auto-detection siblings by framing this as the tool for income that is not detected from Gmail or Plaid.

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 gives the when-to-use context: manual income that is not auto-detected from Gmail or Plaid. It also gives a strong prerequisite by requiring list_income_categories to be called first. It does not explicitly name the sibling add_income_from_csv/add_income_from_file as the batch/alternate path, which keeps it just short of fully explicit alternative routing.

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

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

The description goes far beyond the annotations by stating that step 1 saves nothing, duplicates are skipped unless explicitly kept, previews expire after 15 minutes, and invalid preview IDs never write. This gives an agent a realistic model of the tool's side effects and could not be inferred 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 long but densely structured: it front-loads the purpose and file limits, uses STEP 1/STEP 2 markers to impose order, and every sentence contributes either contract behavior or parameter usage. For a 10-parameter, two-phase tool, this length 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?

The description covers the full lifecycle: file submission, parsing, preview, duplicate handling, user edits, expiration, confirm behavior, and the URLs to show after success. Given no output schema and the complexity of 10 parameters, this completeness is strong.

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

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

Schema coverage is 100%, so the baseline is already 3, but the description adds cross-parameter semantics by explaining which parameters belong to which step and how selectedIndexes, keepBothIndexes, rowEdits, tag, and bulkNote interact with the preview. It does not need to repeat schema-level details because those are already complete.

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

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

The description opens with a specific verb and resource: 'Import income from a CSV/TSV/text export,' and names common sources such as Stripe, PayPal, Square, and bank statements. It clearly distinguishes this tool from manual income entry and references the related add_income_from_file workflow while maintaining its own file-import identity.

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 spells out exactly when to call the tool: step 1 with csvContent and no confirm for parsing, then step 2 with confirm:true and previewId to write rows. It does not explicitly say 'use this instead of X,' but the two-step contract and duplicate-handling guidance make 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 are minimal (readOnlyHint=false, destructiveHint=false), so the description carries the burden — and it excels. It states that step 1 saves nothing, treats attachment as consent to parse not write, that duplicates are skipped unless explicitly kept, that expired previewIds never write, and that step 2 with confirm:true writes exactly those rows. It also gives the returned URLs (spreadsheetUrl, reviewIncomeUrl). This is exceptional behavioral disclosure for a mutation 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?

Long but appropriately so for an 11-parameter two-step tool. It front-loads the file types and the two-step requirement, uses STEP 1/STEP 2 headings to organize behavior, and each sentence earns its place by adding operational detail. Slightly dense, but there's 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?

For a complex tool with no output schema, the description covers everything an agent needs to invoke it correctly: the two-step shape, the previewId expiry, duplicate handling, what counts as written vs not written, the returned URLs, and the alternative for complex reviews. Nothing critical is missing.

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

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

Schema coverage is 100% and each parameter is already documented. The description adds crucial cross-parameter semantics: which params are step-1 vs step-2 only, the mutual exclusivity between photo/photoBase64, the role of confirm in the two-step flow, and how rowEdits/selectedIndexes/keepBothIndexes interact. It adds the meaning behind the parameters rather than just repeating 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 imports income from an attached file (screenshot/image/PDF) and explicitly lists supported formats and max size. It names the specific two-step flow, distinguishing it from sibling tools like add_income and add_income_from_csv, and explains how it differs from the CSV import path.

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 step-by-step guidance: call without confirm first, show the user the parsed preview, then call again with confirm:true and previewId. It also states when NOT to include things (only user-approved changes), what to do with duplicates, and the 15-minute expiry. It even routes to an alternative (get_spreadsheet_url) for complex reviews.

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 a write operation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds transparency about the side effect: it writes a row to the user's expense spreadsheet with a calculated dollar amount, and it exposes a prerequisite (configured rate/unit) that could otherwise cause failures. 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?

The description is front-loaded with the primary purpose, then provides context on target users and prerequisites, and ends with concise routing guidance. Every sentence adds value and there is no redundancy or repetition of schema 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?

Despite having 9 parameters, the input schema fully covers all parameter semantics. There is no output schema, but the description explains the outcome (writes a row, calculates dollar value). It includes prerequisites and alternative usage, so an agent has all necessary information to decide when and how to call 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% for all 9 parameters, and each parameter has a clear description in the input schema. The tool description adds no additional parameter semantics beyond what is already in the schema, so a baseline score of 3 is appropriate. It does not need to compensate for any gaps.

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

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

States a specific verb and resource ('Log a business mileage trip'), explicitly mentions the write effect ('writes a row to their expense spreadsheet with the calculated dollar value'), and differentiates from the sibling get_spreadsheet_url by naming when to use that alternative. This is unambiguous and distinguishes the tool from all siblings.

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 conditions: requires the user to have configured mileage rate and unit in Settings, and names the alternative (get_spreadsheet_url) with a precise list of scenarios that should route to it (Google Maps route calculation, mileage settings, repeated trips, calendar/rideshare import, per diem, visual review). This is a model example of when-to-use vs when-not-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=true and destructiveHint=false, so the tool is safe to call. The description adds significant behavioral context by prohibiting automatic invocation and narrowing the operation to explicit user requests, which prevents the agent from using it unnecessarily. 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 only two sentences but packs in the exact trigger condition, the resource, the topic, and explicit exclusion scenarios. There is no filler, and the most important usage constraint is front-loaded in the first phrase.

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 combination of description and fully documented schema covers everything the agent needs to correctly invoke the tool: exact parameters, exact usage constraints, and safety profile. No output schema exists, but the invocation context is complete and the likely return value is sufficiently evident from the purpose.

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 already have clear, detailed descriptions. The tool description reinforces the context behind the userRequest parameter, but it does not add new semantic detail beyond what the schema already provides. Since the schema carries the full burden, a baseline of 3 is appropriate.

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

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

The description clearly states a specific verb and object: check an existing report for compliance issues such as missing business purpose or policy violations. It also draws the boundary against non-compliance workflows, so an agent can distinguish it from related tools like fix_compliance and check_tax_deductibility.

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 is explicit about when to use the tool: only when the user explicitly asks for a compliance check of an existing report. It also gives hard exclusions for report creation, personal expense exclusions, sharing, and client billing, and explicitly forbids automatic invocation as a preflight or follow-up. This leaves no ambiguity.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description adds useful behavior: it searches the public knowledge base, returns a confidence-scored answer plus related questions, and works with or without authentication. There is no contradiction with 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 concise and well-structured: first states purpose, then the search behavior and return shape, then authentication requirements. Every sentence contributes useful, non-redundant information.

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

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

For a low-complexity tool with one required parameter and no output schema, the description is nearly complete: it explains what it checks, where it searches, what it returns, and auth requirements. It could add slightly more detail about the confidence-score format, but nothing essential is missing 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 single 'feature' parameter is already fully described in the schema with concrete examples, so the description adds little semantic value beyond the schema. This meets the baseline for high schema_description_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 a specific action and resource: checking whether ExpenseBot supports a feature or integration, with quoted example questions. It is distinct from most siblings, though it does not explicitly contrast itself with similar knowledge-lookup tools like search_knowledge or search.

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 invocation context through canonical question forms ('does ExpenseBot support X', 'can it integrate with Y'), so an agent knows when this tool fits. It does not explicitly state when not to use it or name sibling alternatives.

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

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

Annotations already mark read-only/non-destructive, so the description only needs adding context beyond that. It adds 'advice' framing and country/jurisdiction dependence, and explicitly disclaims tax-refund handling. It does not disclose edge-case behavior about unresolved countries, but for a read-only advice tool this is a minor gap.

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: the first states purpose with tight examples, the second draws the sibling-distinction and adds exact routing instruction. There is no filler and no repeated structural metadata.

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

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

For a tool with no output schema and only one required parameter, the description carries the main operational context well: what question it answers, when to avoid it, and which sibling to use instead. It doesn't state what exactly the tool returns or the place of optional filters, but these are less impactful given the advice-tool framing.

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%, with 'category' and 'merchant' lacking descriptions. The tool description heavily reinforces 'query' with examples, but never explains whether/how 'category' and 'merchant' should be filled or how they combine with 'query'. This leaves a meaningful invocation ambiguity.

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 action ('look up'), a specific resource ('tax-deductibility ... based on country'), distinguishes brother(s" and grounds with concrete examples. It is clearly a look-role and not a gauge or a general expense 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?

It provides explicit with-type examples and an explicit when-not-to-use: questions about received tax refunds are routed to get_spending_summary instead. This is a precise decision rule with a named sibling.

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 (destructiveHint=true, readOnlyHint=false), it discloses important behavioral traits: premature confirm:true is converted to preview, operationId is an idempotency key reused unchanged, attendee names must come from the user, Notes segments are preserved, and over-limit changes are skipped safely. It also specifies that results report applied/conflicted/failed counts and support Undo, providing rich behavioral depth 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 front-loaded with purpose and examples, then proceeds logically through workflow, parameter semantics, boundaries, and fallback. The length is justified by the tool's complexity (6 params, nested objects, destructive confirmation flow) and every sentence 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?

With no output schema and a destructive, stateful tool, the description fully compensates: it describes the confirmation flow, the contents of a preview (exact count and before-to-after changes), result reporting (applied/conflicted/failed, Undo), and behavioral boundaries. The operational fallback for unsupported cases and the 100-row limit also make the tool safe to invoke.

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 adds substantial value on top: it explains that receiptId values are the exact full expenseIds from search_expenses, attendeeMode 'add' preserves while 'replace' substitutes, operationId must be generated once and reused, and expected fields are used for conflicting detection. It also grounds the stateful preview/confirm protocol in parameter terms.

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

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

The description states a specific verb and resource ('correct the category, business purpose, or explicit attendees on an exact bounded set of recorded expenses') and reinforces it with concrete examples. It clearly distinguishes itself from sibling tools like update_expense or search_expenses through the bounded-batch scoping and preview requirements.

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

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

The description explicitly prescribes the workflow: first use search_expenses to identify rows, then pass full expenseId values, preview with confirm omitted/false, and confirm true only after explicit approval. It also gives when-not guidance (does not change amounts/dates, omit duplicates, infer business context, or run broad calendar matching) and a fallback URL for unsupported or >100-row cleanup.

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 side effects: revalidation, creation of Google Doc, PDF, and DOCX copies, recording the invoice, and superseding an older active invoice. This goes well beyond the destructiveHint and readOnlyHint annotations, since the agent learns exactly what state may change and what is intentionally not done.

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 dense and well-structured, starting with the core purpose and then covering prerequisites, side effects, exclusions, and a specific required condition. Every sentence adds operational value 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?

For a write tool with no output schema and destructiveHint=true, this description gives the agent enough to call it safely: required ID source, confirmTax condition, external document creation, superseding behavior, and what it does not do. No critical call-time decision is left unexplained.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context: preparationId is short-lived, confirmTax is required when tax is positive, and operationId is for retry. The description strengthens understanding of the parameters beyond their plain 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 clearly states it creates the exact invoice previously produced by prepare_client_invoice, identifies it as a confirmed write, and lists the concrete artifacts it produces. This makes it easy to distinguish from prepare_client_invoice, mark_client_invoice_paid, and add_income tools.

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

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

It explicitly ties usage to an invoice prepared via prepare_client_invoice and specifies that tax confirmation is required when tax is positive. It also lists what it does not do, excluding email and Income row creation, though it does not explicitly name the alternatives an agent should use for those actions.

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 carry bare flags (readOnlyHint=false, destructiveHint=false), so the description carries the full behavioral burden and delivers: it discloses no-duplicate behavior when no unreported matches remain, the scoping rule about expenses not already assigned to another ordinary report, the fact that the link opens a reviewed flow rather than performing an export, and the accountingHandoffUrls inclusion. This is far beyond what annotations provide.

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

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

The description is long (roughly a dozen sentences), but nearly every clause carries operational weight — duplicate prevention, link semantics, scoping rules, exclusions, return values. It is front-loaded with the core purpose and flows logically from what→how→returns→edge-case→exclusions. Slightly dense, but no filler sentences.

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

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

For a 9-parameter tool with zero required parameters and no output schema, the description is remarkably complete: it documents return contents (summary, report link, Bill Client link, applied filters, Report Wizard fallback), handles edge cases (already-reported expenses, ambiguous groups), and covers share/recipient semantics. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds genuine value on top: it explains tags as 'ExpenseBot's grouping layer for clients, projects, project codes, and trips,' clarifies that excludePersonal=true removes both the Personal tag and Personal category in line with Report Wizard behavior, and frames the date/category criteria in user-request language. A modest but real increment over 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 — 'Create an expense report from a clear date, client, project, trip, category, or merchant request' — and enumerates the exact scoping dimensions. It also differentiates from siblings by explicitly naming which tools to avoid (check_compliance, get_report_details, tax/deductibility tools) and distinguishes itself from export_report ('does not mean an export occurred').

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 guidance is explicit and actionable: 'call list_tags when the user's intended group is unclear' names the alternative and the triggering condition, and 'do not call check_compliance, get_report_details, or tax/deductibility tools before or after it unless the user explicitly asks' gives a hard when-not. The excludePersonal example also teaches when to set a specific parameter.

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?

With annotations already indicating readOnlyHint=true and destructiveHint=false, the description adds meaningful context beyond structured metadata: the download is short-lived, it applies to one authorized report, and the in-app link is the path for certain output formats. This behavior is stated 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 three sentences, each delivering independent high-value info: the core output, where formats other than PDF belong, and the mandatory preliminary lookup. Nothing is verbose or redundant.

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 a single required parameter, full schema coverage, and no output schema, this description adequately equips an agent to call the tool: it names the input, the return shape (PDF download and in-app link), and the correct alternative path for other file types. It could go to 5 with explicit response field names like reportUrl or pdfUrl.

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 documents reportId with 100% coverage as 'Report ID from list_reports'. The description reinforces the parameter's origin with 'Use list_reports first to find the reportId' and adds scoping nuance — the report must be 'exact' and 'authorized' — both of which clarify intended values beyond the schema text.

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

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

The description states a precise verb and resource: it gets a 'short-lived direct PDF download' for an 'exact authorized expense report' plus a highlighted in-app report link. The deliverables are specific enough to differentiate it from siblings like get_report_details and get_spreadsheet_url, and the sentence structure grounds the tool clearly in its purpose.

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

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

The description explicitly instructs the agent to use the in-app report link for CSV, XLSX, receipt ZIP, comments, invoicing, and other visually reviewed actions, and it names the prerequisite call: 'Use list_reports first to find the reportId.' It covers usage and context well, though it does not explicitly compare to alternative get_* sibling tools beyond the implied scope.

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

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

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 destructiveHint=true annotation already signals destructive behavior, and the description confirms bulk modification but adds little depth: no mention of which fields get changed, reversibility, permission requirements, or the scope of 'bulk' (all flagged expenses vs. a subset). With only minimal added context beyond the annotation, the burden falls on the description and it only partially meets it.

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 one tightly constructed sentence with no fluff. It introduces the purpose, scope, and a concrete example in a compact way; there is no filler or repetition of the tool name or annotations.

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 destructive bulk operation with no output schema and three required parameters (two of which are only loosely covered), the description lacks enough detail. An agent cannot know what result to expect, whether the operation is reversible, or which entities are affected for each action. The major risk is the ambiguity of which changes happen per action and the sustained broad impact of such a bulk fix anywhere.

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 33%, covering only 'value'. The description's example ('apply the same business purpose') adds helpful semantic mapping to the 'action' enum and value field, but the 'reportId' parameter remains undeclared beyond its schema type. The tool description partially compensates for the low coverage but does not fully explain the parameter roles.

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

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

The description states a specific verb and resource ('Bulk-fix compliance issues in a report') and gives an example ('apply the same business purpose to all flagged expenses'). It is clear enough to distinguish from related tools like check_compliance or correct_expenses, though it doesn't explicitly name the sibling it differs from.

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 bulk remediation of flagged compliance issues but gives no explicit guidance on when to choose this over check_compliance, correct_expenses, or update_expense. No exclusions or alternative conditions are mentioned, leaving selection to inference.

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, the description discloses non-obvious behaviors: it never posts accounting data, provider limitations are provider-specific, writesAuthorized=false for providers except Zoho Books, and reportId changes the setup link target. This is significant behavioral nuance an agent cannot derive from readOnlyHint or destructiveHint 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 longer than needed, but every sentence carries useful information about scope, return content, provider limitations, and parameter behavior. It is front-loaded with the core purpose, followed by actionable details; only minimal redundancy exists because it states read-only which aligns with annotations without repeating them.

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 two-parameter, read-only status tool with no output schema, this description is complete. It covers the returned state, the important provider caveat, and the optional reportId behavior, without requiring an agent to infer critical constraints from elsewhere.

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 fully documents provider and reportId (100% coverage), but the description adds further precision: it explains what reportId changes in the returned link and documents provider-specific authorization behavior. This is additional semantic value, not schema repetition.

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 action — 'Check whether an accounting destination is connected and read-only setup state' — and enumerates exactly what is returned (organization, connection state, rollout state, setup link). It clearly distinguishes this status-check tool from posting or setup tools, and indirectly from sibling get_accounting_push_status by clarifying this covers connection/setup status only.

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 makes clear when to use this tool: to check connection/setup status, with optional reportId to target a specific report's setup control. It also explains that non-Zoho providers are only supported for status and writesAuthorized=false. It doesn't explicitly say 'use send_report_to_accounting to post' or 'use request_accounting_integration to initiate', but the read-only disclaimer plus sibling names make that inferable.

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 read-only nature is known. The description adds context beyond annotations by stating it returns specific fields (status, submission time, posting mode, posted receipt count, any public error, reconciliation required) and warns against re-posting. It also explicitly states 'This tool is read-only' which reinforces annotations. While it doesn't disclose rate limits or pagination, for a simple status read the added context is sufficient. 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?

The description is concise and well-structured: a clear statement of purpose, a usage trigger, a warning, and a read-only note. It front-loads the primary function and then adds actionable guidance. Each sentence adds value without redundancy. No filler 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?

With only 2 parameters, no output schema, and annotations already covering safety, the description provides everything an agent needs: it states what the tool returns (enumerated fields), when to use it, and what not to do. It also mentions the owner-account restriction. There is no missing information that would prevent correct invocation or interpretation of results. The description fully compensates for the lack of an output schema by listing the return contents.

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 both parameters are fully described in the schema. The description adds minor context: 'provider' is defined as the 'Accounting destination provider used for the prior posting attempt' (schema already says this) and 'reportId' as 'Exact ExpenseBot report ID from the prior proposal or posting attempt' (schema already says this). The description does not introduce new syntax or format details beyond the schema. Since the schema carries the semantic weight, a 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's purpose: 'Read the authoritative posting and reconciliation status for one ExpenseBot report at an accounting destination.' It specifies the exact verb (read), the resource (status of a report), and the specific context (accounting destination). It differentiates itself from siblings like send_report_to_accounting and get_accounting_integration_status by focusing on status checking rather than sending or integration status.

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

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

The description explicitly states when to use the tool: 'Use after a timeout or uncertain response before considering any retry.' It also provides a clear exclusion: 'Never re-post a completed report or a report marked needs_reconciliation; show that state to the owner instead.' This gives an agent direct instructions on when to invoke and when not to, including alternative behavior. Additionally, it notes 'owner-account only' which is a scope constraint.

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 meaningful behavior beyond the annotations: it explains the ledger sign semantics (negative = refund remains, positive = client owes), states validated that it 'never records a refund, creates an invoice, or recomputes the ledger in model prose,' and reveals the return value (the existing app handoff for Refund leftover or Bill Client). None of these details are in the schema or annotations.

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

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

Four sentences with each earning its place: purpose, usage examples, balance semantics, and output/read-only guarantee. Slightly more verbose than strictly necessary and the read-only clause partially repeats the annotations, but the text is well-structured and 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?

With no output schema, the description does the needed work on return behavior: it explains sign semantics and the returned app handoff. It does not fully describe the return shape but a reasonable level of completeness for an agent to select and invoke the tool confidently.

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%; the schema already documents both clientName (with the 'omit to list every open balance' behavior) and clientEmail. The description adds no parameter-level guidance, so the 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 a specific verb and resource: 'Read the same per-client advance balances shown in ExpenseBot's Client Advances section.' It includes concrete example queries ('how much of Acme's advance remains?', 'which client floats are still open?') that make it unmistakable distinct from siblings like get_client_invoice, get_income_summary, and get_credits_refunds.

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?

Clear when-to-use context is given through example user questions, which is strong routing guidance. However, it does not explicitly name alternatives or state when-not-to-use, leaving a small overlap ambiguity with get_credits_refunds for the 'do I owe a client a refund?' use case.

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?

Read-only is already declared by annotations, but the description adds non-obvious behavior: invoiceNumber is rejected unless unique, and private Google Doc/PDF/DOCX links are included only when available. It also enumerates the substantive return fields, which is valuable because there is no output 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?

Two sentences with no filler: the first declares the resource and return contents, the second gives the critical identifier rule. The description is dense but not bloated and front-loads the purpose.

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

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

For a read-only single-invoice lookup with no output schema, the description is complete. It lists the key financial and delivery fields, states the required identifier condition, notes the uniqueness constraint, and flags that links are included only when available.

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 all three parameters, but the description adds meaning by establishing that invoiceId or invoiceNumber is required even though no schema field is marked required, and that invoiceNumber must resolve to exactly one invoice.

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: 'Get the full financial and delivery summary for one issued client invoice.' It then lists the concrete fields returned, so an agent can clearly distinguish this from list and management tools like list_client_invoices or prepare_client_invoice.

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 useful call-time guidance: provide either invoiceId or invoiceNumber, one is required, and invoiceNumber works only when unique. It does not explicitly name alternatives, but the 'one issued client invoice' scope and identifier constraints 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?

Beyond the readOnlyHint=true annotation, the description openly states it never scans cards, changes review decisions, or adds rows, and explains returned items are negative expenses or matched against the original charge. It also discloses ordering and default count (newest first, default 25), which adds concrete behavioral detail beyond 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?

The description is concise with the primary action front-loaded, followed by clarifying examples and key behavioral constraints. It contains no fluff, though the two example-heavy sentences could be slightly tightened; still well-organized and readable.

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 no output schema, the description clearly states what is returned ('most recent items', default 25, newest first) and provides enough guidance on optional use of dateRange. It lacks a detailed shape of the returned items, but the description is adequate for a simple read-only list tool.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters. The description mentions default 25 and dateRange narrowing, but does not add substantial meaning beyond the schema; thus 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 explicitly states 'List card refunds, cashback/rewards, and statement credits that ExpenseBot has already recorded', naming both the action and the specific resource. It further disambiguates with user intent examples and a positive claim about scope, so an agent can distinguish it from sibling tools like get_income_summary or get_spending_summary.

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 through example user queries and emphasizes it only reads already-recorded data. It does not explicitly name an alternative tool or state 'use X instead', but 'Read-only: it never scans cards, changes review decisions, or adds rows' conveys when not to use it relative to scanning or review workflows.

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, destructiveHint), the description adds vital behavioral context: it runs as a background job with automatic polling and a 10-30 second latency, and discloses that sampleMeta.isTruncated signals whether the agent saw the full dataset. This goes well beyond the schema.

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

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

The description is compact (three sentences) and front-loads the core purpose, then adds usage examples, timing, and return structure. Every sentence earns its place without redundancy.

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

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

Even without an output schema, the description provides a partial return shape and explains the truncation indicator, which is essential for an analytics tool. It covers usage, execution model, and a key interpretation detail. The inner structure of 'data' is intentionally vague, but the tool is likely to produce heterogeneous results that an agent can reason about from the response.

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 descriptions for both query and dateRange. The description adds value by explaining the type of query to pass (explanatory questions) and instructing to 'use exactly one variant — pick the shape that matches the user's phrasing', which is a practical heuristic not present in the schema.

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

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

The description states a specific verb ('Run deeper, multi-step analytics') and a clear resource ('on the user's expenses'). It distinguishes itself with concrete examples ('why did my spending increase' or 'compare Q1 vs Q2') that contrast with simpler summary tools like get_spending_summary, making it 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?

It explicitly tells the agent when to use it ('Use for explanatory questions like...') and even hints at complexity by noting the 10-30 second background job. However, it does not explicitly mention alternatives or when not to use it, leaving some inference to the agent.

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 with 'Read-only.' Beyond that, it discloses the return format (headers + values + labeled map) which is not self-evident from the schema. This adds useful behavioral context, making the agent aware of what to expect from the response.

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, with the core action and identification methods front-loaded. Each clause serves a purpose: identifying the input, specifying the output, and noting the intended use case. There is no redundancy or filler, making it an efficient and well-structured definition.

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 with optional parameters, read-only semantics, and no output schema. The description covers all essential aspects: how to identify the expense, what the return value contains, and the typical use case. Given the absence of an output schema, the explicit description of the returned map compensates fully. Nothing an agent needs to call this correctly appears 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 schema provides full descriptions for both parameters (expenseId and rowNumber), including the exact source ('Column Q') and row indexing rules. The description adds no new semantic value beyond what the schema already states—it repeats the identification methods without further elaboration. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as fetching a single expense row by two possible identifiers (row number or ExpenseBot expenseId) and explicitly states the output shape. This distinguishes it from general search or list tools in the sibling set, which address different needs.

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

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

The description states when to use it ('so you can refer to a specific expense the user mentioned'), providing a clear use-case. It does not explicitly contrast with alternatives like search_expenses or list-related tools, but the specificity of the operation ('fetch a single expense row') makes the intended context evident. The use-case guidance is sufficient, though a note on when not to use it would be stronger.

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 carry readOnlyHint=true, and the description reinforces this with 'Read-only'. It also adds meaningful behavior beyond annotations: split lines are never counted as separate expenses, totals stay correct, and returns the parent payment with nested allocation lines. This helps the agent understand aggregation semantics and avoid double-counting.

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

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

The description is compact, front-loaded with the core behavior, and each sentence earns its place. The example queries are useful for triggering, the parent-line clarification prevents stat aggregation errors, and the read-only note is useful for usage boundaries.

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

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

There is no output schema, but the description supplies the key return concept: a single parent payment with nested allocation lines, while split lines remain ignored. Parameter behavior and examples are covered. The main minor gap is that it doesn't spell ou tthe exact top-level return shape or any empty-response behavior, but the description is still sufficient 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?

All 5 parameters are already fully described in the schema, so the baseline is 3. The tool description adds the important semantic concept of 'parent' expenses but does not explain limit, dates, reimbursable filtering, amount, or clientEmail beyond what the schema already provides. That is sufficient but not additive.

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 exactly what the tool does: it shows how an expense was split across categories, clients, properties, or business/personal portions. It goes beyond a name-level restatement by explaining that results are parent payments with nested allocation lines, and the example queries make the intended use 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 concrete example prompts ('how is that expense split', 'what was the business portion of that bill') and notes that splits are edited only in ExpenseBot's Review workspace, giving the agent a clear context for when this read tool is right. It does not explicitly name alternative sibling tools or say when not to use it, so it stops short of full routing 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 core safety profile is covered. The description adds valuable behavioral nuances beyond annotations: Schedule-C-style exclusions (security deposits, refunds excluded from taxable totals) and support for YoY/MoM/QoQ comparisons. It also reveals the exact return envelope ({ message, data: { total, breakdown?, comparison?, sampleMeta? } }), which is especially useful given no output 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 longer than average but every component earns its place: the opening states scope, the middle provides precise tax/drill-down details, and the examples indicate common usage. It is front-loaded in effective order and avoids fluff. It could be tightened slightly, but it remains efficient 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 optional parameters, rich natural-language input, and absence of an output schema, the description is remarkably complete. It covers allowed date range shapes (month, quarter, year, specific, relative) through the schema, and the description adds overarching behavior like exclusions, comparison support, and the return envelope. An agent armed with this description and schema can invoke and interpret this tool with confidence.

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

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

Schema description coverage is 100%, so baseline is 3, but the description adds real value. It clarifies how the 'query' parameter behaves, mapping natural language examples to groupBy values ('per-source', 'per-payment-method', 'per-category', 'per-month', 'per-tag') and explicating comparison semantics. This guidance is not present in the schema descriptions and helps agents use the tool correctly.

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?

Purpose is crystal clear: 'Get income totals, breakdowns, and analytics from the Income tab.' The description goes on to enumerate a precise set of income types (Schedule C/T2125, Schedule B drill-ins, rents) and breakdown dimensions (source, category, month, etc.), making it unmistakably distinct from income-related siblings like get_spending_summary. The scope exceeds a simple 'verb+resource' and fully specifies the domain.

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 example user phrasings ('income YTD', 'rental income by property', 'income this year vs last'), which clearly map to when an agent should invoke this tool. However, it does not explicitly contrast it with alternatives or state when not to use it, leaving a slight gap in 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds rich behavioral context beyond that: it explains the pending vs. terminal semantics (found:false vs. found:true), the verdict types (added, duplicate, skipped, errored), the counts and summaries returned, and that on completion the agent should show specific URLs. It also notes the tool is read-only, but since that's already in annotations, the extra behavioral details carry the weight. 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?

The description is relatively long but every sentence delivers meaningful guidance (workflow, polling, pending handling, return semantics, URLs to show, alternative tool). It is front-loaded with the core purpose. The only minor redundancy is the final 'Read-only.' which duplicates the annotation, but overall it is well-structured and dense with useful content.

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

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

Given the tool's complexity, the description covers all necessary aspects: what it does, how to call it (submissionId and polling), what happens when pending vs. terminal, what the return values are (verdicts, counts, URLs), and when to use an alternative. There is an output schema, but the description already explains the key return semantics in a way the agent can act on. Nothing critical 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 covers both parameters with descriptions, so the baseline is 3. The description adds value by clarifying that submissionId must be the exact ID returned by submit_receipt and that the polling interval and time allowance from that response should be used. It reinforces the relationship between the parameters and the submission workflow, slightly exceeding schema information.

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

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

The description states a specific verb ('Check') and resource ('authoritative final outcome of a receipt image/PDF batch submitted with submit_receipt'), making the tool's purpose immediately clear. It also explicitly distinguishes itself from the sibling get_scan_status by saying 'use get_scan_status for Gmail scans', which helps the agent differentiate without opening schemas.

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

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

The description provides explicit guidance on when to call this tool: after submit_receipt returns a submissionId, using the exact ID and polling interval from the response. It warns that a pending result is normal and should not trigger duplicate resubmission. It also names the alternative tool for Gmail scans, giving a clear exclusion condition.

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, and the description adds useful behavioral specifics: it supports grouping, YoY/MoM/QoQ comparisons, country-aware deduction rates, and an explicit return shape. This goes beyond what annotations alone provide.

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

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

The description is well structured and informative without being bloated. It leads with the core purpose, gives examples, notes comparison support, and summarizes the return object in a compact form. A couple of details could be trimmed, but overall it is well-sized.

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

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

There is no output schema, so the description correctly includes the return structure and optional data fields. It also covers common usage patterns and comparison flags. It does not detail edge cases like missing data or rate applicability, but it is complete enough for an agent to call the tool correctly and interpret the response.

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 full parameter documentation and enums, so the baseline is 3. The description adds meaningful query examples and explains that dateRange and groupBy are natural-language-friendly. However, it says breakdowns are by client while the schema enum lists 'tag' instead of 'client', creating a slight mismatch.

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 mileage analytics, covering totals, breakdowns, and deduction estimates. It includes concrete example queries and a return shape, making it easy to distinguish from generic expense or income summary 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?

The examples and supported phrasing strongly convey the intended use cases, including common natural-language mileage questions. It does not explicitly name alternative tools or exclusion cases, but the context is clear enough for an agent to route mileage-related queries here.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavior beyond annotations: figures come from the user's own recorded data, advisory notes are estimates and not tax advice, and the default is the last completed month. This gives the agent useful context about the output 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 front-loaded with a precise summary, then adds usage examples, a default behavior, and an important caveat. Every sentence and phrase earns its place, and the examples are compact rather than rambling.

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

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

There is no output schema, but the description enumerates the expected review contents well enough for an agent to understand what will be returned. The schema handles parameter details, and the annotations cover safety; no critical invocation detail seems missing.

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

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

Schema description coverage is 100%, so the schema already fully explains the period and clientEmail parameters. The description mostly restates the period default already present in the schema and adds no new parameter-level meaning, so the baseline 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 this is a 'Month-end summary of the user's books for one calendar month' and enumerates exactly what it returns: income, money spent, net, top categories/merchants, and alerts. This is a specific verb+resource definition that distinguishes it from narrower sibling tools like get_income_summary or get_spending_summary.

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 natural-language examples like 'how did last month go' and 'close out my books for June,' making the intended usage obvious. It also states the default period behavior. It does not explicitly name alternatives or exclude use cases, but the context is clear enough for an agent to select 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 read-only and non-destructive annotations, the description adds valuable behavioral details: the matching-tag requirement, default year-to-date behavior when no date range is given, support for YoY/MoM/QoQ phrasing, and the unusual margin-as-multiplier disclosure in loss territory. These go well beyond what the 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?

Every sentence serves a distinct purpose: primary definition, required preconditions, tag-prefix conventions, usable examples, supported comparisons, margin edge-case, and default. It is detailed but tightly organized with 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 tool read-only nature, 100% schema coverage, and absence of an output schema, the description covers everything needed to select and invoke the tool: the output scope, mandatory preconditions, acceptable date ranges, and default behavior. The examples are especially helpful for an agent deciding and formulating arguments.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful extra semantics by providing natural-language examples for the query parameter, the default dateRange behavior, the tagPrefix bucketing shortcuts, and the comparison modes. It does not merely repeat 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 a specific verb ('get') and resource ('per-tag P&L') and names the computed fields: revenue, cost, profit, and margin grouped by tag. It clearly distinguishes this from sibling tools such as get_pnl and get_income_summary by emphasizing per-tag grouping across client, property, event, and realtor-deal categories.

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 rich usage context: it requires both income and expense rows to be tagged with matching labels, shows common tag-prefix shortcuts, gives example natural language queries, and supports comparison phrasing. It does not explicitly name a sibling 'use get_pnl instead' type exclusion, but the constraints and examples make 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?

With readOnlyHint=true and destructiveHint=false in annotations, the description adds real behavioral value: it discloses that margin is rendered as a multiplier in loss territory ('expenses 5.4× revenue') instead of a confusing negative percentage, and it documents the exact return shape. This prevents the agent from misinterpreting an unusual output.

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 information-dense and efficiently ordered: core operation, representative queries, period-comparison capability, and even the unusual margin formatting every sentence earns its place. The compact return structure makes the black-box behavior predictable without over-explaining.

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?

Since there is no output schema, the description appropriately provides a return shape and even documents a surprising formatting behavior. It does not mention what happens when no dateRange is provided, however, which is relevant because all parameters are optional, and "sampleMeta?" remains unexplained.

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

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

Schema description coverage is 100%, so the baseline of 3 applies. The description's example date ranges and comparison support add context about how query and dateRange may be phrased, but the schema already carries the semantic weight for parameter shapes, especially the dateRange oneOf variants.

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 precise verb+resource statement — 'Compute Profit & Loss (P&L / net income / margin) by combining the Income tab with expense tabs' — so an agent understands exactly what the tool computes. Examples ranging from 'am I profitable this year' to YoY comparisons make the tool's scope concrete and distinguish it from income-only or spending-summary siblings.

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 use contexts through query examples and explicitly names period-comparison modes (YoY, MoM, QoQ, same-month-prev-year). It does not explicitly say when NOT to use it or name an alternative like get_per_tag_pnl or get_income_summary, so it falls just short of a 5.

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

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

With annotations already indicating this is read-only and non-destructive, the description adds useful behavioral context: it returns an audit log, shows arguments and success status, and caps results at the most recent N entries with a default of 20 and max of 100. This goes beyond what annotations alone communicate, though it stops short of describing pagination or exact result ordering.

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 and front-loaded with the main purpose, followed by clarifying context and intended use cases. Every sentence earns its place and there is 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 simple read-only listing tool with no required parameters, the description is largely complete: it explains what entries are returned, what data each entry contains, and the default/max limit. Some details such as exact result shape or whether results are sorted newest-first are implied but not explicit, given there is no 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 description adds value for `limit`, echoing the default and maximum already present in the schema. `actionId` and `sinceDays` are documented in the schema with descriptions, so the description does not need to repeat them. However, with schema coverage at 67%, the description could have reinforced the exact filtering semantics of all three parameters. Overall it is sufficient but not especially rich.

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: showing recent ExpenseBot activity by this MCP server, including which tools were called, when, with what arguments, and whether they succeeded. It also explicitly distinguishes itself from document processing history, which helps differentiate it from sibling tools like trace_document or get_last_receipt_result.

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 use cases: answering questions like 'what did I do this week' or 'which tools has my assistant run', and enabling transparency into AI-assisted actions. It also excludes a common alternative interpretation by clarifying this is a log of TOOL CALLS, not document processing history, which serves as a when-not-to-use signal.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by disclosing the content returned (expenses, totals, compliance status), but it does not discuss any edge-case behavior or permissions. This is adequate but not rich 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, no filler. The core purpose is front-loaded, and the negative guidance about when not to call is compressed into a tight, informative second 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?

For a read-only retrieval tool with no output schema, the description adequately names the returned content (expenses, totals, compliance status) and gives clear routing rules. It could mention the optional clientEmail behavior, but the schema covers that, making the overall package 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 100%, so the schema already documents reportId, clientEmail, and userRequest. The description reinforces the report-inspection context but adds no parameter-level meaning beyond the schema, which meets the baseline for full 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 uses a specific verb ('Get full details of a specific expense report') and names the exact information returned: all expenses, totals, and compliance status. This distinguishes it from sibling tools like list_reports and get_expense_by_id, so an agent can select it confidently.

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 an explicit trigger condition ('only when the user explicitly asks to inspect an existing report's details') and an explicit exclusion ('Never call this as a preflight or follow-up to creating, sharing, or billing from a report'). It also notes that the creation/sharing/billing tools already return their required result, preventing redundant calls.

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, and the description reinforces this with 'Read-only.' It adds meaningful behavioral detail beyond the annotations: the tool returns live status, queued or attention-needed years, completed years, exclusions, and recent outcomes, and explains the authoritative relationship to the in-app status pill.

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 core purpose. Every sentence earns its place by explaining what is returned, when to call, and how to use the response, without 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 there is no output schema, the description lists all major return categories and explains the response URLs meaningfully. It gives enough context for an agent to interpret and act on the result without needing additional documentation.

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

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

The tool takes zero parameters, so the description carries no parameter burden. With no parameters to document, the description appropriately focuses on behavior and return values, which is the correct approach for parameterless tools.

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

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

States a specific verb and resource: checking the authoritative status of Gmail receipt scans. It clearly identifies the tool's scope and differentiates it from scanning or receipt-processing siblings like scan_gmail and process_gmail_receipts.

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 says when to call this tool, namely when the user asks whether a scan is running, finished, stuck, or what it is doing. It also provides response guidance around which returned URL to show. It does not explicitly exclude alternative tools, but the contextual trigger is clear enough.

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

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

Annotations already cover the read-only and non-destructive nature, so the description's 'Read-Only' line adds little there. However, it does disclose the return payload shape ('data: { total, breakdown?, comparison?, sampleMeta? }') and explicitly states that date ranges, period comparisons, and multiple metrics are supported, which is useful behavior beyond what annotations provide.

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

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

Three sentences, each carrying distinct information: what the tool does, what filtering/aggregation it supports, and what it returns. There is no filler. It is front-loaded with the primary action and compactly conveys the return schema.

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 6 optional parameters, no output schema, and a natural-language `query` parameter, the description does most of what an agent needs: it states capabilities, breakdown axes, metrics, and the return shape. It does not explicitly explain how to divide responsibility between the `query` and `dateRange` parameters, but the schema already offers detailed guidance there, so this is a minor gap.

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

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

Schema description coverage is 67%; the parameters that lack descriptions appear to be `metric` and `groupBy`. The description compensates by listing the supported grouping options (category, merchant, month, tag, source, payment method) and metrics (total, count, average). It also reinforces the dateRange behavior by mentioning date ranges and period comparisons.

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: 'Summarize the user's recorded expenses,' and then enumerates the exact grouping dimensions (category, merchant, month, tag, source, payment method). The 'spending' scope clearly distinguishes this from sibling tools like get_income_summary 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 makes it clear the tool is for aggregate expense summaries, but it provides no explicit guidance about when to choose it over financial summary siblings such as get_income_summary, get_deep_analytics, or get_pnl. There is also no when-not-to-use guidance. The usage is implied rather than stated.

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 with 'Read-only; this tool does not create or modify spreadsheet rows.' Beyond that, it discloses non-obvious behavioral traits: only the one or two relevant links should be shown rather than the whole catalog, the Drive folder link must not be invented ('never invent or request a folder ID'), and if a handoff requires owner access, explain instead of presenting a broken link. With annotations lowering the bar, this level of added context is excellent.

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 (a single dense paragraph) and could be improved with bullets or paragraph breaks, which would make it easier for an agent to consult. However, it is front-loaded with the core purpose and general when-to-use trigger, and nearly every sentence carries unique routing information for a handoff that touches many workflows. Acceptably sized at the upper bound, but not a model of concise prose.

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 tool with a large routing surface, the description covers an extraordinary number of cases: spreadsheet access, Gmail scans, bank reconciliation, configuration, category/group management, Google Photos, Drive-storage questions, client billing handoffs, team setup, imports, and reports. It also anticipates failure modes (using owner-access handoffs, never inventing folder IDs) and points to alternative sibling tools when a different action is required. Alongside the provided output schema, the agent has everything it needs to call and interpret this tool correctly.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the schema trivially covers 100% of parameters. Per the rubric, a zero-parameter tool starts at baseline 4, and the description adds no param-related meaning because no params exist. The routing context it provides is rich, but it belongs to usage guidance rather than parameter semantics.

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 first sentence states a specific verb ('Return') and resource ('master ExpenseBot Google Sheet plus authenticated ExpenseBot workspace links'), and clarifies that each link carries a label and a use-case description. This clearly frames the tool as a link-dispatch/router and distinguishes it from siblings like scan_gmail or submit_receipt, which actually perform those operations rather than returning links to them. The only minor friction is that the tool name (get_spreadsheet_url) undersells its broader role, but the description itself removes that ambiguity.

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 is effectively a decision tree: it states explicit triggers ('Use this when the user asks to open, view, check, or edit their spreadsheet'), gives per-scenario link preferences ('After a receipt submission, prefer Review expenses plus the Google Sheet'), and names when-not-to-use alternatives ('If the user names a client and an exact expense scope..., use search_expenses and group_expenses instead'). It even distinguishes selection rules for Gmail, bank/card, category, group, and billing requests. This is the strongest possible 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?

Given the annotations already declare readOnlyHint=true and destructiveHint=false, the description's job is lighter. It adds context by explaining that the tool wraps a specific audit engine and discloses the return value shape, which helps the agent understand what the tool produces. There is 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?

The description is well-structured: it opens with the tool's purpose, gives the key capability, provides query examples, and closes with the return shape. Every sentence adds value and the most distinguishing 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?

The description covers the main behaviors, parameter semantics are fully in the schema, and the return structure is disclosed since there is no output schema. The tool has a straightforward profile with no side effects. The only slight gap is not describing default dateRange behavior, but that is mildly important.

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

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

Schema description coverage is 100%, so all parameters already have helpful descriptions. The description adds example natural-language queries but does not substantially explain 'focus', 'query', or 'dateRange' beyond what the schema already communicates. 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 identifies the tool as a subscription audit wrapper with specific capabilities (recurring, duplicates, price increases, trial conversions). It uses a specific verb and resource and gives concrete example queries. It does not explicitly differentiate from sibling analytics tools like get_spending_summary or get_deep_analytics, so it falls just short of full sibling differentiation.

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 examples ('recurring subscriptions', 'duplicate subscriptions', 'price increases', etc.) provide clear usage context for when an agent should invoke this tool. It does not, however, provide exclusions or point to more suitable sibling tools, so the guidance is clear but lacks explicit alternative routing.

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

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

The description goes well beyond the readOnlyHint and destructiveHint annotations by explaining strict date formatting, tagged evidence, the 'never infer client/project from geography' rule, and the mandatory confirmation flow around nextAction. There is no contradiction between the text and 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?

Though the description is dense, every sentence earns its place: scoping, return contents, inference guards, confirmation flow, and accountant handoff. The most important 'read-only' signal is front-loaded, and no filler phrasing weakens the message.

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

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

Even though there is no output schema, the description enumerates what each proposal returns: strict dates, evidence, locations, receipt IDs, and expected tags. It also covers the two important edge contexts (nextAction present and accountant clientEmail mode), so the agent has enough to call the tool correctly and know what to do next.

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 input schema already documents limit bounds and the clientEmail accepted-client restriction. The description adds useful contextual nuance around accountant-mode behavior, but it does not need to re-explain the parameters, and it does not add significant detail 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: 'Show ExpenseBot's current high-confidence Trip Intelligence proposals.' It also states what the tool is not ('never groups, tags, creates reports, or writes to the spreadsheet'), which distinguishes it from nearby sibling tools. The scope is unmistakable even before reading the schema.

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 behavior: read Trip Intelligence suggestions from Review Expenses, return proposals, and use nextAction only with confirm:false. It also gives a when-not-to-use rule in accountants mode: if nextAction is absent, hand off to Review Expenses or the owner's assistant rather than executing writes from this read result alone.

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 destructiveHint annotation, the description explains crucial behaviors: a premature confirm:true becomes a preview, effective totals are provisional until the terminal result is used, the Bill Client URL is not an invoice, and Personal-tagged expenses are removed before preview. It also calls out destination naming semantics and duplicate report exclusions, giving the agent plenty of context beyond 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 earned and front-loaded with the central purpose and examples. Some sentences are dense or advisory, like directing the agent to keep a response concise, but the complexity of the operation and the many edge cases justify the length. No sentence seems wholly redundant with the schema.

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 no output schema, the description needed note the return content: preview shows exact rows, count, totals, proposed group, exclusions, and conflicts, while the confirmed call returns exact report and BillClient links. It also covers auto-preview, personal expense handling, report-linked exclusions, and user approval requirements, making the overall contract complete for this complex multi-phase tool.

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

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

The schema already has descriptive parameter text with full coverage, so the baseline is 3. The description adds workflow-level meaning to key parameters such as confirm, operationId, selection, and excludePersonal, and clarifies conditional parameters like createReport and reportTitle. It does not further explain status or undo, but the schema already covers those sufficiently.

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

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

The description states a specific verb and resource: 'Group an exact set of recorded expenses' for a client, project, trip, job, or other user-named purpose, with multiple concrete examples. It also distinguishes this tool from siblings by explicitly disclaiming a separate create_report flow, so an agent can separate it from create_report, update_expense, and list_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 a precise workflow: call with confirm omitted/false for preview, show returned rows and totals, get explicit approval, then resend the same operationId and selection with confirm:true. It explicitly names alternatives and exclusions: use createReport on this call instead of running a separate create_report, do not call check_compliance or tax tools unless asked, and share_report remains separate.

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

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

The annotations already establish read-only and non-destructive behavior. The description adds that the data comes from the user's live spreadsheet, which communicates freshness and current configuration 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 compact: it states the resource, gives a clear usage directive, and explains why it matters. Every sentence contributes meaningful information 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?

For a zero-argument, read-only list tool this description is sufficiently complete. It communicates purpose, ordering, and return source, though it could additionally describe the output shape if an agent must parse the result programmatically.

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 accepts zero parameters, so the schema already tells the agent everything needed. The baseline for a zero-parameter tool is 4, and no parameter explanation is necessary.

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 the exact verb and resource: 'List the user's configured expense categories and billing accounts.' It also clarifies that the result is live and user-specific, which helps distinguish it from list_income_categories and list_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?

It explicitly says to call this tool BEFORE tools that need a category name and even names examples: add_cash_expense, add_mileage_entry, create_report. This gives the agent a concrete trigger condition and prevents guessing.

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 behavior context beyond that: explicitly states 'Read-only', explains scope is 'user's issued client invoices', describes the returned fields (invoice numbers, status, totals by currency, delivery state, private document links), and reveals that document links are private — a nuance the agent should know. 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?

The description front-loads the action, resource, and purpose, then flows through examples, status values, and returns. It is a single dense paragraph with every sentence earning its place. The status enum repeates what the schema already has, which is minor redundancy, but overall it's well-organised and concise without 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?

This is a simple, read-only listing tool with 0 required params and no output schema; the description compensates richly by enumerating the return payload (invoice numbers, status, totals per currency, delivery state, private document links) and giving a clear default status. Combined with 100% schema coverage for the remaining parameter semantics, there is nothing essential missing for an agent to call it correctly.

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

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 (limit, status, clientName, clientEmail), including the status enum and defaults. The description lists the status options again and mentions the default 'active', which is slightly redundant with the schema but reinforces default behavior. There's no significant added parameter meaning that would raise it 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 states 'List the user's issued client invoices (accounts receivable)' — a specific verb, resource, and scope — and further clarifies with 'who owes them money, how much, and when it is due.' This clearly differentiates it from siblings like get_client_invoice (single-invoice lookup), create_client_invoice (creation), and mark_client_invoice_paid (mutation) without needing to inspect any schema.

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 concrete trigger queries — 'which invoices are outstanding', 'what does Acme still owe me', 'any overdue invoices' — which give an agent strong, clear context for when this tool is the right invocation for user intent. However, it doesn't explicitly name sibling alternatives or state when NOT to use this tool (e.g., a single invoice lookup should go to get_transactions).

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral context beyond that: these categories are fixed, not user-configured, implying deterministic output and no custom categories, which is important for agents deciding whether to rely on this list.

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 and front-loaded: the primary action is stated in the first sentence, followed by a key distinction and clear operational guidance. Every sentence carries necessary information without 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?

For a zero-parameter, read-only list tool, the description is complete: it says what the tool lists, why those entries are special, and exactly how the result should be used. No critical operational detail 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 tool has no parameters, so schema coverage is effectively 100% and most parameter-related burden is absent. The description still adds value by clarifying that the returned values are canonical strings suitable for add_income.

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 exact verb and resource: listing ExpenseBot's fixed income tax categories. It also distinguishes these from user-configured Expense Accounts, helping the agent identify the correct tool among category-related siblings.

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: call this BEFORE add_income to obtain the exact canonical category instead of guessing. It does not explicitly enumerate alternatives or when not to use the tool, but the strong directive covers the primary decision point.

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

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

Annotations already mark this as read-only and non-destructive. The description adds valuable behavioral context about the accounting handoff URLs: they must only be used when the user explicitly asks to send or export a report. This prevents incorrect invocation beyond what annotations 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 compact and front-loaded with the main purpose, then adds the URL-safety caveat. Every sentence adds useful information, though the phrasing around 'exact report' is slightly awkward.

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 list tool with no required parameters and full schema coverage, the description covers purpose, pagination, filtering, and a critical usage caution. It does not describe the exact return format, but the tool's simplicity and annotations make this 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description restates the filter enum and mentions pagination but adds no new meaning beyond what the input schema provides.

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

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

The description clearly states a specific verb ('List'), resource ('expense reports'), and core behavior (pagination, status filtering). It is distinct from sibling tools like list_client_invoices, though it does not explicitly name alternatives.

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

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

The description does not say when to use list_reports versus siblings such as get_report_details, search_expenses, or list_client_invoices. It provides a caution about accounting URLs, but no guidance on alternative tool 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 safety. The description adds useful context about what tags represent and when to call it, but doesn't disclose return format, ordering, or any potential quirks. With annotations covering the core behavior, this is adequate but not rich.

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

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

Three sentences, front-loaded with the core purpose. The examples and usage condition are spaced efficiently without redundancy. Every sentence contributes value, making it concise and well-structured.

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

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

For a zero-parameter, read-only list tool with no output schema, the description is complete. It covers what the tool does, why tags matter, and when to invoke it. The annotations handle the safety profile, so nothing critical is missing for an agent to decide and call 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 schema provides no param details. Baseline is 4 for 0 params. The description explains the concept of tags, which is the only relevant semantic context. No additional parameter info is 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?

Clear verb+resource: 'List the user's configured groups.' It defines what groups mean (clients, projects, project codes, properties, trips) with concrete examples, distinguishing it from sibling list tools like list_categories and list_reports. The purpose is unambiguous and specific.

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: '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.' This gives clear context but does not name specific alternative tools or state when not to use, so a 4 is appropriate.

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?

Given that readOnlyHint=false and destructiveHint=true, the description adds useful behavioral context by narrowing the mutation scope to only the invoice record and explicitly excluding Income-row creation/movement. It does not discuss reversibility or any additional destructive consequence of marking an invoice paid.

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, front-loaded with the primary action and condition, then a concise and relevant side-effect clarification. No filler or repetition of schema prose.

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 4-parameter mutation with no output schema, the description covers purpose, preconditions, date format, and side effects well. The main gap is a direct pointer to the sibling tool that should be used to actually record the separate Income row.

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?

Input schema has 100% description coverage for all four parameters, so the baseline is 3. The description repeats the paidDate YYYY-MM-DD constraint but does not add meaning beyond the schema for paidVia or paidAmount.

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

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

The description states a specific action ('Mark an issued client invoice as paid'), the exact resource (client invoice or accounts-receivable record), and a key scope boundary: it does not create or move an Income row. This clearly separates it from the income-creation siblings.

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

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

The description gives a clear precondition ('after explicit confirmation'), a strict requirement for paidDate, and a when-not-to-use rule: record the actual payment separately or link an existing Income row. It stops short of naming the specific sibling tool such as add_income, so the alternative routing is slightly implicit.

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 carry readOnlyHint=true and destructiveHint=false, and the description's explicit 'Does NOT add the expense' aligns with and reinforces that safety profile. It adds behavioral value beyond the annotations by showing the return shape in the example, which matters here because there is no output 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?

Three sentences with zero fluff: purpose, negative-scope disclaimer, and an example. The most decision-relevant information ('Does NOT add the expense') is front-loaded right after the verb, and 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 one-parameter read-only parser, the description covers what, why, and what not, with a worked example. The only meaningful gap is that no output schema exists and the example shows a partial field set with an ellipsis, so an agent cannot know the full set of returned fields or edge-case behavior, such as an unparseable string.

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% for the single text parameter, establishing a baseline of 3. The description adds meaning beyond the schema by demonstrating an input-to-output transformation (a full natural-language phrase mapping to structured fields), which clarifies what form of 'text' is expected.

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 and resource ('Parse a natural language expense description into structured fields') and immediately clarifies the tool's non-goal ('Does NOT add the expense'), which separates it from the many add_*/submit_* siblings in the list. The concrete worked example ('Lunch at Chipotle $15.50 today' → {merchant...}) leaves no ambiguity about 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?

The phrase 'just returns the parsed fields for review' implicitly tells an agent this is a preview/parse step rather than a recording step, which helps an agent decide between parse_expense and add_cash_expense/submit_receipt. It stops short of a 5 because no alternative tool is named explicitly, so the routing is implied rather than stated.

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 show readOnlyHint=false and destructiveHint=false, the description adds crucial behavior beyond the schema: it reserves an invoice number/preview, creates no final artifacts, and returns a short-lived preparationId. This disambiguates the side-effect picture even with the annotations present.

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 cover the operation, the workflow, and the exact side-effect boundaries. Every clause carries critical information; no filler or repetition beyond the intentional emphasis on non-creation.

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 14-parameter tool with 100% schema coverage and no output schema, the description supplies the necessary override purpose, the sequencing, the time limit, and the key return values (exact totals, preparationId). Nothing required to invoke or orchestrate the tool correctly 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 has 100% description coverage for all 14 parameters, so the baseline is 3. The description provides useful high-level context about validating the client ledger and reserve but adds no per-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 explicitly identifies the verb ('prepare'), the resource ('client invoice from a saved ExpenseBot report'), and the key constraint ('without creating it'). It clearly distinguishes itself from the sibling create_client_invoice, which an agent needs to call this and later call the create 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?

It gives explicit workflow guidance: 'Call this first, show the preview to the user, then call create_client_invoice after explicit confirmation.' It also clarifies the reservation window ('30 minutes') and what is not created, preventing misuse.

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

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

The description goes beyond annotations by explaining the side effects: emails are converted to PDF, extracted by AI, and added to the expense spreadsheet. It also sets expectations with the 25-email cap and prerequisite. It does not cover outcomes like duplicate handling or whether emails are modified.

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 that front-load the core purpose, then give the call pattern, limits, and prerequisite. No fluff or redundant restating of the tool name or schema.

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

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

Covers the core behavior, input scope, practical limit, and the key prerequisite, which is enough for an agent to understand how to call the tool. However, given there is no output schema, it would be stronger to mention how the agent can check the result, such as a return value or linking to a related status 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?

Input schema already covers both parameters with 100% description coverage, so the description does not need to repeat schema details. It adds the request limit of 25 emails, which is useful, but doesn't deeply explain parameter semantics beyond what the schema provides.

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 operation: process specific Gmail emails as receipts, and describes the full pipeline (convert to PDF, extract with AI, add to expense spreadsheet). This clearly differentiates it from scanning siblings like scan_gmail or scan_gmail_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?

Provides clear context: pass Gmail message IDs, limited to 25 per request, and requires Gmail connection in ExpenseBot settings. It does not explicitly name alternatives like scan_gmail or state when not to use this tool, so it stops 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 behavioral traits beyond the annotations. It states the user must approve before action (confirmation-gated), it creates a deduplicated request, it does not create an integration or make the package immediately available, and it emails ExpenseBot's internal team. It also explains what to tell the user on accepted or previously recorded requests (one-week email update). The annotations provide structural hints but the description's transparency is rich and decisive.

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 dense but not verbose. It front-loads the critical condition (check destinations first) and then explains the action, the non-effect, and the follow-up. Every sentence is functional and no content is wasted. Minor suggestion: could be a touch more compact, but it's strong.

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?

Despite no output schema, the description is self-contained and fully describes the expected behavior, what to the user, and the temporal after-effect. The agent can correctly invoke it and also know what to tell the user. Given the one-parameter tool and multiple interaction steps, this is complete.

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

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

Schema coverage is 100%, so the annotation baseline is 3. The description adds meaningful constraint on the packageName: it must be the exact package name. The description also implies the parameter must be a tested-for package, and the 'exact' requirement is important. This rises slightly 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 identifies the tool's purpose: request support for an accounting package that is not already a reviewed destination. It specifies the exact action (creating a deduplicated request bound to the authenticated account and emailing the internal team) and distinguishes it from actually creating an integration.

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 usage conditions: only use after checking ExpenseBot's reviewed direct and import-file destinations and finding no matching package. It also says when NOT to use it (listed/Beta destination, general compatibility question, without exact package name). This provides clear decision 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?

The description adds valuable behavioral context beyond annotations: it run asynchronously, returns immediately, and delivers a summary email when complete. It does not contradict annotations. It could go further by explaining what 'process receipt emails' concretely does to the user's data, but the asynchronous behavior and notification mechanism are well covered.

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

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

The description is dense and well-structured: it states the action, default scope, async behavior, UI analogy, and relevant alternatives in four short sentences. No sentence is wasted or redundant.

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 async tool with no output schema, the description sufficiently explains what will happen, what the user can expect, and how to follow up. It names the relevant sibling tools for progress-checking and long-range scans, making the complete enough for an agent to act 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?

Input schema coverage is 100%, so the schema already describes all four optional parameters clearly. The description adds a small amount of semantic context around the default range and year-scale usage, but does not meaningfully expand parameter understanding beyond what the schema already provides.

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 specific action: triggering a background Gmail scan to discover and process receipt emails over a default ~60-day window. It distinguishes this tool from scan_gmail_years and get_scan_status by naming exactly what those alternatives are for.

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 explicit usage guidance: use this for recent receipts by default, use scan_gmail_years for whole past years, and use get_scan_status to check progress. This routes the agent to the correct sibling tools without leaving the decision to inference.

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 substantial behavioral detail not present in annotations: the job is long-running, eligible years start immediately while others queue one at a time, each year can take hours, and the user can close the app. It also warns that the current in-progress year cannot be year-scanned. This goes well beyond the readOnlyHint and 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?

Every sentence earns its place: main purpose, queuing behavior, two-step call protocol, alternative tools, and a constraint. The most important workflow instruction appears early and the description stays tight despite covering a complex long-running 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?

The description fully covers what an agent needs to call this tool correctly: what it scans, how to preview before actually starting, how the queue behaves, how long it may take, and how to check status afterward. Given the annotations and schema coverage, nothing important is missing.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful semantic value by explaining the confirmStart preview-versus-start workflow, giving examples for years, and clarifying that the operation needs confirmation. It doesn't dwell on accountEmail, but that parameter is already well-described 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 states exactly what the tool does: scan completed prior years of the user's Gmail for receipts. It also differentiates this tool from scan_gmail, which handles the last ~60 days, so an agent can tell them apart.

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 explicit workflow guidance: call without confirmStart first to preview eligible years, ask the user, then call again with confirmStart:true. It also states when to use scan_gmail instead and when to use get_scan_status, eliminating ambiguity about 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 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?

The description goes well beyond the readOnlyHint/destructiveHint annotations by disclosing pagination semantics, deterministic natural-language matching, AND-combination of structured filters, disambiguation behavior, and the fact that each result includes an exact durable Receipt ID needed by update_expense. It also warns against splitting date ranges and constructing cursors, which helps agents avoid known 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 dense but efficient: the first sentence states the core purpose, and each subsequent clause adds necessary behavior or important operational constraints. Avoidable redundancy is minimal, and the length is justified by the complexity and the number of behaviors an agent must know to call the tool correctly.

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 — 11 parameters, pagination, disambiguation, mixed structured and natural-language filtering — the description covers all critical aspects: pagination flow, cursor reuse, AND semantics, deterministic recall, and the significance of expenseId/Receipt IDs. The output schema exists, so it need not describe exact return formats, and the description still goes beyond the schema to cover usage pitfalls.

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 has 100% description coverage, so the baseline is satisfied by the schema. The tool description mostly summarizes or restates filter semantics already present in the schema, such as the query combining with structured filters via AND and the pagination cursor behavior. Because the description adds little new meaning beyond the schema's rich per-parameter descriptions, it earns the baseline but not more.

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 specific operation: 'Search and filter the user's expenses' and explicitly says it returns matching expense rows from their spreadsheet. This clearly distinguishes it from add, update, report, and tax-related sibling tools. The scope is precise: it is for retrieving already-recorded expenses, not for creating or modifying them.

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 concrete usage instructions: paginate with hasMore/nextCursor, reuse the same filters, do not split a date range into overlapping searches, and expect a disambiguation list when multiple rows plausibly match. It does not explicitly name alternatives or when-not-to-use conditions, but the context and procedural guidance are clear enough to guide an agent.

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 read-only behavior is known. The description adds value beyond annotations by explaining the excerpt-vs-fullAnswer behavior, the truncation retry guidance, and that results are stable. These are meaningful behavioral details, though it doesn't touch on any edge cases or limitations.

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

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

The description is concise, front-loaded with the primary purpose, and every sentence earns its place. It covers what, when, and how to advance detail level without repetitive or filler content. The distinction between 'discovery'' and 'complete instructions' is compact and clear.

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 a read-only annotation, an output schema, and 100% schema parameter descriptions, the structure already carries a lot. The description completes the remaining decisions: when to use it, how to get full answers, when to retry, and the stability property. No significant gap remains for the agent.

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 schema already documents query, limit, and fullAnswer. The description adds semantic value by contextualizing fullAnswer: set true on the first call when complete/detailed instructions are needed, and use excerpt mode for discovery. This gives agents a decision rule beyond the schema's bare default of false.

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 action and resource: 'Search ExpenseBot's complete product and help knowledge base.' It enumerates typical use categories (setup, billing, Gmail, scan, report, workflow, troubleshooting), which makes the tool's purpose unambiguous and clearly sets it apart from expense-search siblings like 'search_expenses' or the more generic 'search'.

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

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

The description explicitly states when to use the tool: '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.' It also distinguishes between excerpt mode and fullAnswer mode with a retry rule. However, it does not explicitly say when NOT to use it or name sibling alternatives, so it stops 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 behavioral traits: it explicitly says 'NOTHING is posted in step 1' and that step 2 'revalidates live state, and rejects changed reports or mappings,' covering failure modes. It also explains the provider restriction rationale (previews cannot freeze/revalidate). Annotations are minimal (readOnlyHint false, openWorldHint true), but the description carries the burden well, providing far more transparency than the 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 well-structured with clear STEP markers, front-loading the purpose and then detailing the workflow. Every sentence adds value, including the limitation about other providers and the rationale. No redundant or filler sentences exist. It is appropriately detailed for a complex two-step tool without being verbose.

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, nested objects, two-step flow, provider restrictions), the description is remarkably complete. It covers all critical aspects: the step-by-step workflow, what happens in each step, constraints, and alternatives. Even without an output schema, the description tells the agent what to expect (a proposal with proposalId) and the confirmation behavior. Nothing an agent needs to use this correctly 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?

Even though schema coverage is 100%, the description adds essential meaning by categorizing each parameter by step (e.g., 'Step 1 only', 'Step 2 only', 'Step 2 only: true posts the exact staged proposal') and explaining behavior (e.g., mode options, forceRepush for uncertain outcomes). This context is not derivable from the schema alone. The description effectively explains the two-phase usage of parameters, which is critical for correct invocation.

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 core function: 'Review and then post an ExpenseBot report to the owner's accounting destination.' It identifies the specific resource (ExpenseBot report) and the action (review and post), and the two-step process differentiates it from sibling tools like share_report or export_report. The title also reinforces the purpose, making it unambiguous for an agent.

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 step-by-step instructions: STEP 1 (preview without confirm) and STEP 2 (confirm with proposalId), including what to do after each step ('Show the complete proposal and ask for approval'). It also clearly states when NOT to use the tool (other providers, non-owner accounts, client actions) and directs to alternatives ('Use those providers' web flows'). 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 flag destructiveHint=true and openWorldHint=true, and the description meaningfully enriches this by adding 'after confirmation,' enumerating what the reviewer can and cannot do ('can open and edit that report's Google Sheet... cannot act for the owner or use accounting integrations'), and disclosing that the accountant option 'creates the established accountant relationship.' This is far beyond what annotations alone convey. 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?

Three sentences, each earning its place: the core operation and confirmation gate, the default role's capabilities and limits, and the alternative role's trigger condition and persistent consequence. The key decision (reviewer by default) is front-loaded, and there is no filler.

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

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

For a destructive, open-world tool with no output schema, the description covers the essential behavioral ground: confirmation requirement, role permissions, exclusions, and the accountant relationship side effect. Minor gaps remain — how recipients are notified and what the return/result of the share operation looks like — but nothing critical to correct invocation is missing.

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

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

Schema description coverage is only 33%, so the description must compensate. It does so thoroughly for recipientRole by explaining each enum value's capabilities and side effects, and it qualifies reportId as 'existing.' However, the recipients parameter is never explicitly described — its meaning is only implied by 'Share.'

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

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

The description states a specific verb and resource — 'Share one existing expense report' — and clarifies the exact scope of the operation. It further differentiates the two sharing modes (reviewer vs. accountant), which maps cleanly onto the recipientRole enum and helps distinguish this tool from siblings like send_report_to_accounting.

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 selection guidance: 'Default to reviewer' for standard sharing, and 'Use accountant only when the user explicitly asks for ongoing accounting access.' This tells the agent exactly when to pick each role and flags the persistent consequence of the accountant choice, leaving little to inference.

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 indicate readOnlyHint=false and destructiveHint=false, the description goes far beyond that by explaining validation, cloud upload, AI extraction, and the fact that the expense appears in the user's spreadsheet in 1-3 minutes. It also discloses batch rejection behavior (if any file fails validation, the whole batch is rejected and nothing is processed). This gives an agent a realistic model of what will happen after invocation and how to set user expectations.

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

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

The description is long but well-structured: it begins with the core purpose, then lays out the preferred upload flow, then covers single-photo and fallback paths, and closes with metadata behavior. Some redundancy exists with the already-detailed schema, but the length is justifiable given the complexity of the two phase upload workflow, nine parameters, and the lack of an output schema.

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 without an output schema and with a complex multi-step upload protocol, the description is nearly fully self-contained: it defines the initial filesToUpload call, the upload actions, the final uploadRefs call, batch rejection behavior, and where note/tag values are stored. It also explains which input parameter to choose for each file and client variant, making 'how to invoke this safely and correctly' very clear. No additional external contract instructions seem 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?

Input schema has 100% per-parameter description coverage, and the schema itself is extremely detailed. The description still adds useful operational semantics beyond the schema, such as the one-at-a-time HTTP PUT upload, the instruction to announce file progress, and the requirement to call the tool once with all uploadRefs, which slightly exceeds the schema's own wording. It doesn't reach 5 because many parameter details in the description are effectively restatements of 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 opens with a specific verb and resource: 'Submit a photo or PDF of a receipt for processing.' It then lists exact user phrasings ('log this', 'save this', 'expense this') that this tool should handle, which makes it distinguishable from siblings like add_cash_expense or add_income_from_file. It clearly positions itself as the receipt-image/PDF intake tool rather than a manual expense entry or Gmail scanning 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 explicit when-to-use and when-not-to-use instructions: filesToUpload is preferred and required for PDFs, photo is for a single ChatGPT attachment, photoBase64 is only a fallback, and the user is told never to call the tool once per file. It also explains when to call the tool a second time with uploadRefs and what batch semantics apply, so an agent knows exactly how and when to invoke this tool in its workflow.

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