ExpenseBot

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true), the description discloses that it writes directly to the spreadsheet after confirmation, reuses or creates the canonical client group, applies 'Cash advance received', and stores advance amounts as negative. These are non-obvious side effects an agent could not infer from the schema. It stops short of stating duplication/permission behavior, so not a full 5.

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

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

Purpose and both modes are front-loaded, and every sentence carries routing or behavioral information. The final exclusion sentence is long and list-heavy, but it earns its place by preventing common misrouting.

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 12-parameter write tool with an output schema (so return values need not be explained), the description covers both operating modes, prerequisites, side effects, and the alternative path. An agent has everything needed to call it correctly or route 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?

Schema description coverage is 100%, so all twelve parameters are already documented in the input schema, including the negative-storage convention for total and the clientName/isClientAdvance relationship. The description mostly restates those semantics, adding only the list_categories prerequisite. Baseline 3 is appropriate when the schema carries the parameter burden.

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

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

The description names a specific verb and two distinct modes of the resource: 'Add an expense without a receipt' and 'record money a client provided in advance.' It clearly differentiates from siblings like submit_receipt, parse_expense, add_income, and update_expense by scoping itself to receiptless cash entries and client advances.

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 preconditions per mode ('call list_categories first and provide a configured Expense Account'; 'set isClientAdvance=true and clientName'), states a strong negative boundary ('never for vendor refunds, reimbursements, earned fees, retainers, or generic deposits'), and names a concrete alternative ('Use the Manual expense link from get_spreadsheet_url instead when...'). This is textbook when/when-not/alternative guidance.

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

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

Annotations only declare the generic write profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true). The description adds real behavioral context: the write target (Income tab of the expense spreadsheet), the single-payment constraint, that sibling tools stage a duplicate-checked preview requiring confirmation, and that an unknown category is rejected while an omitted one defaults to Service income.

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?

Front-loads the core constraint (exactly one payment) in the first sentence, then the anti-pattern, then alternatives, then destination and category rule. Every sentence carries a distinct instruction 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?

An output schema exists so return values need no explanation. For a 12-param mutation tool with annotations, the description covers the cardinality rule, the sibling routing, the write destination, and the category prerequisite — everything an agent needs 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 coverage is 92%, so the baseline is 3. The description still adds value beyond the schema by mandating the list_income_categories lookup and stating the rejection/default behavior for the category parameter, plus the paymentMethod normalization note is reinforced 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?

States a specific verb and resource ('Log exactly one user-confirmed income payment manually') plus concrete scope ('one', 'manually') and enumerates example rails. It explicitly differentiates itself from add_income_from_csv and add_income_from_file, so an agent can pick it apart from siblings 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?

Explicit when-to-use ('income that isn't auto-detected from Gmail or Plaid'), explicit when-NOT ('Never loop this tool over a statement, export, table, or multi-row list'), and names the exact alternatives for the two-or-more case along with the condition that selects them.

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

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

Goes well beyond the annotations by disclosing that Step 1 writes nothing, that duplicates require explicit keep approval, that unknown/expired previews never write (15-minute expiry), and which URLs are returned. These are the safety-critical behaviors an agent needs before invoking a write path.

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?

Front-loads the purpose and the size limit, then walks the two steps in order, and every sentence carries operational content. It is dense and the long sentences could be split, but nothing is wasted for a tool of this 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 ten parameters, nested objects, and an output schema, the description covers the full call lifecycle: input sources, the staged-then-confirmed flow, duplicate handling, expiry, and the returned URLs. Nothing an agent needs to call 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, but the description adds cross-parameter semantics the schema alone lacks: confirm:true must be paired with the previewId from Step 1, and rowEdits/keepBothIndexes operate on staged rows. This meaningfully clarifies how the parameters interact across the two calls.

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 ('import the user's CSV/TSV/text income export') and bounds the input with a size limit (max 500 KB). The CSV-import scope clearly separates it from add_income and add_income_from_file, so an agent can distinguish it without opening 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?

It lays out a concrete two-step workflow (Step 1 stage preview, Step 2 confirm) and states an explicit exclusion: accepts user-provided attachments or inline text, not arbitrary web URLs. It never names a sibling alternative such as add_income_from_file, so the routing guidance is strong but not fully comparative.

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 cover readOnlyHint/destructiveHint/openWorldHint; the description adds substantial context beyond them: nothing is saved in step 1, the preview expires after 15 minutes, an expired or unknown previewId never writes, duplicates are checked against the Income tab, and file size (10 MB) and edit limits (50 rows, 120-char note) are stated. The write-on-confirm behavior is consistent with destructiveHint=false since it adds rows rather than deleting.

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?

Front-loaded with the purpose, then organized as an explicit STEP 1 / STEP 2 sequence, so the density is navigable. It is long, but nearly every sentence carries operational detail (expiry, duplicate handling, which params apply to which step); a small amount of repetition about 'step 2 only' could be trimmed.

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

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

For an 11-parameter, nested-object, two-phase mutation tool with an output schema, the description covers the parse/confirm lifecycle, safety framing, expiry behavior, and follow-up URLs. Nothing an agent needs to call it correctly is missing, and return values are left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: which parameters belong to step 1 versus step 2, the consent framing for the attachment, the 50-row cap on rowEdits, and the semantics of keepBothIndexes and selectedIndexes. It goes beyond restating the schema descriptions.

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

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

States a specific verb and resource ('Import income from an attached screenshot, image... or PDF') and immediately scopes it with concrete source examples (payment screenshots, wallet apps, payout/bank statements). An agent can distinguish this from siblings like add_income and add_income_from_csv purely from the first sentence.

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 describes the two-step flow, when to call without confirm (parse/preview only) versus with confirm: true (write), how to treat duplicates (skipped unless keepBothIndexes), and it names a sibling alternative (get_spreadsheet_url) for complex visual reviews. The when-to-use and when-not-to-use conditions are fully spelled out.

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

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

Annotations declare the write safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds value beyond them: it discloses that a row is written to the user's expense spreadsheet with a calculated dollar value, and that mileage rate/unit settings must exist first. It does not cover duplicate handling or what happens if settings are missing.

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, front-loaded with the action, then prerequisite, then side effect, then alternative. Each sentence earns its place, though the audience list ('realtors, consultants, contractors') is soft filler that could be trimmed.

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

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

With 9 params, an output schema present, and annotations covering the safety profile, the description supplies exactly what structured fields cannot: the prerequisite configuration, the write side effect, and clear routing away from the sibling alternative. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so every parameter (including roundTrip's doubling behavior and the date timezone guidance) is already documented in the schema. The description only reinforces the unit dependency for `distance`; baseline 3 is appropriate when the schema carries the 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?

States a specific verb+resource ('Log a business mileage trip in ExpenseBot') and immediately contrasts it with the sibling route via get_spreadsheet_url. An agent can distinguish this write-tool from add_cash_expense, add_income, and get_trip_suggestions without opening a 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?

Gives an explicit prerequisite (user must have configured mileage rate and unit), a named alternative tool (`Mileage and travel link from get_spreadsheet_url`) and enumerates the exact conditions that select that alternative (Maps routing, repeated trips, calendar/rideshare import, per diem, visual review). 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the explicit anti-automation guardrail and the 'do not infer consent' rule, which constrain how the agent may trigger 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?

Two sentences, the positive trigger front-loaded and the exclusions following. Every clause is load-bearing for correct invocation; 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?

An output schema exists so return values need no explanation, and annotations cover safety. The description covers the remaining gap — precise trigger conditions and prohibitions — so an agent has everything needed 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% and the analysisRequested description already explains the explicit-consent requirement, so the schema carries the parameter burden. The description reinforces but adds no syntax or format detail beyond it; 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?

States a specific verb and resource ('check an existing report for compliance issues') and names what those issues are (missing business purpose, policy violations). It is clearly distinguishable from siblings like create_report and fix_compliance.

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

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

Explicit when-to-use ('only when the user explicitly asks') plus an enumerated when-not list (creating a report, excluding Personal expenses, sharing, billing) and a prohibition on automatic preflight/follow-up invocation. Nothing about invocation conditions 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?

With annotations already declaring readOnly/openWorld/destructive hints, the description adds useful behavioral context: it queries a public knowledge base, returns a confidence-scored answer plus related questions, and does not require authentication. 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?

Two concise sentences with examples front-loadedclause by clause. No filler, every sentence earns its place.

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

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

For a simple, read-only, single-parameter tool with rich annotationschedema and a described return shape, the description is fully adequate for an agent to select and invoke it correctly.

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

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

Schema covers the single parameter 100%, including a description and example. The description's example queries reinforce semantics but don't add meaningful new information beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: checking whether ExpenseBot supports a specific feature, with examples of natural language queries. It distinguishes from check_compliance and check_tax_deductibility by focusing on feature support, though it doesn't explicitly distinguish itself from the similar 'search' 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?

Provides clear context with example phrasings ('does ExpenseBot support X', 'can it integrate with Y'). States that it searches the public knowledge base and works with or without authentication. Doesn't explicitly exclude alternatives, but the examples serve as strong usage signals.

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 is consistent ('Read-only: it does not classify saved expenses, prepare a return, or determine the user's actual tax liability'). Beyond that it discloses non-obvious behavior the annotations cannot: the lookup keys off the account's tax-country/home settings and current year, and verified rules return a percentage plus reference while unverified rules return unknown/reviewRequired with no percentage.

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?

Front-loads the core 'when to use' before the behavioral and exclusion details, and each sentence carries distinct information (use case, lookup mechanism, return semantics, scope limits, exclusion). It is slightly longer than strictly necessary with some overlapping negative statements ('does not classify... prepare a return... determine liability'), but nothing is 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?

Despite the tool's non-trivial logic, the description covers the trigger, the settings-dependent lookup, the two possible return shapes, the read-only scope, and the sibling alternative. An output schema exists, so return-value documentation is not required, yet the two outcome branches are still flagged, leaving nothing an agent needs 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 documents query, category, and merchant, including the 'no account numbers or unrelated personal context' constraint. The description adds little parameter-level detail beyond re-emphasizing the expense-type framing, 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?

States a specific verb+resource ('looks up reference rules' for an expense type's deductibility) and scopes it precisely ('general deduction guidance... such as business meals or home-office expenses'). It also explicitly differentiates from a sibling by naming get_income_summary for refunds, so an agent can separate it from the other tools without opening a 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?

Gives an explicit use case ('when the user asks for general deduction guidance for an expense type') and an explicit exclusion with the alternative named ('Do not use for tax refunds received as income; use get_income_summary for recorded refunds'). The routing decision is fully determined.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, and the description adds far more: an automatic grounded preview with count and before-to-after diffs, premature confirm being downgraded to preview, idempotency via a stable operationId, Notes preservation and Formula Notes/limit skips, applied/conflicted/failed reporting, and Undo support. This is exactly the safety and side-effect detail that matters for a destructive mutation.

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?

Front-loaded with purpose then workflow then constraints, and the examples are useful. It is long and dense for a single paragraph, with a few clauses (e.g., the Notes-limit/Formula skip detail) that could be tightened, but almost every sentence carries operational 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 destructive, nested-object mutation with an available output schema, the description covers selection provenance, concurrency expectations via 'expected' fields, preview/confirm gating, idempotency, and failure counts, so an agent has everything needed to call it correctly. Return-value detail is appropriately left to the output schema.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description still adds meaning: 'repeat the same operationId, selection, and change with confirm:true' explains the sequencing contract, and 'attendeeMode add preserves existing attendees, while replace substitutes only the attendee segment' clarifies replace semantics beyond the schema's terse 'Use add unless...'.

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 bounded precisely ('Safely correct the category, business purpose, or explicit attendees on an exact bounded set of recorded expenses') and enumerates concrete examples. It also carves out what it does NOT do ('does not omit duplicates, change amounts or dates, infer business context, or run broad Calendar matching'), which separates it from the broader update_expense sibling even without naming it.

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?

Prescribes an explicit workflow: first call search_expenses to identify exact rows, then pass full expenseId values, preview automatically, and only confirm after explicit approval reusing the same operationId/selection/change. It also names the exclusion route ('unsupported or more than 100-row cleanup' → review URL), so when-to-use and when-not-to-use are both covered.

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 destructiveHint annotation by detailing side effects: revalidating snapshot/client identity, creating Google Doc/PDF/DOCX copies, recording the invoice, and superseding an older active invoice. It also explicitly frames the operation as 'a confirmed write,' giving the agent accurate 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?

Four tightly written sentences deliver the core purpose first, then side effects, exclusions, and the key conditional rule. Every sentence earns its place with no filler or repetition of schema fields.

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

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

Given this is a destructive write operation with an output schema, the description covers all essential context: preconditions, created artifacts, supersession effect, excluded side effects, and the tax confirmation requirement. An agent has enough information to decide when to invoke it and what to expect.

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 useful semantic context on top, such as confirmTax being required only when tax is positive and preparationId being the short-lived ID from prepare_client_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?

States a specific verb and resource: 'Create the exact invoice previously returned by prepare_client_invoice.' This clearly distinguishes it from read-only siblings like get_client_invoice and list_client_invoices, and from related actions like mark_client_invoice_paid.

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 ties invocation to a prior call to prepare_client_invoice, and clarifies what the tool does not do ('does not send email or create an Income row'). It also gives a concrete conditional rule: 'If tax is positive, confirmTax must be true.'

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

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

Annotations declare destructiveHint=true, openWorldHint=true, readOnlyHint=false, so the safety bar is partly covered. The description adds substantial non-schema behavior: dedup logic (no duplicate report if no unreported matches), the scope rule that grouped reports pull in unassigned matching expenses, sharing/role semantics, and the caveat that the link does not mean an export occurred. It stops short of explicitly framing the mutation/destructive impact on expense assignment.

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?

Purpose is front-loaded and readable, but the description is long and overlaps the schema (excludePersonal, recipientRole, shareWith) and the output schema (returned summary, links, applied filters, handoff URLs). Several clauses restate structured fields rather than adding new signal.

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 mutation tool with annotations and an output schema, the description covers the critical gaps: dedup behavior, scope of included expenses, sharing roles, sibling-tool routing, and the meaning of the returned link. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description still adds meaning: it explains that excludePersonal removes both the Personal tag and the Personal category (matching Report Wizard) and clarifies the reviewer vs accountant intent for recipientRole, going 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?

States a specific verb (Create) and resource (expense report) plus the scoping inputs (date, client, project, trip, category, merchant). It is clearly distinguishable from siblings like list_reports and get_report_details, which are read/retrieval operations.

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 routes to list_tags when the group is unclear, gives a concrete trigger for excludePersonal ('all expenses in August except personal'), and explicitly forbids calling check_compliance, get_report_details, or tax tools before/after unless asked. This is when-to-use, when-not-to-use, and alternatives all in one.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: the PDF is 'short-lived', the report must be 'authorized', and the in-app link is 'exact highlighted'. It also clarifies that the tool only provides URLs, not the actual file contents, which is useful behavioral information 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?

Three sentences with zero waste. The core purpose is front-loaded in the first sentence, the alternative use case is in the second, and the prerequisite is in the third. 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 single-parameter read-only tool with an output schema, the description is complete. It covers what the tool returns (PDF URL + in-app link), when to use it, when not to use it, and the prerequisite. The output schema handles return value details, so nothing an agent needs to call 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% and the only parameter (reportId) is described as 'Report ID from list_reports'. The description reinforces this by saying 'Use list_reports first to find the reportId', which adds provenance context beyond the schema. With a single parameter and full schema coverage, the description adds just enough extra meaning.

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

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

The description states a specific verb ('Get'), a specific resource ('one exact authorized expense report'), and the exact output format ('short-lived direct PDF download' plus 'exact highlighted in-app report link'). It clearly distinguishes itself from sibling tools like get_report_details and share_report by focusing on export URLs rather than details or sharing workflows.

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 says when to use this tool ('Use the in-app report for CSV, XLSX, receipt ZIP, comments, invoicing, and other visually reviewed actions') and provides a prerequisite ('Use list_reports first to find the reportId'). This gives clear routing guidance and tells the agent what to do before invoking.

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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds useful context beyond that: the return payload ('full text content + metadata for the AI to cite') and a concrete failure warning (expense ids are never sheet row numbers because rows shift), which is genuinely non-obvious behavioral information.

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?

Front-loads the core action, then bullets the three id families with examples. The encoded example strings ('expense:RR-123%3A%3Adrive%2Ffile%209') are somewhat dense, but each sentence carries actionable content rather than 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 single-parameter read tool with an output schema, this is complete: it covers every accepted id form, how to obtain each, the exact-usage constraint, and what comes back. 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 exceeds that by expanding the id grammar with real examples, the URL-encoding requirement, and the row-number pitfall — meaning the agent understands more than the regex pattern alone conveys.

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+resource (fetch full details for a specific item) and constrains it to items previously returned by `search`. It distinguishes itself from the list-oriented `search` sibling, but does not differentiate from detail-oriented siblings like `get_expense_by_id` or `get_report_details`, so an agent may not know which detail tool to pick.

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?

Gives clear context: use it on an id returned by `search` or `list_reports`, and 'always use the id exactly as returned... do not invent or modify.' It names the producing tools but offers no when-not-to-use guidance or routing against the other detail tools.

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

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

Goes well beyond annotations: discloses the preview-first / no-change-on-first-call behavior even if confirm:true arrives early, the idempotency contract (repeat same operationId/selection/change), approval gating, result reporting (applied/conflicted/failed counts), and Undo support. Destructive and openWorld annotations are consistent with the described mutate+Undo profile.

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?

Front-loads scope and safety in the first clauses and stays information-dense, but the single paragraph runs long and mixes workflow, constraints, and fallback routing; a sentence break would improve scannability.

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 destructive, confirmation-gated, idempotent mutation with an output schema present, the description covers the full agent-relevant surface: preconditions, preview/confirm loop, idempotency, conflict handling, and escape hatches. 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%, so the schema already carries most parameter detail. Description adds meaningful semantics the schema doesn't: the identity-vs-row-selection distinction on expenseId, never infer business purpose/category/attendee, and the confirm/operationId pairing. Minor value-add over an already complete 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?

States a specific verb+resource (correct compliance issues on a bounded set of recorded expenses) and explicitly positions itself against siblings check_compliance, correct_expenses, group_expenses. An agent can route without opening 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?

Explicit when-to-use ('only after the user explicitly asks to fix issues found by check_compliance'), prerequisites ('use search_expenses to obtain each full expenseId'), and named alternatives ('for tags/groups use group_expenses', overflow link for >100 rows). Exclusions are stated clearly.

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 description's claim of being read-only is redundant but consistent. However, the description adds context beyond annotations: it specifies that the tool returns selected organization/company/business, connection state, rollout state, and the setup link null, and notes that posting is not performed. It also mentions that some providers have writesAuthorized=false, which is useful behavioral context. No contradiction.

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

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

The description is moderately long but well-structured: it states the core purpose first, then details the return valueschers, then the reportId usage, then the read-only/posting qualifier. It is front-loaded with the most important informationholistic. The latter part about providers is slightly verbose but provides necessary navigation between providers, so it earns its place.

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

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

Given the tool has an output schema, the description does not need to list return fields in detail, but it does mention what is returned (organization, connection state, rollout state, setup link). It also clarifies the nuanced provider limitations (e.g., only Zoho Books has writesAuthorized=true). The tool is not overly complex, and with annotations and schema covering safety and parameters, the description provides sufficient context for correct invocation. A 4 is appropriate.

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 both parameters. The description adds a small amount of meaning beyond the schema: for reportId, it explains that the setup link opens the exact report's provider setup control, which is more specific than the schema's 'opens this exact report'. For provider, the description adds that certain providers are accepted for connection onlyholistic. But overall, since the schema already covers the parameters well, 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 the tool checks connection status and read-only setup state for an accounting destination, with a specific verb (check) and resource (accounting integration status). It distinguishes itself from siblings like request_accounting_integration (which initiates connection) and get_accounting_push_status (which is about posting), by explicitly mentioning connection/setup state and read-only behavior.

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 guidance: when an existing ExpenseBot report is available, pass reportId to open the exact report's setup control. It also explicitly lists which providers are supported for what purpose—agent-driven posting only for Zoho Books, others for connection only. This clearly tells the agent when to use this tool and how it differs from posting-related tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; description adds value by stating the tool is read-only and owner-account only, and by listing the exact fields returned (status, submission time, posting mode, posted receipt count, public error, reconciliation requirement). It also discloses a safety rule (never re-post) which goes beyond annotations. 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?

Four sentences, each earning its place: purpose, usage trigger, return summary, and constraint. Front-loaded with the primary action and scope. No filler or redundancy.

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

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

For a two-parameter read-only tool with an output schema, the description covers the essential use case (checking status after timeout), the return contents, and the critical behavioral rule (don't re-post). It also notes the owner-account restriction. Nothing critical 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?

Schema descriptions already fully document both parameters: provider enum with its purpose and reportId with exact identification requirement. The description does not add extra parameter-level meaning beyond what the schema provides, so a baseline of 3 is appropriate given 100% 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?

States a specific verb (read) and resource (posting and reconciliation status for one report at a destination). Distinguishes from siblings like get_accounting_integration_status (integration status) and get_report_details (report details) by specifying 'authoritative' and 'one report'. Clear and unambiguous.

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

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

Explicitly says 'Use after a timeout or uncertain response before considering any retry', giving a clear trigger condition. Also provides an exclusion: 'Never re-post a completed report or a report marked needs_reconciliation; show that state to the owner instead.' This is direct guidance on when to use and what not to do, even though it doesn't name specific alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with a strong behavioral guarantee: 'never records a refund, creates an invoice, or recomputes the ledger in model prose.' It also clarifies the meaning of positive/negative balances, which is not in the schema. This goes beyond annotations by explaining what the tool does NOT do, which is valuable for an agent to avoid accidental side effects.

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

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

The description is concise but information-dense. It starts with the core purpose, then gives examples, then explains the sign convention, then the return value, and ends with the read-only guarantee. No sentence is redundant; each adds actionable detail. The structure is front-loaded with the main purpose, making it easy for an agent to scan.

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

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

For a read-only tool with two optional parameters and an output schema, the description covers the essential usage: how to invoke it, what the balance signs mean, and what it returns. It doesn't discuss error handling (e.g., invalid client name) but the output schema likely covers that. It also doesn't mention rate limits or auth, but given the read-only nature and annotations, this is sufficient. Slightly incomplete because it doesn't note any caveats about data freshness or multi-currency, but overall it's quite complete.

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

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

The schema covers both parameters with descriptions (coverage 100%), so the baseline is 3. The description adds extra value: for clientName, it clarifies that omitting it lists all open balances; for clientEmail, it restricts usage to accepted ExpenseBot clients. These clarifications are not in the schema and help the agent understand optionality and constraints. This exceeds the baseline.

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

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

The description clearly states the tool reads per-client advance balances, references the exact UI section ('Client advances section'), and provides concrete example questions. It also explains the sign convention (negative means refund, positive means client owes), which removes ambiguity. This distinguishes it from any sibling that might deal with invoices or refunds, though it doesn't name a specific alternative.

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

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

The description gives explicit use cases ('Use for questions like...') and explains the optional parameter behavior ('Omit to list every open balance'). It also mentions the return handoff for refund/bill actions. It doesn't explicitly state when not to use it or compare to alternatives, but the examples are clear enough for an agent to select it correctly. A slight gap is the lack of a note about using it vs. other financial tools like get_credits_refunds.

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

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

Description explicitly states read-only behavior, consistent with the annotation, and adds detail about return contents and the 'when available' caveat for private document links.

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?

Front-loaded purpose, enumerates the key returned fields, states the input requirement and read-only nature. Dense but efficient; 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?

The description explains what data is returned, how to identify the invoice, availability caveats, and read-only safety. Combined with schema and annotations, nothing essential is missing for a getter.

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

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

Schema descriptions already fully document the parameters; tool description reinforces the one-required rule and uniqueness condition but adds little beyond schema. No contradiction.

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?

Uses a specific verb ('Get') and a clear resource ('full financial and delivery summary for one issued client invoice'), and enumerates the returned fields. This distinguishes it from list/prepare/update invoice 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 clear guidance on the required identifier, the one-required rule, and the uniqueness constraint on invoiceNumber. Does not explicitly name alternatives, but the usage context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only: it never scans cards, changes review decisions, or adds rows.' This adds behavioral context beyond the annotations, clarifying what the tool does NOT do. It also discloses default behavior (most recent items, default 25, newest first) and the dateRange narrowing option.

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: it states the resource and scope in the first sentence, provides example queries, and then gives behavioral and parameter context. Every sentence earns its place, and the read-only note is a useful addition without bloat.

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

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

The description is complete for a read-only list tool: it covers what is returned, default behavior, narrowing options, and read-only guarantees. The output schema exists, so return values are documented elsewhere. It could mention the clientEmail parameter's purpose, but the schema already covers that, and the description's focus on usage and behavior is sufficient.

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 three parameters (limit, dateRange, clientEmail). The description adds context for dateRange ('narrow with dateRange') and limit ('default 25, newest first'), but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('List') and resource ('card refunds, cashback/rewards, and statement credits that ExpenseBot has already recorded'), and clarifies the scope ('either as negative expenses or matched against the original charge'). It also provides example user queries, which makes the tool's purpose immediately recognizable. It distinguishes itself from sibling tools like get_recent_activity or search_expenses by focusing on recorded 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?

The description gives clear context for when to use the tool ('did my refund come through', 'show my statement credits', 'was that return recorded') and notes it returns recent items with a default limit and dateRange narrowing. It does not explicitly name alternative tools or state when not to use it, but the examples and scope make usage conditions clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description enriches this with important operational behavior: it runs as a background job, takes 10-30 seconds, is polled automatically, and may return truncated data via sampleMeta.isTruncated. This goes beyond the structured annotations and gives the agent accurate expectations for latency and result completeness.

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

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

The description is three sentences with no fluff: purpose, example use cases, latency/background behavior, and return shape are each packed into distinct, front-loaded statements. Every sentence earns its place and the key operational constraint (10-30 seconds) appears early.

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 analytics tool, the description covers purpose, invocation context, asynchronous behavior, and important return metadata (sampleMeta.isTruncated). The schema and output schema handle the parameter and return details, so nothing critical is missing for an agent to call this 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 both `query` and the `dateRange` variants in detail. The description reinforces the query semantics with examples but does not add substantial new parameter meaning beyond what the schema provides. This is the appropriate 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 states a specific verb and resource ('Run deeper, multi-step analytics on the user's expenses') and gives concrete example questions that distinguish it from simpler reporting tools like get_spending_summary or get_pnl. The 'deeper, multi-step' phrasing and explanatory-question use cases make the tool's purpose clear and differentiated.

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 says 'Use for explanatory questions' and provides examples, giving clear guidance on when to invoke this tool. It does not explicitly name alternatives or state when not to use it, so it stops short of a full when-to-use vs. when-not-to-use matrix, but the context is unambiguous enough for an agent to route correctly.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower; the description still adds value by enumerating what it will not do and by listing the returned payload (sheetName, rowNumber, headers, values, labeled fields, reviewExpenseUrl). 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?

Four short sentences, front-loaded with the core action and the identifier requirement; the closing negative list is slightly redundant with the readOnly annotations but earns its place as explicit scope bounding.

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

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

With an output schema present, the description need not explain returns, yet it still covers the zero-required-parameter nuance (must supply one identifier), the identifier provenance, and the non-destructive scope. Nothing an agent needs to call 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?

Schema description coverage is 100%, so the baseline is 3, but the description adds provenance the schema lacks: the expenseId must come from search_expenses and corresponds to Receipt ID in Column Q, and rowNumber is an alternative the user may specify. It also implies that one of the two identifiers must be supplied even though the schema marks neither as required.

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

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

States a specific verb+resource ('Read one existing expense from the authenticated user's ExpenseBot spreadsheet') and immediately scopes it against siblings by declaring it 'does not edit, submit, delete, share, or scan anything', distinguishing it from update_expense, submit_receipt, and the scan_* 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?

Gives explicit input-sourcing rules: use the exact expenseId returned by search_expenses (Column Q) or the user's specified rowNumber, and 'never invent an identifier'. It names the alternative tool (search_expenses) that produces the required identifier, so the when-to-use path is unambiguous.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses important behavior: split lines are never counted as separate expenses, so totals stay correct, and the tool returns a single parent payment with nested allocation lines. It also tells the agent that splits are edited elsewhere, which clarifies the tool's non-mutating role.

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, leading with the core action, then key behavioral nuance, then examples, then a read-only note. No sentence is wasted, and the structure makes the tool's purpose immediately scannable.

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 what the tool does, how results are shaped, how totals behave, when to use it via examples, and the read-only context. With a full input schema, annotations, and an output schema present, nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so all five parameters are already documented with types, defaults, and constraints. The description adds useful conceptual context but does not need to restate parameter semantics; the baseline of 3 applies because the schema carries the burden.

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

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

The description uses a specific verb ('Show') with a clear resource ('how an expense was split') and enumerates the dimensions of splits: categories, clients, properties, business/personal portions. It also clarifies that it returns parent payments with nested allocation lines, distinguishing it from ordinary expense lookup tools like get_expense_by_id or search_expenses.

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

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

The description provides natural-language examples ('how is that expense split', 'what was the business portion of that bill') that signal when the tool is appropriate. It also adds the read-only note and directs editing to ExpenseBot's Review workspace, giving clear context, though it does not explicitly name alternative tools or state when not to use this one.

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 readOnly/openWorld=false/destructive=false, and the description adds real context beyond them: it discloses the return shape (message plus data with total, optional breakdown, comparison, sampleMeta) and draws hard boundaries against scanning, importing, or mutating. It does not discuss pagination or result limits, so it falls short of a 5.

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

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

Front-loaded with the trigger condition, then scope, then return shape, then exclusions — a sensible ordering with no filler sentences. It is fairly dense, packing five groupBy values and multiple exclusions into two sentences, but nothing is wasted.

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

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

An output schema exists, so return values need not be explained further; the description covers trigger, scope, grouping/filtering dimensions, comparison support, and explicit non-goals. Nothing an agent needs to invoke 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?

Schema description coverage is 100%, so the schema already documents query, groupBy, dateRange variants, and incomeTagPrefix in detail. The description largely restates the groupBy enum values and filter fields rather than adding new 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?

States a specific verb (read totals) and resource (income recorded in the ExpenseBot Income tab) and enumerates the grouping and filtering dimensions. It is clearly distinguishable from siblings like get_pnl, get_spending_summary, and get_mileage_summary without opening 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?

Explicit trigger ('Use this when the user asks about income already recorded in their Income tab') plus an explicit exclusion list ('No scanning, imports, mutations, tax returns or liability determination') that routes those needs away from this tool. Both when-to-use and when-not are covered.

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 declare readOnlyHint/openWorldHint/destructiveHint, but the description adds substantial behavior: pending is normal and found:false is non-terminal, held_for_review files were not added, unknown outcomes stay unknown, and spreadsheets must not be shown as the destination for held files. This is genuine operational context beyond the safety 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 purpose and trigger are front-loaded, but the description runs long and includes a cluster of guardrail sentences ('do not invent a missing card', 'do not blindly resubmit') that partly repeat the same intent. It is dense and useful but not tightly sized relative to a 2-parameter read-only tool.

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

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

An output schema exists, yet the description still supplies the terminal/pending semantics and verdict vocabulary an agent needs to interpret results. For a polling tool with cross-tool dependencies, nothing essential is missing.

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

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

Schema description coverage is 100%, so both submissionId and withinSeconds are already documented, including the 'strongly preferred' rationale and the 30-3600 fallback range. The description reinforces using the exact ID from the submit_receipt response but adds little syntactic or format meaning beyond the schema, matching 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?

States a specific verb and resource ('Check the authoritative final outcome of a receipt image/PDF batch') and ties it to submit_receipt explicitly. It also differentiates from the sibling get_scan_status ('This is for uploaded receipts; use get_scan_status for Gmail scans'), so an agent can pick between them without opening a 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?

Gives an explicit trigger (call after submit_receipt returns a submissionId, using that exact ID and the polling interval/time allowance from the response) and names the alternative tool plus its condition (Gmail scans -> get_scan_status). It also warns that a pending result must not trigger a duplicate resubmission, which is a clear when-not-to-act rule.

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, non-destructive safety profile. The description adds genuine behavioral context: country-aware IRS/CRA rates, cents-per-mile/km deduction framing, and YoY/MoM/QoQ comparison handling. It does not discuss edge cases like empty data, but that is a minor gap for a read-only summary tool.

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

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

The description is compact, front-loads the core purpose, and packs example queries, grouping dimensions, comparison support, and return shape into two sentences worth reading. There is no filler, repetition, or tautology.

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 rich output schema, full parameter documentation, and read-only annotations, the description only needs to cover scoping and use conditions. It does so with practical examples, comparison semantics, and country-aware deduction behavior. It could still be more explicit about sibling-tool routing or how query, groupBy, and dateRange interact, 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?

Schema coverage is 100%, so the baseline is 3; the description adds useful example queries and return-shape context. However, it mentions breakdowns 'by client' while the groupBy enum exposes 'tag' rather than 'client', creating a mild mismatch between prose and schema. The dateRange guidance is helpful but largely restates schema intent.

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-target pair—'Mileage analytics'—and enumerates totals, breakdown dimensions, and deduction framing, making the tool's scope unmistakable. The mileage focus clearly distinguishes it from sibling reporting tools like get_income_summary and 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?

Concrete natural-language examples ('mileage this year', 'miles driven for Acme', 'mileage deduction estimate') give clear context for when this tool applies. It also mentions comparison phrasing support, but it does not explicitly state when to prefer an alternative analytics sibling or what conditions rule this tool out.

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 readOnly/openWorld/destructive annotations, the description discloses provenance ('figures come from the user's own recorded data'), reliability caveats ('advisory notes are estimates, not tax advice'), and explicit non-capabilities ('it does not close books or certify tax completeness'). It also explains what closeReadiness contains (recorded-book checks, Action Needed categories, authenticated app links), which the annotations alone would not 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 purpose and scope are front-loaded, then contents, examples, defaults, and caveats follow in a logical order. It is dense and slightly run-on in the trailing sentences about closeReadiness and unknown coverage, but nearly every sentence carries distinct 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?

With an output schema present, return-value detail is not required, and the description still covers defaults, data provenance, advisory-vs-authoritative distinctions, and the closeReadiness summary field. For a two-optional-param read-only review tool, 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 description coverage is 100%, so both parameters (period format, clientEmail scope) are already documented in the schema, and the description only restates the default-month behavior. The accountant-restriction note on clientEmail also appears in the schema, so the description adds essentially no parameter meaning beyond structured fields — 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 names a specific verb+resource ('Month-end summary of the user's books for one calendar month') and enumerates the exact contents (income recorded, money spent, net, top categories/merchants, alerts). Its scope — a single calendar month defaulting to the last completed month — clearly separates it from sibling tools like get_pnl, get_spending_summary, and get_income_summary, which are not month-scoped reviews.

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?

Concrete user-utterance examples ('how did last month go', 'close out my books for June', 'monthly review') give clear context for when to invoke it, and the clientEmail note scopes accountant use. It never names an alternative tool or states when NOT to use this one, 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?

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses key behaviors: the requirement for matching tags on income and expense rows, that margin renders as a multiplier in loss territory, and that the tool defaults to year-to-date when no date range is given. These are valuable behavioral details not captured in 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 well-organized: it leads with the core purpose, then prerequisites, tag prefixes, examples, and behavioral quirks. Every sentence adds value, and the structure is front-loaded with the most important information. It is slightly verbose but not padded.

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 three parameters (including a complex dateRange schema) and an output schema, the description covers the main use cases, preconditions, defaults, and output quirks. Nothing essential is missing for an agent to invoke it correctly.

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

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

The schema already provides descriptions for all parameters (100% coverage), but the description adds significant contextual meaning: it explains tag-prefix shortcuts (e.g., 'Prop –' for properties), provides example natural-language queries for the query parameter, and clarifies the default behavior of the dateRange parameter. This enriches the schema beyond its raw 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 the tool produces per-tag P&L (revenue, cost, profit, margin) grouped by tag, and explicitly lists the tag categories (client, property, event, realtor-deal). It includes concrete example queries that make the purpose unmistakable and distinguishes it from broader P&L tools like get_pnl.

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

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

The description provides explicit example queries that indicate when to use this tool (e.g., 'profit by client', 'per-tag P&L this year') and states the prerequisite that both income and expense rows must be tagged with matching labels. It does not name sibling tools to avoid, but the examples and focused scope imply the appropriate usage context.

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

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false), and the description adds genuinely non-obvious behavior: margin is rendered as a multiplier in loss territory ('expenses 5.4× revenue') rather than a negative percentage, and comparison output is conditional. It does not mention auth/permission nuances or data-freshness limits.

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?

Front-loads the core definition, then example phrasings, then the return shape — a sensible priority order with no filler sentences. The inline example list is somewhat long, but each example earns its place by teaching the NL query surface an agent must match.

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?

An output schema exists, so the brief returns summary ({ message, data: {...} }) is supplementary rather than required, and the description covers the data sources, comparison support, and the margin edge case. Missing only the when-not-to-use boundary versus per-tag and analytics 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 description coverage is 100% and the dateRange oneOf variants are fully self-documenting, so the baseline is 3. The description's restatement of example query strings and period-comparison semantics adds only marginal meaning beyond the schema and does not clarify e.g. precedence between 'query' and 'dateRange' or the clientEmail authorization rule.

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 ('Compute Profit & Loss ... by combining the Income tab with expense tabs') and defines scope (revenue minus expenses plus margin), which inherently separates it from single-axis siblings like get_income_summary and get_spending_summary. The natural-language example queries ('am I profitable this year', 'what's my margin') make the intent 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?

Gives strong contextual triggers via example phrasings and enumerates supported comparison modes (YoY, MoM, QoQ, same-month-prev-year). It does not, however, state when NOT to use it or name alternatives such as get_per_tag_pnl for per-tag breakdowns or get_deep_analytics, so routing against close siblings 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?

Annotations already cover read-only and non-destructive nature, and the description adds valuable context about what the log contains (tool calls, arguments, timestamps, success/failure). It also states the default limit and maximum, which are not in annotations. Since annotations cover safety, the description provides additional behavioral detail 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 three sentences with no fluff. The primary purpose is stated first, followed by a clarifying distinction and then usage context and parameters. Every sentence earns its place, and the length is proportional to 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?

The tool has an output schema, so return format is covered. The description covers purpose, use cases, data scope, and parameter defaults. It does not explicitly mention pagination or error cases, but for a read-only audit log with a limit parameter, those are not critical. It is complete enough 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?

Schema description coverage is 67% (actionId and sinceDays have descriptions, limit does not). The description compensates for limit by stating 'default 20, max 100', which is not in the schema. However, it does not add beyond the schema for actionId or sinceDays, so overall it meets baseline without enriching beyond what is already clear. A 3 is appropriate.

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

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

The description clearly states a specific verb ('Show') and resource (recent activity log) and explicitly distinguishes it from document processing history. It names the underlying content (tool calls, arguments, success/failure) and directly differentiates from the sibling 'trace_document' by clarifying it is not processing history. This is unambiguous.

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

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

The description gives concrete use cases: 'what did I do this week' and 'which tools has my assistant run', and states it provides transparency into AI-assisted actions. It also clarifies it is not for document processing history, though it does not explicitly name an alternative tool. It could be stronger by pointing to specific siblings, but the guidance is clear and actionable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context: it discloses what the call returns (all expenses, totals, compliance status) and a meaningful gating rule about consent for inspection. It doesn't mention rate limits or the accountant-specific client scoping beyond the schema, hence not a full 5.

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

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

Three sentences, front-loaded with the capability, then the usage condition, then the exclusion. Every sentence carries a distinct and necessary constraint with zero 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?

An output schema exists, so return values need not be spelled out, and annotations cover safety. Combined with 100% schema coverage, the description supplies the remaining needed pieces: scope, consent gating, and the preflight/follow-up prohibition.

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

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

Schema description coverage is 100%, so all three parameters are already documented, including the analysisRequested consent semantics and the clientEmail accountant restriction. The description reinforces the consent constraint but adds no syntax or format detail beyond the schema, so 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?

States a specific verb (Get) and resource (full details of a specific expense report) and enumerates the payload (all expenses, totals, compliance status). It is clearly distinguishable from siblings like list_reports (enumeration) and check_compliance (single check).

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 it ('only when the user explicitly asks to inspect an existing report's details') and when not to ('never call this as a preflight or follow-up to creating, sharing, or billing'), explaining that those tools already return the required result and links. This is explicit when/when-not guidance with the alternative mechanism named.

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.' It goes beyond the annotations by detailing the fields returned (spreadsheetUrl, reviewExpensesUrl, gmailScanUrl) and instructing which to display under which condition, plus noting the data mirrors the in-app status pill. 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 well-structured: it opens with the core purpose, then lists returned data, then gives usage triggers and follow-up actions, and closes with 'Read-only.' Every sentence adds value; it is compact without being terse, and the most critical info (purpose and when to call) 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 read-only status tool with no parameters and an output schema (which presumably documents the return structure), the description covers the essential agent needs: what it returns, when to call, and how to act on the results. It could mention edge cases (e.g., no active scan) but these are likely implied by the output schema, so it is sufficiently complete.

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

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

The tool has zero parameters, so the description carries no parameter burden. The baseline for 0 parameters is 4, and the description adds no unnecessary parameter info. Schema coverage is trivially 100% (empty schema), so this score 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: 'Check the authoritative status of the user's Gmail receipt scans.' It enumerates the exact returned data (scan lock, live phase, item progress, years, exclusions, outcomes) and explicitly ties it to a status-pill context, which clearly differentiates it from siblings like scan_gmail (which initiates scans) and get_last_receipt_result (which returns a single 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 gives an explicit trigger: 'Call when the user asks whether a scan is running, finished, stuck, or what it is doing.' It also provides follow-up actions (show spreadsheetUrl/reviewExpensesUrl when complete, gmailScanUrl when setup needed). However, it does not explicitly state when NOT to use it or name alternative tools, so it lacks exclusions.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds a compact return shape ('Returns: { message, data: { total, breakdown?, comparison?, sampleMeta? } }'), which gives some behavioral context beyond annotations. It does not describe auth requirements, rate limits, or edge cases, but the annotations cover the important safety dimension.

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

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

The description is three sentences long, front-loaded with the core capability, then covering options, read-only status, and return shape. There is no filler or redundant elaboration; every clause contributes to an agent's understanding.

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

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

After accounting for the existing output schema and annotations, the description fills the main gap by documenting the enum parameters and the overall purpose. It lacks context about natural-language query usage (e.g., that query can be a free-form question) and does not mention the clientEmail restriction, but these are already in the schema. The main omitted guidance about which sibling to use instead is captured in the usage_guidelines dimension.

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%, and the two undocumented parameters (metric and groupBy) are clear from the description: it lists 'category, merchant, month, tag, source, or payment method' and 'total, count, or average metrics', mapping directly to the enum values. This adds real semantics beyond the schema. Other params (query, dateRange, categories, clientEmail) are adequately 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 a specific verb and resource: 'Summarize the user's recorded expenses with totals and breakdowns...' It also enumerates grouping dimensions and metrics, making the intent concrete. It does not explicitly name sibling alternatives like get_income_summary or get_pnl, but the 'expenses' scope and read-only nature implicitly distinguish it from those.

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?

No explicit when-to-use or when-not-to-use guidance is given. The description mentions capabilities ('Supports date ranges, period comparisons...') but does not clarify when to choose this rather than sibling tools like get_income_summary, get_pnl, or get_deep_analytics. With a large sibling list, the absence of route-to-alternative guidance is a significant gap.

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, destructiveHint=false, openWorldHint=false, and the description reinforces this with 'Read-only; this tool does not create or modify spreadsheet rows.' Beyond annotations it adds genuinely useful behavior: show only one or two relevant links rather than the full catalog, never invent a Drive folder ID, explain owner-access requirements instead of presenting a broken link, and require explicit confirmation before row changes.

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?

This is a single ~350-word run-on paragraph with no headings or bullets, and much of the routing prose duplicates its own output — the description states each returned link already carries 'a description of when to use it.' The purpose is front-loaded, but the volume is disproportionate and unstructured even for a dispatcher tool.

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

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

Coverage of scenarios is remarkably complete for a zero-param dispatcher, and the presence of an output schema means return contents need not be explained. The only shortfall is that the heavy per-scenario routing rules logically belong in the returned link descriptions, making the tool description an oversized complement rather than a 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. Referenced fields like clientBillingHandoffs and the label/description pairs are part of the output, not inputs.

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 opening sentence states a specific verb and resource: 'Return the user's master ExpenseBot Google Sheet plus authenticated ExpenseBot workspace links, each with a label and a description of when to use it.' That immediately distinguishes it from siblings like get_spending_summary or search_expenses — it is a link/handoff catalog, not a data or write 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 an exhaustive when-to-use map: after receipt submission prefer Review expenses + Sheet, after income write prefer Review income, Gmail requests use Scan Gmail, bank/card use Reconcile, categories use Category management, etc. It also names explicit alternatives (search_expenses and group_expenses for client-scoped work, direct write tools for clean cash/mileage entries) and the conditions that select them.

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

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

The structured annotations already say readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description meaningfully adds that the tool wraps a 'Subscription Auditor engine' and enumerates the output categories, which helps the agent predict behavior. It does not contradict any annotation.

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: first sentence states the purpose, then a short example list, then a brief return signature. Every part earns its place; no verbose filler or circular wording.

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

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

Combined with a rich input schema and an existing output schema, the description supplies the tool's engine, domain keywords, natural-language examples, and return shape. There is no material gap that would prevent an agent from choosing and calling 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%, so baseline is 3. The description's natural-language examples give useful phrasing for the `query` parameter, but it does not clarify the relationship between `focus` and `query` (e.g., whether query overrides focus or they combine), which is a real semantic gap 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 names a specific resource ('subscriptions') and a clear verb ('audit/find'), enumerates the exact categories it returns (recurring, duplicates, price increases, trial conversions), and gives natural-language examples. It does not explicitly contrast itself with sibling tools like get_spending_summary or get_deep_analytics, so it stops short of a 5.

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

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

The examples ('recurring subscriptions,' 'duplicate subscriptions,' 'subscriptions over $20/month') establish a clear trigger context for an agent deciding to invoke this tool. It does not name alternatives or exclusion conditions, but the type of question this tool handles is unmistakable.

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 goes well beyond that: it reinforces the read-only nature with concrete examples of what is never done, specifies the exact return format (strict YYYY-MM-DD dates, evidence, locations, Receipt IDs, expected tags), and discloses a non-obvious rule: 'Never send confirm:true from this read result alone.' It also exposes the accountant-mode limitation. These details add significant behavioral context that annotations alone do not provide, with no contradiction.

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

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

The description is dense but every sentence earns its place. It leads with the primary purpose, then layers read-only constraints, return format, the critical nextAction workflow, and a mode-specific caveat. There is no filler or redundancy; the structure is logical and the most safety-critical guidance ('Never send confirm:true') is emphasized. The length is justified by the complexity of the tool's 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?

Given the tool's complexity—read-only retrieval with a conditional write handoff and accountant-specific behavior—the description covers all necessary aspects: what it returns, what the agent should do with nextAction, what not to do (infer client from geography, send confirm:true), and when to hand off. The presence of an output schema reduces the need to explain return values, and the description fills the remaining gaps about usage policy and edge cases.

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

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

Schema description coverage is 100% for both parameters (limit and clientEmail), each with clear descriptions and constraints. The tool description does not add any meaning about the parameters themselves—it only contextualizes how to use the returned nextAction, which is about output handling, not parameter semantics. Per the rubric, with high schema coverage, the baseline is 3, and the description does not elevate it further.

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 statement of what the tool does: it shows ExpenseBot's high-confidence Trip Intelligence proposals from Review Expenses. It clearly distinguishes itself from write operations by explicitly listing what it never does (groups, tags, creates reports, writes to spreadsheet) and provides a concrete handoff path (Review Expenses or owner's assistant) that separates it from sibling tools. 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?

The description gives explicit when-to-use and how-to-proceed instructions: it states the tool is read-only, and when nextAction is present, exactly which parameters to use (group_expenses with confirm:false), how to present results (show canonical preview), and when to ask for confirmation before any write. It also details the accountant clientEmail mode and directs the agent to hand off when no executable nextAction is returned. This is thorough, actionable guidance that removes ambiguity.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and readOnlyHint=false, but the description adds substantial behavioral context beyond them: automatic grounded preview, premature confirm conversion, operationId idempotency reuse, personal-marker protection, conflict/exclusion behavior, duplicate-report avoidance, and the meaning of returned Bill Client links.

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 and dense, but it front-loads the purpose and examples before moving into workflow constraints. Almost every sentence serves to prevent a specific failure mode in a complex destructive bulk operation, though the single-paragraph format and volume keep it from being maximally concise.

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, 12 parameters, nested objects, destructive annotation, and the presence of an output schema, the description is complete enough to guide correct invocation. It covers preview/confirmation, report creation, exclusions, idempotency, conflicts, and post-confirmation reporting behavior without needing to explain return values.

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

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

Schema description coverage is 100%, so the schema already carries the basic parameter definitions. The description adds meaningful workflow semantics for confirm, createReport, excludePersonal, approveNewGroup, and selection stability, though it does not add equally clear guidance for undo, status, reportTitle, excludedTags, or excludedCategories.

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: grouping an exact set of recorded expenses for a client, project, trip, job, or other user-named purpose. It is clearly differentiated from siblings by naming search_expenses as the source of exact IDs and explicitly steering report creation into this call rather than a separate create_report query.

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

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

Usage is highly prescriptive: first call with confirm omitted/false to preview, then only after explicit approval repeat with confirm:true. It names alternatives and exclusions, including when to use createReport:true and excludePersonal:true, and explicitly says not to call check_compliance, get_report_details, or tax tools unless separately asked.

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, destructiveHint=false, and openWorldHint=true, so safety is covered structurally. The description adds useful context beyond that: the data is live from the user's spreadsheet, which tells the agent results are fresh rather than cached. It doesn't discuss failure modes (e.g., no categories configured), so it stops short of a 5.

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

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

Three sentences, none wasted, and the ordering instruction is front-loaded after the purpose. The rationale for the call order is compressed into a single clause rather than spelled out.

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?

An output schema exists, so return values need no explanation here, and with zero parameters and full annotation coverage the description has nothing left to carry. It supplies the one thing structured fields can't: the required call ordering relative to sibling tools.

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

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

Zero parameters, so there is nothing to document and the baseline is 4. The description correctly adds no parameter noise.

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+resource ('List the user's configured expense categories and billing accounts') and scopes it precisely enough to separate it from list_income_categories and list_tags. An agent can identify the tool's job without opening 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?

Explicitly prescribes when to call it ('BEFORE calling tools that need a category') and names the exact downstream tools (add_cash_expense, add_mileage_entry, create_report). It also states the reason — passing real category names instead of guesses — which closes the loop on why this ordering matters.

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 readOnly/destructive/openWorld annotations, it discloses meaningful behavioral traits: accountant-only access, that no client identities, amounts, or individual items are returned, that unavailable sources stay 'unknown', and two pagination caveats (page uses the current roster; pages must not be summed into a verified total). These are exactly the constraints an agent needs to avoid misreporting results.

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

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

Four sentences, front-loaded with the scope and return shape before the usage trigger and caveats. Every sentence carries information (audience, output, trigger, data limits, pagination warning), though the density is high enough that it reads more like a spec block than a tight synopsis.

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

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

With an output schema present, the description needn't explain return fields, and it correctly focuses on limits, audience, and pagination behavior instead. It is nearly complete; only a pointer on how the page-link/pagination should be consumed is left to the schema.

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

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

All three parameters are fully documented in the schema (100% coverage), including the page/limit/period semantics and the nextPage chaining hint, so the schema does the heavy lifting. The description only reinforces the page-level nature of results, adding no syntax or format details beyond what is already structured. 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 states a specific verb and resource ('month-end overview of accepted client workspaces' with 'page-level readiness and affected-client category counts') and immediately scopes it as accountant-only. It is clearly distinguishable from sibling tools like list_client_invoices or get_client_advance_balances, which deal in per-client detail rather than aggregate readiness.

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

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

It gives an explicit trigger ('Use for "how many clients need attention before month end"') and redirects detail resolution to another surface ('select a client in ExpenseBot to resolve items'). It never names a sibling tool directly nor states when not to use it, but the operational context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by listing the returned fields (invoice numbers, status, totals by currency, delivery state, private document links) and the default status behavior, which goes beyond the annotations without contradicting them.

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

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

The description is well-structured: it opens with the core purpose, then gives examples, then details status options and return fields. Each section earns its place, though the examples and enumeration could be trimmed without loss. It is appropriately sized for a tool with four optional parameters.

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 (four optional parameters, an output schema, and a clear read-only role), the description covers the essential context: what it lists, how to filter, and what it returns. The limit parameter is documented in the schema, and the output schema handles return details. Nothing critical is 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 baseline is 3. The description does not add extra meaning for the parameters beyond what the schema already documents; it only reiterates the status enum values and default, which are already in the schema. No additional semantic value is provided.

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 clear verb ('list') and resource ('the user's issued client invoices'), with a plain-language explanation of accounts receivable and concrete example queries. It clearly distinguishes from sibling tools like get_client_invoice (singular) by framing itself as a listing operation.

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 example phrasings that map to typical use cases and enumerates the status filter options, providing clear context for when to use this tool. It does not explicitly name alternatives or say when not to use it, but the examples imply the intended scope, so this is strong but not explicit on 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 provide read-only and non-destructive hints. The description adds that the categories are fixed and not user-configured, which is a useful behavioral fact but largely reinforces the existing openWorldHint=false annotation. There is no contradiction.

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

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

Two sentences, first is front-loaded with the core purpose, second provides usage context and the rationale for the action. Every sentence earns its place with no waste.

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 list tool with an output schema present and annotations covering read-only/destructive behaviors, this description is complete. It tells the agent when to use it, what it is, and why it matters, so nothing essential is missing.

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

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

This tool has zero parameters and 100% schema description coverage. The description does not need to add parameter detail, so the high baseline of 4 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?

Clearly identifies the specific action (list) and resource (ExpenseBot's fixed income tax categories), distinguishing it from user-configured Expense Accounts. The mention of income tax and the unmodifiable nature makes the purpose unambiguous.

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

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

Explicitly instructs to call this tool before add_income and warns against guessing categories, indicating when to use it. It contrasts with Expense Accounts without naming the exact sibling tool, so it stops short of a fully explicit when-not/alternative tool list.

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, the description discloses that results embed accounting handoff URLs and warns against acting on them unless explicitly asked. The note that 'the app keeps organization, mapping, and final confirmation' clarifies the tool's limits, adding meaningful behavioral context.

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

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

The description is short and front-loaded with the core action, followed by filter options, return contents, and a safety caveat. There is minor ambiguity in 'each exact report' and the phrase 'the app keeps organization, mapping, and final confirmation,' but overall it is efficient.

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

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

For a simple read-only listing tool with an output schema, the description covers its purpose, filtering, pagination, relevant returned data, and an important usage caveat. It does not specify when to prefer sibling tools, but that is not essential for a straightforward list operation.

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

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

Schema coverage is 100%, with page, limit, filter, and clientEmail all described. The description adds only high-level context about pagination and status, and does not meaningfully extend the parameter explanations 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 opens with a specific verb and resource: 'List the user's expense reports with pagination.' It is unambiguous against siblings like add_expense or export_report because the focus is purely read-only listing. The mention of status filtering and returned URLs further distinguishes it from detail or send operations.

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 a clear operational caveat—use the accounting URL only when the user explicitly asks to send/export—but it does not explicitly route an agent away from or toward sibling tools such as get_report_details or export_report. The filtering and pagination context is useful, yet alternative selection guidance is missing.

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