ExpenseBot

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

Annotations only declare readOnly=false, destructive=false, openWorld=true; the description adds substantial context beyond them: the write goes 'directly to the user's expense spreadsheet after confirmation', the tool reuses or creates the canonical client group, applies the 'Cash advance received' account, and stores the amount as a negative expense. That is exactly the side-effect and state-mutation disclosure an agent needs for a write 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?

Front-loaded with the core action and the two modes before the exclusions. It is fairly long (six-plus sentences) but nearly every clause carries routing or behavioral information; only the repeated advance guidance in the closing sentence is mildly redundant.

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

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

For a 12-parameter mutation tool with an output schema (so return values need not be explained) and non-destructive annotations, the description supplies prerequisites, mode branching, side effects, and fallbacks. An agent can call it correctly without opening any sibling.

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 only implies: category is required for ordinary expenses but not for a client advance, merchant is derived from clientName in the advance path, and total is stored negated. It doesn't cover tax/tip/subtotal handling, but those are adequately self-documented.

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 ('Add an expense without a receipt'), then immediately distinguishes two distinct modes: ordinary expense vs. client advance. It also names the exact sibling (list_categories) needed for the ordinary path, making it clearly separable from add_income and 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?

Explicitly routes the agent: ordinary expense → list_categories first; client advance → isClientAdvance=true plus clientName. It also lists hard exclusions ('never for vendor refunds, reimbursements, earned fees, retainers or generic deposits') and names the fallback path (Manual expense link from get_spreadsheet_url) for multi-entry, refunds, tax/tip breakdowns, and per diem.

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 declare non-read-only but non-destructive; the description supplies the missing operational detail: nothing is written in step 1, the attachment is consent to parse only, previews expire after 15 minutes, and an expired or unknown previewId never writes. These are non-obvious safety behaviors that go well beyond the annotation flags.

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 resource and format list, then cleanly chunked into STEP 1 and STEP 2 with a closing fallback route. It is long for a single tool description, but nearly every clause carries actionable information; only the format enumeration in the first sentence borders on excess.

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, the description covers the workflow, the write-safety boundary, expiry, duplicate handling, and post-confirm next steps (spreadsheetUrl, reviewIncomeUrl). With annotations and an output schema present, nothing an agent needs in order 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 coverage is 100%, so the baseline is 3, but the description adds sequencing semantics the schema only implies: which parameters belong to step 2, that selectedIndexes/keepBothIndexes/rowEdits/bulkNote compose into 'only user-approved changes,' and that previewId ties step 2 back to step 1. Remaining duplication of per-field descriptions keeps it from a 5.

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/PDF), enumerates supported formats and size limit, and implicitly separates itself from add_income and add_income_from_csv by naming the file-based, two-step parse-then-confirm model. An agent can identify the tool and its scope 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?

Gives an explicit two-step protocol (call without confirm, then call with confirm:true and previewId), states which step accepts which arguments, and routes visually complex reviews to the Add Income app link from get_spreadsheet_url. It also specifies the duplicate policy (skipped unless keepBothIndexes) so the agent knows the default behavior.

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; the description goes well beyond that by disclosing the mandatory preview gate, that a premature confirm:true is downgraded to preview, attendeeMode add-vs-replace semantics, that Notes structured segments are preserved while Formula Notes and over-limit changes are skipped, and that the confirmed result reports applied/conflicted/failed counts with Undo support. These are exactly the operational facts an agent needs before a destructive write.

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 and examples, followed by the preview/confirm protocol and then constraints, so scanning order matches decision order. It is long and dense for a tool description, but nearly every sentence carries a rule an agent would otherwise get wrong; only the Notes/Formula detail is somewhat compressed.

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, 6-parameter tool with an output schema, the description supplies the full operating protocol (search → select → preview → approve → confirm → undo) plus the guardrails that annotations alone leave ambiguous. Return-value detail is correctly left to the output schema, with only the applied/conflicted/failed counts summarized.

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 3 is the floor; the description still adds workflow meaning the schema cannot express, namely that operationId must be generated once and reused unchanged between preview and confirm, and that the selection list must not be broadened after preview. It also explains the conflict detection purpose of expected values indirectly through 'before-to-after changes'.

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 concrete verb (correct) plus the exact resources it can touch (category, business purpose, attendees) on a bounded set of recorded expenses, and makes the scope explicit with 'exact bounded set' and an example set that maps directly to the three change types. It is clearly distinguishable from search_expenses (upstream selector) and update_expense (singular edit).

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 the sequence: call search_expenses first, then pass full expenseId values, preview with confirm omitted/false, ask once, then confirm:true with the same operationId. It also states what the tool will not do (no duplicate omission, no amount/date edits, no inferred business context, no broad Calendar matching) and routes unsupported or over-100-row work to an external URL, giving an unambiguous alternative path.

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 readOnly=false and destructiveHint=true; the description adds real behavioral context beyond them: no duplicate report is created when no unreported matches remain, group-scoped reports only pull expenses not already on another ordinary report, and accountingHandoffUrls do not mean an export occurred. It stops short of clarifying the destructive/irreversible aspect implied by destructiveHint (what a created report locks or changes), so not a perfect score.

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

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

Purpose and key routing advice are front-loaded, and nearly every sentence carries non-obvious operational detail (duplicate suppression, group scoping, handoff URLs, tool-call exclusions). It is dense and long, but the density is mostly justified rather than padding.

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

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

An output schema exists, and the description still names the key returns (report summary, report link, Bill Client link, applied filters, Wizard fallback). Combined with the duplicate-suppression rule, sharing behavior, and the terminal handoff URL caveat, an agent has everything needed 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 coverage is 100%, so baseline is 3; the description still adds meaning by explaining that tags are ExpenseBot's grouping layer for clients/projects/trips and that excludePersonal covers both the Personal tag and the Personal expense category to match Report Wizard behavior. It adds little on shareWith/recipientRole beyond what the schema already documents.

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

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

Opens with a specific verb+resource (create an expense report) and immediately scopes the inputs it accepts (date, client, project, trip, category, merchant). It is clearly distinguishable from siblings such as list_reports, get_report_details, and export_report, which it implicitly rules out via the 'do not call check_compliance, get_report_details...' instruction.

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 routing: call list_tags when the intended group is unclear, use excludePersonal=true for the 'all expenses except personal' case, use recipientRole only when ongoing accounting access is wanted. It also states negative conditions – do not pre- or post-call compliance, report-detail, or tax tools unless the user asks.

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: discloses a staged preview/confirm transaction, that fresh duplicate checks re-run on confirm, that exact canonical duplicates are a no-op, that archived tags are not reactivated, and that similar names surface as choices. These are non-obvious semantics an agent would otherwise get wrong on a write 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?

Six tight sentences, front-loaded with the core action then the confirmation protocol, then the edge cases. No restatement of the tool name and no filler; each sentence carries a distinct constraint.

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 two-step confirm flow is the main complexity risk for this tool and it is fully spelled out, including the fresh-duplicate-check behavior on the second call. An output schema exists, so omitting return-value detail is correct, and nothing needed 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, but the description adds meaning beyond the field docs: it explains the operationId round-trip between calls, that a first confirm:true call still only previews, and the risk condition under which allowSimilar is legitimate. It does not mention the status parameter's polling use, which the schema covers instead.

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 the specific verb and resource ('Create a standalone group/tag') and immediately scopes it against the obvious sibling: it does not select or change expenses, unlike group_expenses. An agent can distinguish this from group_expenses and list_tags 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?

Gives explicit when-to-use choreography (preview first, confirm only after user approval), an exclusion (don't set allowSimilar unless the user explicitly wants a distinct group), and routes inspection to list_tags. The confirm-without-preview edge case is called out rather than 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 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?

While annotations confirm destructive intent, the description adds critical operational behavior: it mandates a two-stage workflow (preview without changing anything, followed by explicit approval to execute), guarantees idempotency via 'operationId', and discloses outcome reporting (applied/conflicted/failed counts and Undo support).

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 definition is extremely verbose, detailing a complex multi-stage operational workflow (preview, approval, execution, reporting). While every sentence serves a functional purpose, the overall length sacrifices conciseness for maximum behavioral detail.

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

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

Given the complexity (multi-stage state change, idempotency, and failure modes), the description is highly complete. It successfully marries the low-level parameters provided by the schema with the high-level business logic and behavioral rules required for safe execution.

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

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

With 100% schema description coverage, the baseline is 3. The description adds valuable constraints and context, such as specifying that selections must use 'exact full expenseId/Column-Q receipt identity' and that the `confirm:true` status is only valid *after* explicit user approval, adding necessary intent-based guidance beyond the structure.

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

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

The description clearly identifies the function ('correct compliance issues'), the target resource ('recorded expenses'), and the strict prerequisite workflow (must use issues found by 'check_compliance'). This makes it immediately distinct from 'check_compliance' and 'correct_expenses' 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?

It provides explicit preconditions ('Use only after the user explicitly asks to fix issues found by check_compliance'). Furthermore, it mandates strict usage constraints (bounded set of expenses, exact IDs from search_expenses) and outlines a complex, staged workflow.

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, but the description goes well beyond them: it defines the sign convention (negative = money remains to refund, positive = client owes the user) and explicitly states it never records a refund, creates an invoice, or recomputes the ledger in prose. That is exactly the kind of domain behavior an agent cannot infer from annotations or schema.

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

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

Front-loaded with the verb+resource, then usage examples, then the crucial sign-convention and read-only caveats — logical ordering with little waste. The middle list of three example questions is slightly verbose but serves as genuine usage scaffolding.

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 shapes; it covers the semantic interpretation of the returned balances (sign convention) and the handoff behavior (Refund leftover / Bill Client), which are the pieces a schema cannot convey. 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 both clientName and clientEmail are already documented in the schema. The description reinforces the 'omit to list all open balances' default but adds no syntax or format detail beyond what the schema provides, so the baseline of 3 applies.

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

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

States a specific verb ('Read') and resource ('per-client advance balances'), plus ties it to the visible Client advances section of the app so an agent knows exactly which data surface it touches. The example questions ('how much of Acme's advance remains?', 'which client floats are still open?') further pin the domain apart from siblings like get_credits_refunds.

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

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

The example questions give clear usage context, and the closing sentence explicitly excludes writing behavior. It does not explicitly compare against the nearest sibling (get_credits_refunds) or say when a different tool should be chosen, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces rather than contradicts that. It adds context annotations do not carry: links are 'private' Google Doc/PDF/DOCX and only present 'when available', and invoiceNumber lookups fail unless unique. No mention of failure behavior when the number is ambiguous, which is the one real gap.

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

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

Two sentences, front-loaded with purpose before constraints, and no filler. The return-field list is dense but each item maps to real output the agent may need, though it pushes the sentence toward a catalogue rather than a summary.

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 field enumeration is arguably redundant, but it is harmless and the identifier rules cover the only decision an agent must make before calling. The gap is guidance on recovering from a non-unique invoiceNumber or resolving the ID via list_client_invoices.

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 three parameters, including the accountants-only constraint on clientEmail. The description adds only the 'exactly one identifier required' and 'must be unique' semantics, and it never mentions clientEmail at all, so it is at the baseline for a fully-covered 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 ('Get') and a precisely scoped resource ('full financial and delivery summary for one issued client invoice'), and the singular scope cleanly separates it from the sibling list_client_invoices. The enumeration of what the summary contains leaves no ambiguity about the payload.

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 identifier rules: 'Provide invoiceId or invoiceNumber — one is required; invoiceNumber is accepted only when it is unique.' That tells the agent how to satisfy the call, but it never names list_client_invoices as the way to obtain an invoiceId, nor states when to prefer this over the list tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with concrete negative guarantees — no card scanning, no review-decision changes, no row insertion — which are more actionable than the hints alone. It also discloses result ordering and the default window (25, newest first), which annotations cannot convey.

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

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

Front-loads what the tool lists, then examples, then result behavior and safety guarantees — a sensible order. Slightly dense in one paragraph, but every clause (examples, ordering, read-only guarantees) carries 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 and full parameter documentation, the description need not explain return shapes; it still covers scope, ordering, and safety. It omits mention of the clientEmail accountant path, which the schema covers, so 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 description coverage is 100%, so limit, dateRange bounds, and clientEmail are already fully documented. The description only adds the 'newest first' ordering and restates the default of 25, adding modest value beyond the schema.

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

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

States a specific verb (list) and a precise resource (card refunds, cashback/rewards, statement credits already recorded), plus how they are recorded (negative expenses or matched to original charge). The quoted user-intent examples ('did my refund come through', 'was that return recorded') make the scope unmistakable against generic search tools like 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?

Provides concrete example queries that trigger it and tells the agent to narrow with dateRange. The closing clause implicitly routes scanning/mutating cases elsewhere ('never scans cards, changes review decisions, or adds rows'), though it does not name the alternative tools (scan_gmail, correct_expenses) explicitly.

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

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

Beyond the read-only, non-destructive annotations, the description discloses important behavior: it takes 10-30 seconds, runs as a background job that is polled automatically, and returns a truncation flag indicating whether the full dataset was visible. These details materially affect how an agent should invoke and interpret the tool.

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

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

The description is compact and front-loaded: purpose first, then usage examples, then latency/async behavior, then return-shape caveat. Every sentence provides useful information without repetition.

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

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

Given the annotations, full schema coverage, and existing output schema, the description is complete enough to call the tool correctly. It adds the important async latency and truncation semantics that an agent needs when interpreting results.

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 the query and dateRange parameters are already well documented in the schema. The description reinforces usage with examples like Q1 vs Q2, but it does not add parameter-level meaning beyond what the schema provides.

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

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

The description states a specific verb and resource ('Run deeper, multi-step analytics on the user's expenses') and distinguishes the tool from simpler summary or lookup siblings through the phrase 'deeper, multi-step'. The explanatory-question examples further clarify its distinct analytical role.

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

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

It gives clear when-to-use guidance with concrete examples such as 'why did my spending increase' and 'compare Q1 vs Q2'. It does not explicitly name alternatives like get_spending_summary or get_pnl, so the agent must infer that simpler summaries belong elsewhere.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description earns credit for the substantive additions: results are one parent payment with nested lines, split lines are never counted as separate expenses, and totals remain correct as a consequence. That aggregation semantics is exactly the kind of non-obvious behavior an agent needs, and it is not derivable from 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?

Four sentences, front-loaded with the core behavior and aggregation caveat before the example queries. The examples are functional rather than filler, though the read-only sentence partially duplicates the readOnlyHint annotation.

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

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

With an output schema present, return-value details are unnecessary; the description covers scope, aggregation semantics, and the read/write boundary. Combined with fully documented parameters, 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%, with limit, dateRange bounds, receiptId, clientEmail and the onlySplit flag all documented in-schema. The description adds no parameter-level detail beyond what the schema provides (it never mentions onlySplit=false for inspecting an unsplit receipt, nor the accountants-only constraint on clientEmail), 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 and resource (show how an expense was split) and enumerates the split dimensions (categories, clients, properties, business vs personal). The parent-payment-with-nested-allocation framing cleanly distinguishes it from flat listing tools like search_expenses or get_expense_by_id.

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

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

Provides three concrete example queries that map directly to invocation, plus an explicit boundary: reads happen here, edits happen in the Review workspace. It stops short of naming sibling tools (e.g., use search_expenses to locate the receipt first, then this to inspect its allocation), so routing is clear but not exhaustively specified.

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 and non-destructive annotations, the description discloses that it returns message/data with total plus optional breakdown, comparison and sampleMeta. It also states what the tool does not do: scanning, imports, mutations, tax returns and liability determination, which is useful behavioral context.

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

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

The description is front-loaded with the usage trigger and then packs purpose, parameters, return shape and exclusions into a short paragraph. Each clause carries information and there is little repetition.

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

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

With annotations and an output schema present, the description supplies enough context about when to call it, what it returns and what it explicitly does not do. An agent can invoke it correctly without additional documentation.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters, including the dateRange variants and groupBy enum. The description reinforces the groupBy dimensions and filters but adds no syntax or interaction detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: it reads income totals from the ExpenseBot Income tab. It clearly separates this from scanning, importing, mutating, tax-return and liability work, so an agent can distinguish it from siblings such as add_income or scan_gmail.

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

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

It gives an explicit trigger ('Use this when the user asks about income already recorded...') and exclusions ('No scanning, imports, mutations...'). It does not name alternative tools for adjacent tasks such as expense summaries or recording income, so it falls just short of full 5-level 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 readOnly/non-destructive/closed-world; the description goes far beyond by disclosing the pending-vs-terminal semantics via found:false/found:true, the full verdict taxonomy (added, duplicate, skipped, held_for_review, errored), what held_for_review means operationally, and the hard rule against blind resubmission. This is exactly the async/authority context annotations cannot carry.

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 and mostly well-organized, but the 'do not resubmit' warning is stated twice ('must not trigger a duplicate resubmission' and 'Unknown outcomes stay unknown; do not blindly resubmit'), and the spreadsheetUrl/reviewExpensesUrl presentation rules overlap with what the output schema already encodes. A few sentences do not earn their 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 an async polling tool with held/review states and an output schema, the description covers the lifecycle, polling budget, terminal-state interpretation, and downstream reporting obligations. Nothing an agent needs to call it or act on the result 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 meaning the schema lacks: it binds submissionId to the polling interval and time allowance returned by submit_receipt, and frames withinSeconds as a fallback path rather than a primary input. Marginal but real added value over the field 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 ('Check the authoritative final outcome of a receipt image/PDF batch submitted with submit_receipt') and explicitly names the sibling it is not for ('use get_scan_status for Gmail scans'). An agent can distinguish it from submit_receipt and get_scan_status 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?

Gives the exact trigger ('After submit_receipt returns submissionId, call this tool with that exact ID'), the polling cadence source and time budget, an explicit negative ('A pending result is normal and must not trigger a duplicate resubmission'), and the alternative for out-of-scope uploads. When, when-not, and alternatives are all 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful behavioral context the annotations lack: deduction framing with country-aware IRS/CRA rates and cents-per-mile computation.

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 purpose ('Mileage analytics — totals, breakdowns...') before listing dimensions, deduction framing, examples and return shape. Dense but each clause carries information; the parenthetical rate explanation is slightly heavy but earns its place.

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

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

With an output schema, full schema coverage, and safe annotations, the description covers what an agent needs to call it and interpret results. The gap is minor: it doesn't clarify how free-text filtering (e.g. by client) interacts with groupBy.

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 parameters are well documented and the baseline is 3. The description's examples loosely map to the query parameter, but it also says breakdown 'by client' while the groupBy enum offers 'tag' rather than 'client', a minor mismatch that doesn't clarify over the schema.

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

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

States a specific verb and resource ('Mileage analytics — totals, breakdowns') and enumerates the breakdown dimensions and deduction framing, so an agent knows exactly what it returns. It doesn't explicitly name competing siblings like get_spending_summary or get_income_summary to route away from them, keeping it just 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?

Provides concrete usage examples ('mileage this year', 'miles driven for Acme', 'business miles last quarter') and notes comparison phrasing support, giving clear context for when to reach for it. It never states when-not-to-use or the write alternative (add_mileage_entry), so no 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?

This is highly transparent. The description explicitly warns that advisory notes are 'estimates, not tax advice' and states that the tool 'does not close books or certify tax completeness.' This crucial context far exceeds what the readOnlyHint annotation provides.

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 because it attempts to cover definition, usage examples, and legal disclaimers in one block. While comprehensive, it sacrifices conciseness for exhaustive explanation.

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

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

Given the complexity of financial summaries, the description is remarkably complete. It covers scope, limitations, output intent (summary and alerts), and even provides specific example prompts, ensuring an agent can handle various user queries.

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

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

Schema coverage is 100%, meaning the schema itself is robust. The description merely reinforces the schema's descriptions and the implied default behavior of the 'period' parameter, thus meeting the baseline score.

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

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

The description clearly states the tool provides a 'Month-end summary' encompassing specific financial metrics like income, spending, net, categories, and alerts. This comprehensive scope distinguishes it from simpler sibling tools like get_spending_summary.

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

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

The description provides numerous clear examples of user intent ('how did last month go', 'close out my books for June'), which serves as strong guidance for when to use the tool. It also clarifies the default behavior, using the last completed month.

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 safety and closed-world scope, but the description adds real behavior: the tool silently returns nothing unless both sides of a tag are posted, YTD is the default window, and 'margin renders as multiplier in loss territory' is a genuine output-format quirk. That is meaningful context beyond the annotation set.

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

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

The lead sentence front-loads what is computed and how it is grouped, and the constraint sentences follow in priority order. The five example phrases and four prefix shortcuts are somewhat list-heavy for one description, but they are the natural language this tool parses, so they earn their place.

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

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

With an output schema present, the description need not explain return values, and it does cover the data precondition, the default date window, and the loss-margin rendering quirk. What remains unstated is what an agent should do when the tag-matching precondition fails (empty bucket vs. error), which is the one operational gap.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds two things the schema does not: the year-to-date default when dateRange is omitted, and the semantic framing of tagPrefix as a bucketing limiter tied to the same prefix shortcuts it lists. That is additive rather than redundant.

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 clause names the specific output (revenue, cost, profit, margin) and the grouping dimension (tag), which distinguishes it from the untagged sibling get_pnl. The tag-type parenthetical (per-client, per-property, per-event, per-realtor-deal) sharpens the resource further, though it never names get_pnl or get_income_summary explicitly as the 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?

It gives concrete query phrasings ('profit by client', 'per-client P&L this year vs last') and states the precondition that both income and expense rows must carry matching tags, plus the default of year-to-date. It stops short of saying when to prefer this over get_pnl or get_income_summary, so the routing decision is only implied.

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=true and destructive=false, so safety is covered. The description adds genuine behavioral detail beyond that: period-comparison modes supported (YoY/MoM/QoQ/same-month-prev-year) and the non-obvious loss-margin rendering as a multiplier rather than a negative percentage, which is exactly the kind of surprise an agent should be warned about.

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, trigger examples, comparison modes, and return shape appear in that order with no filler; the margin-multiplier note is a single justified sentence preventing misread output. It is dense but every clause carries 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 read-only reporting tool with full schema coverage and an output schema, the description supplies what's needed: what it combines, what periods/comparisons are legal, and what the payload contains. Minor gap: no guidance on default period when no dateRange is supplied (0 required params).

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 earns above baseline by explaining that comparison types are driven from the natural-language query and by mapping example phrasings to dateRange styles. It does not add much on clientEmail, but the schema already documents it as accountant-only.

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 enumerates the metrics produced (net income, margin). The examples cement scope so an agent can distinguish it from income-only siblings like get_income_summary or get_per_tag_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?

Provides concrete trigger phrasings ('am I profitable this year', 'P&L for Q1', 'what's my margin', YoY comparison), which is clear usage context. It stops short of naming alternatives or stating when NOT to use it (e.g., use get_per_tag_pnl for per-tag breakdowns, get_income_summary for revenue-only).

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?

Goes well beyond the readOnly/openWorld annotations: it discloses that the default path reads only the stored report, that the freshness path hits canonical Google Sheets sources under a 5-second bound, and that an incomplete tax-year replay yields 'unknown' rather than 'current'. That degraded-result semantics is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Front-loaded with the resource and its payload, then the gating rules, then the exception path — a sound ordering with no filler. The freshness sentence restates some of what the schema already says about analysisRequested, which is the only 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?

Complete for a four-parameter read tool with an output schema: return shape needn't be described, and the description instead spends its budget on the non-obvious parts — consent requirements, the freshness escalation, and the unknown-vs-current failure mode. Nothing needed 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, but the description adds genuine meaning: it ties checkFreshness to a bounded source check, explains the unknown-status outcome, and reinforces that analysisRequested must reflect explicit user intent. clientEmail (accountants-only) is not mentioned in the description, leaving one parameter to the schema alone.

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

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

States a specific verb and resource ('Get full details of a specific expense report') plus the payload it returns: all expenses, totals, and compliance status. It also carves itself out from the write-side siblings (create, share, bill) by declaring it is never a preflight or follow-up to those, so an agent can place 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?

Gives an explicit positive condition ('only when the user explicitly asks to inspect an existing report's details') and an explicit negative one ('Never call this as a preflight or follow-up to creating, sharing, or billing'). The checkFreshness escalation has its own trigger condition, so both the default and the elevated path are routable.

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, openWorldHint=false, and destructiveHint=false. The description adds useful behavioral detail beyond that, including live phase/progress, queued/attention-needed periods, exclusions, recent outcomes, and which URL to surface after completion versus setup/reconnection.

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

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

The description is front-loaded with purpose and then usage triggers. It is somewhat dense and lists many return fields even though an output schema exists, but the routing guidance is valuable and most sentences earn their place.

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

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

With zero parameters, an output schema present, and annotations covering safety, the description is complete enough for correct invocation. It explains what kind of status is returned and how to route the user to the appropriate URL afterward.

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

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

There are zero parameters, so no parameter semantics are needed. The baseline for a parameterless tool is 4.

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 ('Check authoritative Gmail receipt scan status') and clearly separates this status tool from scan-triggering or receipt-processing siblings. It also names the domain object ('Gmail receipt scan') precisely.

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

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

It gives explicit usage triggers: asked whether a scan is running, finished, stuck, or what it is doing. It does not explicitly name alternatives such as scan_gmail or get_last_receipt_result, but the intended 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, destructiveHint=false and openWorldHint=false, so the description's 'Read-only.' adds nothing. The 'Returns:' line duplicates the existing output schema. The only genuine behavioral signal is the mention of period comparisons, which is modest added context over structured fields.

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

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

Purpose and scope are front-loaded in the first sentence, capabilities follow, and the read-only note is a four-word line. The trailing 'Returns:' block partly repeats the output schema and could be dropped, but overall there is little 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?

With annotations and an output schema present, the safety and return-shape burden is covered. What is missing is guidance for a tool with zero required parameters: no statement of default scope (all-time? last month?), and no mention of the optional 'clientEmail' scoping for accountants, which is a meaningful behavioral difference.

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%, so the schema carries most of the weight and baseline 3 applies. The description echoes the groupBy and metric enum values and the date-range concept, but says nothing about 'categories' or 'clientEmail' (accountant-only scoping), nor about behavior when no date range is supplied.

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 ('summarize the user's recorded expenses') and enumerates the exact grouping dimensions and metrics, so an agent can tell it apart from get_income_summary and search_expenses. It does not explicitly differentiate itself from analytical siblings like get_pnl or get_deep_analytics, which leaves some overlap to inference.

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

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

Usage is implied by the capability list ('supports date ranges, period comparisons, and total, count, or average metrics'), so an agent can infer that this is the tool for spending roll-ups. However, there are no explicit when-to-use/when-not rules and no named alternative such as get_pnl or get_deep_analytics for profit or deeper analysis.

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 by structured data; 'Read-only; modifies no spreadsheet rows' largely restates it. What the description does add beyond annotations is operational: show only one or two relevant links rather than the catalog, never invent or request a folder ID, surface clientBillingHandoffs, and explain an owner-access-required message instead of presenting a broken link.

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 opening sentence front-loads the purpose correctly, but the body sprawls into a several-hundred-word catalog of sibling routing rules, which sits awkwardly against its own instruction to show only one or two links rather than a catalog. Much of the content is relevant, yet it is dense, semicolon-chained, and hard to scan for the single link an agent needs.

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 annotations carry the safety profile, so the remaining need is knowing which links apply in which state. The description covers that thoroughly, including fallback behavior for owner-access and the clientBillingHandoffs path, leaving little an agent would need to guess.

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 applies. The schema is empty and consistent with the description's no-argument link lookup.

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

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

The first sentence states a specific verb and resource: it returns the master ExpenseBot Google Sheet plus labeled workspace links, each with a when-to-use description. That is concrete enough to distinguish it from data-mutation siblings, though the core function is quickly buried under a long downstream routing catalog.

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 enumerates explicit triggers (open/view/edit spreadsheet, review expenses, scan Gmail, reconcile, manage bank/card, open Automation Hub, create reports, trace a receipt) and then maps each scenario to a specific sibling or link. It also gives explicit exclusions: use the direct write tool for a complete unambiguous cash expense, use search_expenses plus group_expenses when the user names a client and exact scope.

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

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

Goes well beyond the readOnlyHint/destructiveHint annotations by disclosing that extraction isn't saved, that read and save jobs may overlap so counts aren't statement totals, that absence of a job is not proof of no import, and that the tool never uploads, parses, saves, retries or recovers. These are precisely the side-effect and data-validity caveats an agent needs before acting on the result.

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 tight sentences, front-loaded with the core question and answer shape, followed by the caveats in descending order of importance. No filler and no repetition of the name or title.

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 the description covers the scoping and validity caveats thoroughly. The one gap is scope selection: with no job identifier parameter, it is not stated which five jobs are examined (presumably the caller's most recent), leaving the agent to infer the lookup window.

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

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

The single parameter (clientEmail, accountants-only) is fully documented in the schema at 100% coverage, so the baseline is 3. The description adds nothing about the parameter — in particular it doesn't clarify what happens when clientEmail is omitted, which matters since it is not 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?

Opens with the exact user question it answers ('Did my statement finish importing?') and states the resource (import jobs) plus the return payload (status and authenticated review link). It is clearly distinct from neighbors like get_scan_status, get_last_receipt_result and trace_document by virtue of being about statement import jobs, though it never names a sibling explicitly.

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 a clear invocation context (checking whether an import finished) and a hard bound of 'at most five jobs'. It also supplies a key interpretation rule — 'No job found doesn't prove no import; older non-job imports are excluded' — which tells the agent when the answer is inconclusive. It stops short of naming which alternative tool to use for older/non-job imports.

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 closed-world scope, so the safety profile is covered. The description adds that results are heuristic ('suspects') and that analysis is scoped to the user's expenses, but it does not note data prerequisites (e.g. need for imported expenses) or that sampleMeta indicates partial samples. Adequate but thin beyond structured fields.

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

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

One sentence of purpose plus two compact labeled fragments (examples, returns), all front-loaded with zero filler. The structure lets an agent extract routing guidance and return shape at a glance.

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 and all three parameters documented, the description needs only to convey intent and detection categories, which it does. The only residual gap is data prerequisites/empty-result behavior, which is minor for a read-only audit tool.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by mapping natural-language examples to the `query` parameter and listing categories that mirror the `focus` enum (recurring, duplicates, price increases, trial conversions). It does not discuss how `focus` interacts with `query` or `dateRange`, leaving minor ambiguity.

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

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

States a specific verb+resource ('Subscription audit') and enumerates exactly what it detects: recurring charges, duplicates, price increases, trial conversions. This clearly separates it from generic siblings like get_spending_summary or get_deep_analytics without the agent needing to open 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?

The sample phrasings ('recurring subscriptions', 'price increases', 'trial conversions', 'over $20/month') make it clear what kinds of user requests should route here, giving strong positive guidance. It stops short of explicit exclusions, e.g. that non-subscription spend analysis belongs to get_spending_summary.

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

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

Beyond the read-only annotations, the description discloses important behavioral constraints: locations are not travel or client proof, clientEmail mode is read-only, refresh never changes tags, candidates are not saved, and existing assignments/Personal/read-only rows must be preserved. These cautions materially reduce misuse risk.

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

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

The description is dense and runs many workflow, mode, caveat, and downstream-tool instructions together in one block. Most content is relevant, but the lack of separation and the packed semicolon clauses make it harder to scan than a well-structured description.

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 10-parameter tool with an output schema, the description covers the key modes, defaults, paging behavior, downstream grouping workflow, and important safety caveats. It is broadly complete, though the dense presentation leaves some operational details harder to extract than necessary.

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 defines all parameters. The description still adds useful semantics for mode:area, includeCandidates, destination disambiguation, offset paging, includePossibleAdditions, and the read-only clientEmail mode, though it does not add much for limit, refresh, or dateRange beyond the schema.

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

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

The description clearly identifies a retrieval/review tool for trip suggestions, including default high-confidence behavior and an area mode. It is more specific than the name alone, but the phrase 'engine behind Review Expenses Find' is awkward and the description does not sharply distinguish this from sibling search/list tools.

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

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

It gives substantial conditional guidance: use includeCandidates:true for uncertain candidates, use destination when the user names a trip, use mode:area to list expenses in a country or city, and keep possible additions out unless explicitly included. It also names group_expenses as the downstream tool, but it does not directly state when to prefer this over sibling expense-search 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 mark it destructive and open-world; the description goes well beyond them by disclosing the mandatory preview, the premature-confirm downgrade, operationId idempotency reuse, conflict/exclusion handling, preservation of existing assignments, and that a Bill Client URL is not an invoice. That is unusually rich mutation 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?

Purpose and the preview/confirm rule are front-loaded and there are no filler sentences, but the block runs long and packs many rules into dense prose. Almost every sentence earns its place; the size is justified by the tool's complexity but hurts 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?

For a 13-parameter, nested-object, destructive bulk tool with an output schema, the description covers the workflow, safety gates, exclusion behavior, report creation and what the returned links mean. 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 schema already documents each parameter; the description adds cross-parameter workflow meaning instead of repeating field text — confirm only after approval, reuse the same operationId, set createReport on the confirmed call, excludePersonal semantics. It stops short of explaining undo/status/approveNewGroup interplay, so not a 5.

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 (group) and resource (an exact set of recorded expenses) plus the user-named destination kinds, with concrete examples. It also names the sibling it depends on (search_expenses) and the one it replaces (create_report), so an agent can distinguish it 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?

Explicitly says when to use it, when not to call adjacent tools ('do not call check_compliance, get_report_details or tax/deductibility tools'), and that a separate create_report must not be run. The preview-then-confirm workflow and the replaceExistingTags condition are stated outright.

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.