ExpenseBot

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

Beyond the annotations, the description discloses concrete side effects: it writes directly to the spreadsheet after confirmation, reuses or creates the canonical client group, applies 'Cash advance received', and stores client advances as negative expenses. This goes well beyond the structured annotations, though it does not mention reversal or post-write behavior in much detail.

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

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

The description is longer than average, but every sentence carries operational value and the two modes are clearly separated. The most important constraint, 'never for vendor refunds...', is explicitly front-loaded before naming the alternative, which keeps the structure scannable despite its length.

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

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

For a 12-parameter, two-mode write tool, the description covers the required workflow, mode-specific parameter requirements, exclusions, and the fallback alternative. Since an output schema is present, the description does not need to explain return values, and nothing material appears missing for an agent deciding whether and how to invoke this 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%, but the description adds meaningful cross-parameter semantics: category must come from list_categories, isClientAdvance requires clientName and does not require category, merchant is derived from clientName for advances, and total is stored as negative for advances. These relationships are not present in the individual parameter descriptions.

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

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

The description opens with a specific verb and two identifiable actions: adding an expense without a receipt or recording a client advance. It also names the write target, 'user's expense spreadsheet', and distinguishes the client-advance mode from ordinary expenses, which sets it apart from sibling tools like add_income or update_expense.

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

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

The description gives explicit when-to-use guidance: call list_categories first for ordinary expenses, set isClientAdvance=true and clientName for client advances, and never use this tool for vendor refunds, reimbursements, earned fees, retainers, or generic deposits. It also names the alternative, the Manual expense link from get_spreadsheet_url, with the exact conditions under which that alternative should be preferred.

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

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

The description discloses that the tool writes to the Income tab, that an omitted category defaults to Service income, and that unknown categories are rejected. It could be even more explicit about the direct-write/no-confirmation behavior compared to the staging alternatives, but the annotations already signal this is not read-only.

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

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

The description is dense but every sentence earns its place: scope, anti-patterns, sibling routing, side effects, use case, and category prerequisite. It is front-loaded and contains no filler.

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

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

For a single-write tool with high schema coverage and an output schema, the description provides all essential context: what it does, when not to use it, alternatives, side effects, and required category lookup. Nothing critical is missing.

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

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

Schema coverage is 92%, so the schema does most of the parametric work. The description adds valuable semantics beyond the schema: category must be a fixed tax category from list_income_categories, omitted categories default to Service income, and unknown categories are rejected.

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

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

The description opens with a precise verb+resource: 'Log exactly one user-confirmed income payment manually'. It clearly distinguishes this tool from add_income_from_csv and add_income_from_file by scope and invocation model.

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

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

It explicitly says never to loop this tool over multi-row data and names the exact alternate tools for CSV/TSV/text and image/PDF inputs. It also tells the agent to call list_income_categories first and clarifies when this tool is useful relative to auto-detection.

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

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

Annotations only say readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description carries the behavioral burden. It discloses the two-step write contract, the 15-minute preview expiry, that expired/unknown previewIds never write, duplicate skipping unless explicitly kept, and the max 500 KB file size. This is rich behavioral context that goes well beyond the annotations.

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

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

The description is dense and front-loaded with the core action and supported sources, then walks through the two-step contract in a logical order. It is long, but nearly every sentence earns its place given the complexity of the two-step flow and the number of parameters. A small amount of redundancy exists (e.g., repeating the same two-step contract as add_income_from_file), but it is not bloated.

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

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

Given the tool's complexity (10 params, nested objects, two-step contract, output schema present), the description covers the workflow, safety guarantees, expiry, duplicate handling, and post-confirm next steps (spreadsheetUrl and reviewIncomeUrl). The output schema exists, so return values need not be spelled out. Nothing essential is missing for an agent to invoke this correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the step-1/step-2 roles of parameters (e.g., confirm, previewId, selectedIndexes, keepBothIndexes, rowEdits, tag, bulkNote) and by clarifying that csvText is a legacy fallback while ChatGPT should use csvContent. That is meaningful semantic guidance beyond the schema.

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

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

The description opens with a specific verb and resource ('Import income from a CSV/TSV/text export') and immediately enumerates supported sources, which distinguishes it from generic import tools. It also names the sibling add_income_from_file and frames this as the same two-step contract, so an agent can tell them apart.

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

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

The description gives an explicit two-step protocol: step 1 with csvContent and without confirm, step 2 with confirm:true and previewId. It also states what not to do ('NOTHING is saved in step 1') and what to show the user, which is strong usage guidance beyond the schema.

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 provide readOnlyHint, openWorldHint, and destructiveHint, all false. The description takes on the full burden and thoroughly discloses that step 1 saves nothing, writes only happen with confirm, previews expire after 15 minutes, and duplicates are skipped unless keepBoth is requested.

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

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

The description is lengthy but well-structured, beginning with purpose and formats, then breaking into STEP 1 and STEP 2. Every sentence earned its place in a complex two-step tool with 11 parameters.

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

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

The definition covers file constraints, consent boundaries, preview details, expiration, duplicate handling, and the appropriate next integration. With an output schema present, it fully equips an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds step-specific orchestration (selectedIndexes, keepBothIndexes, rowEdits, confirm, previewId) that links parameters to the preview/confirm workflow, raising it above baseline.

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

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

The description begins with a specific verb and resource: 'Import income' from attached images/PDFs. It clearly enumerates supported file formats and references the same importer as the app's Add Income screen, making its scope 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 a complete two-step protocol, explaining when to call with confirm vs. without, how to handle duplicates, and when to route the user to the Add Income app link. It explicitly guides step 1 vs. step 2 behavior and leaves no ambiguity about when the tool should be used.

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

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

Annotations already establish readOnlyHint=false, indicating a write operation. The description goes beyond this by specifying the concrete side effect: 'writes a row to their expense spreadsheet with the calculated dollar value.' It also discloses the requirement for pre-configured mileage settings. This adds useful behavioral context beyond the annotation, though it does not detail error handling or validation behavior.

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

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

The description is three sentences with zero filler. The primary action is stated first, followed by prerequisites, the effect, and a clear alternative. Every sentence serves a distinct purpose and the structure is efficiently front-loaded.

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

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

Given the tool's complexity (9 parameters, 2 required), the presence of an output schema, and the annotations, the description covers the essential context: what it does, prerequisites, side effects, and when to prefer an alternative. It does not explain potential error conditions or response format, but the output schema covers returns. This is sufficient for an agent to correctly invoke the tool.

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

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

Schema description coverage is 100%, with each parameter already documented in the input schema (e.g., distance described as 'in the user's configured unit', roundTrip as 'doubles the distance'). The tool description does not add any additional parameter-level meaning beyond what the schema provides. With high coverage, 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 opens with a clear verb and resource: 'Log a business mileage trip in ExpenseBot.' It specifies the target audience (realtors, consultants, contractors) and distinguishes itself from the alternative get_spreadsheet_url by listing explicit use cases it does not cover, such as route calculation or import. This makes the tool's unique role unambiguous.

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

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

The description gives explicit when-to-use guidance ('Log a business mileage trip') and when-not-to-use guidance by naming the alternative tool and the exact conditions that should route the agent elsewhere (Google Maps, mileage settings, repeated trips, etc.). It also states the prerequisite (configured mileage rate and unit), leaving no ambiguity about the appropriate context for calling this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description goes beyond them by defining the required user intent and explicitly prohibiting automatic invocation, which is a meaningful behavioral constraint and clarifies that this is not a side-effect-free routine to run casually.

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

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

The description is compact, front-loaded with the core condition, and uses the second sentence to prevent common misuse. Every clause contributes useful guidance with no wasted words.

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

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

The definition covers what the tool does, when to use it, when not to use it, and the precise nature of the required user request. An output schema exists, so return values need not be described, and no critical operational context is missing.

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

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

Schema description coverage is 100%, so the schema already documents both reportId and userRequest. The description reinforces that the report must already exist and that userRequest must be literal, but it adds only marginal meaning beyond the schema's own parameter descriptions.

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

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

The description states a specific verb and resource: 'check an existing report for compliance issues,' with concrete examples like missing business purpose or policy violations. It also clearly distinguishes this from sibling workflows such as creating, sharing, or billing reports, so an agent can correctly identify the tool's scope.

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

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

Usage is explicit: call only when the user explicitly asks for a compliance check, and never automatically as a preflight or follow-up. The description also names non-compliance workflows (creating a report, excluding Personal expenses, sharing, billing) to prevent misuse.

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

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

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, so the safety profile is known. The description adds that this is an 'advice' tool and that results depend on country/jurisdiction, providing context beyond the annotations. It does not contradict any annotation.

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

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

The description is two sentences, front-loaded with purpose and examples, then provides the exclusion. It is concise and well-structured, though the second sentence is somewhat long with multiple examples. No wasted words.

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

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

The output schema exists, so return values are covered. The description includes examples, jurisdictional context, and explicit exclusions. Given the moderate complexity and that annotations cover safety, the description is nearly complete. The only minor gap is lack of parameter elaboration for optional fields.

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

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

Schema description coverage is only 33% (only 'query' is described). The description does not mention 'category' or 'merchant' parameters, nor their purpose. Given the low coverage, the description should compensate, but it only explains the primary 'query' parameter implicitly. The agent is left without guidance on the optional parameters.

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

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

The description clearly states the tool's function: to look up tax deductibility based on jurisdiction, with specific examples. It distinguishes itself from siblings like get_spending_summary, which handles tax refunds. The verb 'look up' and resource 'tax deductibility' are precise.

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 provides when to use ('is Uber deductible', 'home office write-off') and when not to use (tax refunds, routed to get_spending_summary). Names the alternative tool and the condition for switching, leaving no ambiguity.

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

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

Annotations supply destructiveHint=true, but the description goes far beyond that: premature confirm:true is converted to preview, formula Notes and over-limit changes are skipped safely, attendeeMode add vs replace semantics, Notes preservation, confirmed result counts, and Undo support. These are behavioral traits the structured annotations cannot express, and they materially change 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 long but every sentence earns its place for a complex two-phase tool. It front-loads the core purpose and examples, then walks through the preview/confirm lifecycle, then edge cases, then exclusions and fallback. Dense but highly structured, with no redundant filler or repetition of schema trivia.

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

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

Given the tool's complexity (two-phase confirm flow, conflict detection, undo, attendee modes, 100-row limit, external fallback), the description covers all decision-relevant aspects: how to prepare the selection, how to execute the preview and confirmation, what happens on premature confirmation, what is preserved vs skipped, and what the confirmed result reports. The output schema covers return values, so nothing needed for correct use 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%, but the description adds crucial meaning beyond field names: operationId is a 'stable idempotency key generated once for preview and reused unchanged,' selection must 'never broaden this list after preview,' expected values are for 'optimistic-concurrency... conflict detection,' and attendees 'must come explicitly from the user; never infer them.' These semantics are essential for correct invocation and are absent from 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 opening sentence states a specific verb + resource + scope: 'Safely correct the category, business purpose, or explicit attendees on an exact bounded set of recorded expenses.' The examples further clarify real intent, and the closing exclusions (does not omit duplicates, change amounts/dates, infer business context, run broad Calendar matching) sharply delimit what this tool is not, distinguishing it from siblings like update_expense, fix_compliance, and group_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?

Explicit when-to-use and workflow: 'First use search_expenses to identify the exact rows, then pass their full expenseId values.' The preview/confirm protocol is spelled out step-by-step, and an explicit fallback is given: 'For unsupported or more than 100-row cleanup, send the user to https://...' There is also a clear list of things the tool does NOT do, which doubles as a negative usage guide.

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 indicate readOnlyHint=false, openWorldHint=false, destructiveHint=false, but the description adds significant behavioral context: it explains the excludePersonal behavior (excludes both Personal tag and category), dedup behavior (no duplicate report if no unreported matches), and that the link 'opens the reviewed app flow and does not mean an export occurred'. It also clarifies that the report may include matching expenses not assigned to other reports. This goes beyond the annotations, so a 4 is appropriate.

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

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

The description is long but well-structured audio. It starts with the main use case, then adds important notes about tags, examples, return value, duplicate handling, and guidance on when not to call other tools. Each sentence adds substantive guidance beyond the schema. Although it is verbose, it is front-loaded with the most critical information and avoids redundancy with the schema. A 4 is justified because it is detailed yet coherent, not full of fluff.

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

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

Given that an output schema exists (context signal indicates it does), the description does not need to explain return values, but it still does mention key outputs (summary, links, filters). It also covers edge cases like duplicate reports. It is complete for a complex tool with 9 parameters and multiple date range variants. The description ensures an agent will not misuse it by calling forbidden redirects or skipping deduplication.

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

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

The input schema has 100% description coverage, so the schema itself documents all 9 parameters. However, the description adds valuable insights: it explains the purpose of tags as grouping layer, the meaning of excludePersonal, and provides specific examples for dateRange variants. It also subtly hints at the purpose of recipientRole. This is above the baseline 3 because it goes beyond merely repeating schema descriptions.

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

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

The description clearly states the tool's purpose: 'Create an expense report' with specific criteria (date, client, project, trip, category, or merchant). It also explicitly mentions tags as the grouping layer and contrasts with list_tags. The title 'Create expense report' reinforces the purpose, and the description effectively distinguishes this tool from siblings like get_report_details or send_report_to_accounting.

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

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

The description provides explicit when-to-use guidance: it instructs to call list_tags when the user's intended group is unclear. It also gives clear examples like handling 'all expenses in August except personal' and sets expectations about duplicate reports and when not to call related tools (check_compliance, get_report_details). It explicitly tells the agent to complete the request directly and not call other analysis 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?

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

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

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

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

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

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

Given the tool has only one parameter, an output schema exists, and the annotations provide safety context, the description is complete. It explains how to construct/obtain the id, what the id encodes, and what the return value contains (full content + metadata). No additional context is needed for correct invocation.

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

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

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

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

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

The description clearly states the tool fetches full details for a specific item returned by `search`, using a specific verb and resource. It distinguishes itself by explaining the two id formats (expense and report) and emphasizing that the id must be used exactly as returned, which clarifies its scope as a unified fetch tool.

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

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

The description gives clear context on when to use the tool: after a `search` or `list_reports` call. It instructs the agent to use the id exactly as returned and not to modify it. However, it does not explicitly mention alternatives like `get_expense_by_id` or `get_report_details`, so it lacks explicit exclusions.

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

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

Beyond the annotations (readOnlyHint: false, destructiveHint: true), the description discloses the critical two-step workflow: first call always prepares a preview and makes no change even if confirm:true arrives early, explicit approval is required, and the confirmed result reports applied/conflicted/failed counts with status and Undo support. This is rich behavioral context that the annotations alone do not provide.

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

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

The description is longer than average, but every sentence earns its place by adding operational detail. It is front-loaded with the purpose, then logically proceeds through usage, workflow, and alternatives. While dense, it is not verbose and remains well-structured.

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

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

Given the tool's complexity (6 parameters, nested objects, output schema), the description covers all essential aspects: the two-step approval flow, the need for exact IDs, the constraints on selection and change, the output counts, and the alternatives. 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?

The schema has 100% coverage, but the description adds critical semantic constraints: operationId must be stable and reused, selection must be exact from search_expenses and never broadened after preview, and change must be exactly one correction. It also warns against selecting every report row and inferring values, which goes beyond the schema's property descriptions.

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

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

The description states a specific verb and resource: 'Safely correct compliance issues on an exact bounded set of recorded expenses.' It also clearly distinguishes itself from siblings by naming correct_expenses as the reviewed workflow, group_expenses for tags/groups, and providing a URL for unsupported cleanup. This leaves no ambiguity about what the tool does or which 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?

Explicitly instructs to use only after the user asks to fix issues found by check_compliance, mandates using search_expenses to obtain exact expense IDs, and warns against inferring business purpose, category, or attendee. It also names alternatives for other cases (group_expenses and the external URL), giving clear when-to-use and when-not-to-use guidance.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds a small amount of meaning beyond the schema: for reportId, it explains that the setup link opens the exact report's provider setup control, which is more specific than the schema's 'opens this exact report'. For provider, the description adds that certain providers are accepted for connection onlyholistic. But overall, since the schema already covers the parameters well, a baseline of 3 is appropriate.

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

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

The description clearly states the tool checks connection status and read-only setup state for an accounting destination, with a specific verb (check) and resource (accounting integration status). It distinguishes itself from siblings like request_accounting_integration (which initiates connection) and get_accounting_push_status (which is about posting), by explicitly mentioning connection/setup state and read-only behavior.

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

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

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

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

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

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

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

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

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

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

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

For a two-parameter read-only tool with an output schema, the description covers the essential use case (checking status after timeout), the return contents, and the critical behavioral rule (don't re-post). It also notes the owner-account restriction. Nothing critical is missing for correct invocation.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Front-loaded purpose, enumerates the key returned fields, states the input requirement and read-only nature. Dense but efficient; no filler.

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

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

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

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

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

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

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

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

Uses a specific verb ('Get') and a clear resource ('full financial and delivery summary for one issued client invoice'), and enumerates the returned fields. This distinguishes it from list/prepare/update invoice siblings.

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

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

Provides clear guidance on the required identifier, the one-required rule, and the uniqueness constraint on invoiceNumber. Does not explicitly name alternatives, but the usage context is clear.

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

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

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

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

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

The description is compact and front-loaded: it states the resource and scope in the first sentence, provides example queries, and then gives behavioral and parameter context. Every sentence earns its place, and the read-only note is a useful addition without bloat.

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

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

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

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (limit, dateRange, clientEmail). The description adds context for dateRange ('narrow with dateRange') and limit ('default 25, newest first'), but does not add significant meaning beyond the schema. Baseline 3 is appropriate.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

For a complex analytics tool, the description covers purpose, invocation context, asynchronous behavior, and important return metadata (sampleMeta.isTruncated). The schema and output schema handle the parameter and return details, so nothing critical is missing for an agent to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents both `query` and the `dateRange` variants in detail. The description reinforces the query semantics with examples but does not add substantial new parameter meaning beyond what the schema provides. This is the appropriate baseline.

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

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

The description states a specific verb and resource ('Run deeper, multi-step analytics on the user's expenses') and gives concrete example questions that distinguish it from simpler reporting tools like get_spending_summary or get_pnl. The 'deeper, multi-step' phrasing and explanatory-question use cases make the tool's purpose clear and differentiated.

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it returns headers + values + a labeled map, which is useful behavioral context beyond the annotations. It also explicitly says 'Read-only' reinforcing the annotation. No contradiction.

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

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

Two sentences, front-loaded with the core function and lookup keys, then return format and use case. No wasted words.

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

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

The tool has an output schema, so return values are covered. The description explains the two lookup methods and the use case. It doesn't mention edge cases like what happens if both parameters are provided, but that's a minor gap given the schema and output schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters well. The description adds the clarification that expenseId is the exact Receipt ID in Column Q, which reinforces the schema but doesn't add much beyond it. 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 fetches a single expense row by either sheet row number or ExpenseBot expenseId, and explicitly names the exact Receipt ID in Column Q. It distinguishes itself from sibling tools like search_expenses and get_expense_splits by focusing on a single expense row lookup.

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

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

The description implies when to use this tool: when the user mentioned a specific expense and you need its row details. It doesn't explicitly name alternatives or exclusions, but the context of 'refer to a specific expense the user mentioned' gives clear usage context. Sibling tools like search_expenses exist, but the description doesn't explicitly contrast 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?

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

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

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

The description is compact and front-loaded, leading with the core action, then key behavioral nuance, then examples, then a read-only note. No sentence is wasted, and the structure makes the tool's purpose immediately scannable.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is set. The description adds meaningful behavioral detail beyond that: the tax-routing exclusion ('security deposits, refunds excluded from taxable totals'), the support for period comparisons, and the exact return shape ({ message, data: { total, breakdown?, comparison?, sampleMeta? } }). These are not in the schema or annotations, giving the agent a clear picture of tool behavior.

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

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

The description is dense but efficiently structured: purpose → coverage → exclusions → examples → comparison support → return format. Every sentence contributes new information; there is no filler or repetition. Despite its length, it remains front-loaded and scannable, making it easy for an agent to extract the key facts.

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

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

For a tool with four parameters (all optional) and complex breakdown logic, the description is remarkably complete. It specifies the data scope, the breakdown dimensions, the exclusions, the comparison phrases, and the return structure. The presence of an output schema further reduces the need for description-level explanation. Nothing an agent needs to invoke this tool correctly is missing.

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

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

Schema coverage is 100%, so each parameter (query, groupBy, dateRange, incomeTagPrefix) is already described in the schema. The description adds value through concrete examples ('income YTD by source', 'rental income last month') and explains how the query parameter supports comparison phrasing, which is not fully captured in the schema's generic description. This enriches parameter understanding without redundancy.

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

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

The description opens with 'Get income totals, breakdowns, and analytics from the Income tab' – a clear verb, resource, and scope. It then enumerates specific income types (Schedule C/T2125, Schedule B drill-in, rental) and breakdown dimensions (source, payment method, category, month, tag), distinguishing it from sibling tools like get_spending_summary or get_pnl. The examples ('income YTD', 'rental income by property') further cement the tool's purpose.

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

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

The description gives clear context on when to use this tool: for any income-related question, with explicit coverage of income categories and breakdown options. It does not explicitly name alternatives or state when NOT to use it (e.g., 'for spending use get_spending_summary'), but the scope is unambiguous enough that an agent can route correctly. The period comparison support (YoY, MoM, QoQ) also clarifies valid usage patterns.

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

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

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

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

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

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

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

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

Given the tool's complexity, the description covers all necessary aspects: what it does, how to call it (submissionId and polling), what happens when pending vs. terminal, what the return values are (verdicts, counts, URLs), and when to use an alternative. There is an output schema, but the description already explains the key return semantics in a way the agent can act on. Nothing critical is missing.

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

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

The input schema already covers both parameters with descriptions, so the baseline is 3. The description adds value by clarifying that submissionId must be the exact ID returned by submit_receipt and that the polling interval and time allowance from that response should be used. It reinforces the relationship between the parameters and the submission workflow, slightly exceeding schema information.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

With a rich output schema, full parameter documentation, and read-only annotations, the description only needs to cover scoping and use conditions. It does so with practical examples, comparison semantics, and country-aware deduction behavior. It could still be more explicit about sibling-tool routing or how query, groupBy, and dateRange interact, but nothing essential is missing for correct invocation.

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

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

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

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

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

The description opens with a specific action-target pair—'Mileage analytics'—and enumerates totals, breakdown dimensions, and deduction framing, making the tool's scope unmistakable. The mileage focus clearly distinguishes it from sibling reporting tools like get_income_summary and get_spending_summary.

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable context: figures come from the user's own data, advisory notes are estimates and not tax advice, and it defaults to the last completed month. These disclosures go beyond the annotations and are relevant for an agent deciding whether to invoke this tool.

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

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

The description is concise, front-loaded with the core summary, and includes examples and a caveat in a compact form. It avoids redundancy and stays focused. While it could be slightly more structured, it is efficient and easy to scan.

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

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

With an output schema present and annotations covering safety, the description adequately covers what the tool does, its default behavior, and a caveat about data sources. It does not mention edge cases like missing data for the month, but that is not critical given the output schema and overall completeness. The description provides sufficient context for an agent to call it correctly.

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

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

Schema coverage is 100%, so both parameters (period and clientEmail) are fully documented in the input schema. The description reiterates the default for period but adds no new semantic detail beyond what the schema provides. Per the rubric, the baseline of 3 is appropriate when the schema already handles parameter documentation.

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: provides a month-end summary of the user's books for a calendar month, enumerating contents (income, spending, net, categories, merchants, alerts). It distinguishes itself from sibling tools like get_pnl and get_income_summary by focusing on a comprehensive monthly overview. The inclusion of example queries reinforces the tool's purpose.

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

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

Clear context is provided via example queries ('how did last month go', 'close out my books for June'), indicating when to use this tool for month-end reviews. However, it does not explicitly name alternative tools or state when not to use it, so it lacks explicit exclusions. The context is strong enough for an agent to infer appropriate usage.

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

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

Beyond the readOnlyHint=true and destructiveHint=false annotations, the description discloses key behaviors: the requirement for matching tags on income and expense rows, that margin renders as a multiplier in loss territory, and that the tool defaults to year-to-date when no date range is given. These are valuable behavioral details not captured in annotations.

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

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

The description is long but well-organized: it leads with the core purpose, then prerequisites, tag prefixes, examples, and behavioral quirks. Every sentence adds value, and the structure is front-loaded with the most important information. It is slightly verbose but not padded.

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

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

For a tool with three parameters (including a complex dateRange schema) and an output schema, the description covers the main use cases, preconditions, defaults, and output quirks. Nothing essential is missing for an agent to invoke it correctly.

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

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

The schema already provides descriptions for all parameters (100% coverage), but the description adds significant contextual meaning: it explains tag-prefix shortcuts (e.g., 'Prop –' for properties), provides example natural-language queries for the query parameter, and clarifies the default behavior of the dateRange parameter. This enriches the schema beyond its raw definitions.

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

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

The description clearly states the tool produces per-tag P&L (revenue, cost, profit, margin) grouped by tag, and explicitly lists the tag categories (client, property, event, realtor-deal). It includes concrete example queries that make the purpose unmistakable and distinguishes it from broader P&L tools like get_pnl.

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

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

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

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

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

Annotations already cover readOnly=true and destructiveHint=false, so the safety profile is established. The description adds meaningful behavior beyond that: it combines Income and expense tabs, supports comparison modes, and discloses the unusual loss-territory margin rendering ('expenses 5.4× revenue'). This is useful behavioral context that the annotations do not provide.

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

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

The description is front-loaded with the core action, then supplies illustrative examples, supported comparisons, an edge-case behavior, and the return shape in a compact, structured way. Every sentence contributes operational value with no filler or repetition of schema details.

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

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

For a natural-language analysis tool with three parameters, the description covers the core calculation, query phrasing, comparison capabilities, the loss-territory margin behavior, and the return structure. Since an output schema exists, return values do not need further explanation, and nothing an agent needs to invoke the tool correctly appears to be 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, dateRange, and clientEmail thoroughly. The description's example phrases add some color to the query parameter, but it does not materially extend the semantic information already present in the schema. Baseline 3 is appropriate.

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

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

The description starts with a specific verb and resource: 'Compute Profit & Loss (P&L / net income / margin) by combining the Income tab with expense tabs.' It also lists concrete question phrasings and clearly distinguishes this from the sibling get_per_tag_pnl by framing it as the aggregate P&L tool. An agent can tell what it does and when it applies 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?

The description gives a clear situational context through example queries ('am I profitable this year', 'P&L for Q1', 'net income last quarter') and states the supported period comparisons (YoY, MoM, QoQ). It does not explicitly name alternatives or say when not to use this tool, so it stops short of a 5, but the usage scope 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 cover read-only and non-destructive nature, and the description adds valuable context about what the log contains (tool calls, arguments, timestamps, success/failure). It also states the default limit and maximum, which are not in annotations. Since annotations cover safety, the description provides additional behavioral detail without contradicting them.

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

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

The description is three sentences with no fluff. The primary purpose is stated first, followed by a clarifying distinction and then usage context and parameters. Every sentence earns its place, and the length is proportional to the tool's complexity.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, establishing the tool as a safe read operation. The description adds the scope of returned content and a strict anti-preflight rule, but does not disclose additional behavioral traits such as error conditions, permissions, or data freshness. It is consistent with annotations, so no contradiction.

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

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

Two sentences: the first states the purpose, the second states usage constraints. There is no filler, and the core function is front-loaded before the usage warnings.

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 values are covered. All three parameters are documented in the schema, and the description provides clear when-to-use and when-not-to-use guidance. There are no missing pieces for an agent to call it correctly.

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

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

Schema description coverage is 100%, with each parameter having a meaningful description (reportId, clientEmail, userRequest). The tool description itself does not add parameter-level context, so it meets the baseline of 3 for schema-documented parameters.

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

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

The description names a specific verb ('Get'), a resource ('a specific expense report'), and the scope of details (expenses, totals, compliance status). This distinguishes it from sibling tools like list_reports (which lists reports) and get_expense_by_id (which targets a single expense).

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

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

Explicitly states when to use the tool ('only when the user explicitly asks to inspect an existing report's details') and when not to use it ('Never call this as a preflight or follow-up to creating, sharing, or billing'), and points to alternatives that already return the required results. This leaves no ambiguity for an agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only.' It goes beyond the annotations by detailing the fields returned (spreadsheetUrl, reviewExpensesUrl, gmailScanUrl) and instructing which to display under which condition, plus noting the data mirrors the in-app status pill. No contradictions with annotations.

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

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

The description is well-structured: it opens with the core purpose, then lists returned data, then gives usage triggers and follow-up actions, and closes with 'Read-only.' Every sentence adds value; it is compact without being terse, and the most critical info (purpose and when to call) is front-loaded.

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

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

For a read-only status tool with no parameters and an output schema (which presumably documents the return structure), the description covers the essential agent needs: what it returns, when to call, and how to act on the results. It could mention edge cases (e.g., no active scan) but these are likely implied by the output schema, so it is sufficiently complete.

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

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

The tool has zero parameters, so the description carries no parameter burden. The baseline for 0 parameters is 4, and the description adds no unnecessary parameter info. Schema coverage is trivially 100% (empty schema), so this score is appropriate.

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

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

The description opens with a specific verb and resource: 'Check the authoritative status of the user's Gmail receipt scans.' It enumerates the exact returned data (scan lock, live phase, item progress, years, exclusions, outcomes) and explicitly ties it to a status-pill context, which clearly differentiates it from siblings like scan_gmail (which initiates scans) and get_last_receipt_result (which returns a single result).

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

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

The description gives an explicit trigger: 'Call when the user asks whether a scan is running, finished, stuck, or what it is doing.' It also provides follow-up actions (show spreadsheetUrl/reviewExpensesUrl when complete, gmailScanUrl when setup needed). However, it does not explicitly state when NOT to use it or name alternative tools, so it lacks exclusions.

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

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 67%, and the two undocumented parameters (metric and groupBy) are clear from the description: it lists 'category, merchant, month, tag, source, or payment method' and 'total, count, or average metrics', mapping directly to the enum values. This adds real semantics beyond the schema. Other params (query, dateRange, categories, clientEmail) are adequately described in the schema.

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

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

The description states a specific verb and resource: 'Summarize the user's recorded expenses with totals and breakdowns...' It also enumerates grouping dimensions and metrics, making the intent concrete. It does not explicitly name sibling alternatives like get_income_summary or get_pnl, but the 'expenses' scope and read-only nature implicitly distinguish it from those.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description is compact and front-loaded: first sentence states the purpose, then a short example list, then a brief return signature. Every part earns its place; no verbose filler or circular wording.

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

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

Combined with a rich input schema and an existing output schema, the description supplies the tool's engine, domain keywords, natural-language examples, and return shape. There is no material gap that would prevent an agent from choosing and calling the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description's natural-language examples give useful phrasing for the `query` parameter, but it does not clarify the relationship between `focus` and `query` (e.g., whether query overrides focus or they combine), which is a real semantic gap beyond the schema.

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

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

The description names a specific resource ('subscriptions') and a clear verb ('audit/find'), enumerates the exact categories it returns (recurring, duplicates, price increases, trial conversions), and gives natural-language examples. It does not explicitly contrast itself with sibling tools like get_spending_summary or get_deep_analytics, so it stops short of a 5.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The description opens with a precise statement of what the tool does: it shows ExpenseBot's high-confidence Trip Intelligence proposals from Review Expenses. It clearly distinguishes itself from write operations by explicitly listing what it never does (groups, tags, creates reports, writes to spreadsheet) and provides a concrete handoff path (Review Expenses or owner's assistant) that separates it from sibling tools. The purpose is unambiguous and specific.

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

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

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

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

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

Annotations indicate destructiveHint=true, and the description is exceptionally transparent about side effects: preview is automatic, premature confirm converts to preview, personal expenses are excluded before preview, existing report assignments cause exclusion, and Bill Client URL does not confirm invoice. Adds critical behavioral context beyond annotations.

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

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

The description is long but dense and front-loaded with the core purpose and examples. Every sentence adds operational detail, but it feels overly verbose for an agent, risking cognitive overload. Some redundancy exists in the workflow description, though it is informative.

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

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

Given the tool's complexity (12 params, nested objects, destructive mutation), the description covers the full workflow, parameter usage, exclusions, edge cases, and output interpretation. The output schema exists, so return values are likely documented there. Highly complete for safe invocation.

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

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

Schema coverage is 100%, so the description adds limited parameter-specific detail. It does clarify the confirm parameter's dual preview/confirmation role and that selection must not be broadened, but the schema already documents all fields accurately. 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 groups expenses under a user-named purpose, with concrete examples. It distinguishes from siblings by noting it's for grouping (not creating reports or compliance checks), though it does not explicitly name a specific sibling for comparison.

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

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

Provides explicit when-to-use and when-not-to-use guidance: instructs to use exact expenseIds from search_expenses, clarifies that check_compliance and get_report_details should not be called unless explicitly requested, and details the two-step preview/confirm workflow. Strong contrast with create_report and share_report.

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

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

Annotations already provide readOnlyHint, safeHint, and destructiveHint, so the read-only behavior is covered. The description adds a meaningful behavioral detail: it returns the 'live list from their spreadsheet', clarifying that freshness depends on the user's spreadsheet state. That is useful beyond the annotations.

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

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

The description is three short sentences with no filler, and the most decision-critical information (what it lists and when to call it) comes first. The final sentence adds live-data context without redundancy.

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

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

For a zero-parameter read-only listing tool, the description covers the what, the when, the why (avoid guesses), and the data source. The annotations already carry the safety profile, and the output schema exists, so nothing an agent needs to correctly invoke it 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?

There are zero parameters and the schema is fully described (100% coverage) as an empty object, so the baseline is 4. The description focuses on the output value, communicating what the returned categories 'are the user's actual category names' rather than guesses, which supports the purpose but is not about input semantics.

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

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

The description lists a specific verb ('list') and precise resource ('the user's configured expense categories and billing accounts'). It distinguishes itself from sibling tools such as list_income_categories by explicitly limiting to expense categories and adding billing accounts.

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

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

It explicitly tells agents when to use it: 'Use this BEFORE calling tools that need a category' and gives concrete sibling examples (add_cash_expense, add_mileage_entry, create_report). This goes beyond general timing and directly maps to concrete workflows.

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

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

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

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

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

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

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

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

Given the tool's complexity (four optional parameters, an output schema, and a clear read-only role), the description covers the essential context: what it lists, how to filter, and what it returns. The limit parameter is documented in the schema, and the output schema handles return details. Nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning for the parameters beyond what the schema already documents; it only reiterates the status enum values and default, which are already in the schema. No additional semantic value is provided.

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

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

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

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

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

The description gives example phrasings that map to typical use cases and enumerates the status filter options, providing clear context for when to use this tool. It does not explicitly name alternatives or say when not to use it, but the examples imply the intended scope, so this is strong but not explicit on exclusions.

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

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

Annotations already provide read-only and non-destructive hints. The description adds that the categories are fixed and not user-configured, which is a useful behavioral fact but largely reinforces the existing openWorldHint=false annotation. There is no contradiction.

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

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

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

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

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

For a zero-parameter list tool with an output schema present and annotations covering read-only/destructive behaviors, this description is complete. It tells the agent when to use it, what it is, and why it matters, so nothing essential is missing.

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

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

This tool has zero parameters and 100% schema description coverage. The description does not need to add parameter detail, so the high baseline of 4 applies.

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

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

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

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

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

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

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

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

Beyond the readOnlyHint, the description discloses that results embed accounting handoff URLs and warns against acting on them unless explicitly asked. The note that 'the app keeps organization, mapping, and final confirmation' clarifies the tool's limits, adding meaningful behavioral context.

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

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

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

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

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

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

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

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

Schema coverage is 100%, with page, limit, filter, and clientEmail all described. The description adds only high-level context about pagination and status, and does not meaningfully extend the parameter explanations beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'List the user's expense reports with pagination.' It is unambiguous against siblings like add_expense or export_report because the focus is purely read-only listing. The mention of status filtering and returned URLs further distinguishes it from detail or send operations.

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

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

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

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the main safety concern is covered by structured data. The description adds clarity about what data is listed (clients, projects, project codes, properties, trips), but it does not disclose any deeper behavioral traits such as pagination, response limits, or auth requirements. This is adequate though not exceptional.

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

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

Three sentences, front-loaded with the core responsibility, followed by helpful examples and usage timing. Nothing is wasted, though the example list could be slightly shorter without loss of value.

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

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

For a zero-parameter read-only listing tool, the description fully covers what it returns conceptually, how the data is modeled, and when to invoke it. The output schema exists, so return structure does not need to be spelled out in the description. Minor ambiguity about whether all tags are returned or just top-level groups is not significant.

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 and schema coverage is 100%, so there are no parameter semantics to explain. The description compensates by making the meaning of the tool's resource domain clear, which is more useful here than parameter documentation would be.

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

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

The description names a specific verb and resource ('List the user's configured groups') and explains what counts as a group by giving concrete tag examples like 'Client: Acme' and 'Property: 123 Main'. It is clearly differentiated from sibling list tools such as list_categories and list_reports because it focuses on user-configured tags representing clients/projects/trips, though it does not explicitly name an alternative.

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

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

The description gives explicit use-case guidance: use it when the user asks 'what groups/projects/clients do I have?' and before filtering/grouping/reporting when an existing name is unclear. It lacks an explicit when-not-to-use clause naming alternatives, but the context it provides is sufficient for an agent to make an appropriate selection.

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