receipt-scanner

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

All annotations are false, so the description carries the burden. It discloses that it can both replace and list, and that it returns the stored rule list. It also notes integration with expense_add. However, it does not explicitly state that replacing overwrites the entire rule list (though 'Replace' implies it) or mention any side effects on existing data.

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

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

Three concise sentences, front-loaded with the main action. No redundancy; every sentence adds value (action, return, and context).

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 tool with one optional parameter and no output schema, the description covers the action, return, and the reason rules exist (used by expense_add). Details on matching logic are in the schema, so nothing critical is missing.

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

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

Schema description coverage is 100%, with the rules parameter well-documented ('The FULL rule list; it replaces the stored one...'). The tool description adds context about the dual behavior but does not extend parameter semantics beyond the schema. Baseline 3 applies.

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

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

States a clear action: replace the merchant-to-category rules or list them. It also mentions the rules are applied by expense_add, giving context. Does not explicitly differentiate from siblings, but no other tool manages rules, so purpose is distinct.

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 dual action (replace or list) implies usage, and the mention of expense_add provides context on when rules matter. However, it does not explicitly state when to use this tool versus alternatives or provide 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 are minimal (readOnlyHint false, idempotentHint false, etc.), so the description adds useful behavioral context by saying a new expense is recorded and that the response reports every applied default. This helps the caller understand the operation's side effects, though it does not cover reversibility, permissions, or duplicate handling.

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

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

Two sentences, front-loaded with the primary action, and every sentence earns its place. The description is compact while still conveying the outcome and the transparency guarantee about applied defaults.

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

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

Given a rich 12-parameter schema and the absence of an output schema, the description adequately covers the return value and the key caveat that defaults will be reported. It does not address when to choose this over sibling tools, but the schema covers parameter-level detail and the core create behavior is clear.

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

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

The schema already provides detailed descriptions for 92% of parameters, including defaults and aliases. The description adds only a broad hint about the net/VAT split and billable flag, which maps to vat_rate and billable but does not materially extend the parameter semantics covered by the schema.

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

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

The description clearly states a specific action ('Record one expense') and the resource, with useful result details (id, net/VAT split, billable flag). It is distinct from siblings like expense_update or expense_list, but it does not explicitly name or contrast itself with them, so it falls short of full differentiation.

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

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

No guidance is given on when to use this tool versus alternatives such as expense_update or mileage_add. The description states what the tool does but does not mention prerequisites, exclusions, or conditions for choosing a different sibling 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 mark destructiveHint=true, but the description adds valuable context: the tool 'reports what went,' the receipt FILE stays on disk, and deleting a rebilled expense loses invoice-charge history. These behaviors go beyond the structured annotations and help the agent anticipate consequences.

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 concise sentences, each carrying meaningful information: the action, a key side effect, and a critical exception. No filler or redundancy; the most important information is front-loaded.

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

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

For a one-parameter delete operation, the description covers the core action, the post-action report, the side effect on files, and the rebilled-expense exception. Combined with annotations, the agent has everything needed to invoke the tool correctly and safely.

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 only one parameter, 'id', with no description (0% coverage). The description's phrase 'by id' clarifies that the id is the expense identifier, not a file or other entity. While minimal, this is sufficient for a single-parameter tool and compensates for the schema gap.

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: 'Delete one expense by id.' It also distinguishes itself from the sibling expense_update, clarifying what this tool is not for. The purpose is immediately 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 provides a when-not-to-use case: 'Deleting a rebilled expense loses the record of what an invoice charged, so correct it with expense_update instead.' It also notes the receipt file remains on disk, which helps an agent decide whether this tool is appropriate.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral facts beyond those: the download link expires after one hour, and the export is atomic—no partial file is produced if a limit is hit. This is strong contextual disclosure.

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 short sentences, front-loaded with the action and return value, followed by an important caveat. Every sentence earns its place with no filler.

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

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

Core behavior and key caveats are present, and required parameters are clear. However, the optional filter parameters are left undefined, and the nature of the 'limit' is unspecified, so it is not fully complete for a 7-parameter tool without an output schema.

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

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

Schema coverage is only 43%, and the description adds little beyond the schema: 'date range' and 'csv, xlsx or json' restate from/to/format. It does not explain the meaning or effect of project, billable, category, or path, which are undocumented 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 ('Export'), a resource ('expenses'), a required date range, supported formats, and the return type (download link). It is unambiguous, though it does not explicitly distinguish itself from sibling tools like expense_list or expense_summary.

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

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

The description implies when to use the tool: when expense data needs to be exported in a file format. However, it gives no explicit when-not-to-use guidance, prerequisites, or references to 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 cover readOnlyHint, idempotentHint, and destructiveHint. The description adds value by disclosing the returned fields, per-currency totals, and the behavior around the 30-day free read window. There is no contradiction with annotations.

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

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

Two concise sentences with the main purpose and output details front-loaded. The free-tier explanation is compact and meaningful. No filler or redundant restatement of the tool name.

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

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

With no output schema, the description usefully explains the return shape and the free-tier date limitation. It omits pagination and ordering details, but these are minor for this kind of listing tool given the description's otherwise clear scope.

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 40%, covering just to/from. The description mentions date-range filtering and lists category/project/billable as fields, but it does not clarify that project, billable, and category are optional filters, their allowed values, or how they interact. It therefore does not adequately compensate for the low 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 names the operation and resource clearly ('List expenses') and adds specific detail about the returned data: net/VAT split, category, merchant, project, billable flag, and total per currency. It distinguishes itself from a summary or export implicitly, though it does not explicitly name a sibling 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 implies the intended use is retrieving expense records within a date range, and it adds a meaningful note about the free 30-day read window. However, it does not explicitly state when to prefer expense_summary, expense_export, or other sibling tools, nor does it provide 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 indicate this is a mutating, non-idempotent operation taking the safety burden down. The description adds behavioral context beyond annotations: the invoice must already exist, one currency group must be handled at a time, and the tool returns what was marked. It does not describe reversal or side effects, but the annotations plus schema cover the main traits.

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 compact sentences front-load the purpose and key prerequisite, then give a terse usage pattern and mention the return value. Every clause contributes meaning without elaboration or redundancy.

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

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

The description, combined with the fully described schema, covers the tool's purpose, input modes, precondition, grouping constraints, invoice_number's role, and return value. No critical calling information appears missing even though there is no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the two parameter usage patterns: the ids array from expense_to_invoice versus the project/from/to/currency group, and it explicitly associates currency with a single invoice group. This exceeds what the schema alone conveys.

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

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

The description names a specific action ('Mark expenses as rebilled') and ties it to a precise precondition ('once the invoice that carries them actually exists'). It also distinguishes its two input modes, which separates it from related tools like expense_to_invoice and expense_update.

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 clearly states when to use the tool and how to select the input mode: pass expense_ids from expense_to_invoice, or pass project/date range/currency. It does not explicitly mention when not to use alternatives, but the relationship to expense_to_invoice and the billing workflow is clear enough.

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

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

The description goes beyond the annotations by explaining that a no-argument call is side-effect free, that the tool returns stored defaults, and that the settings are fallback values used by expense_add. It does not specify partial-update semantics (e.g., whether omitting one field preserves the other), but the annotation set already covers safety traits.

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 short sentences, all informative, with the core action front-loaded and the safe-read instruction at the end. There is no filler or redundant restatement of the schema.

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

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

For a two-optional-parameter get/set tool with full schema documentation, the description gives enough to call it: what the defaults are, how they are used, and the no-argument read behavior. The only notable gap is that it does not explicitly state whether a set call with one argument preserves the other default, and there is no output schema to specify the exact response shape.

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

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

Schema coverage is 100% and both parameter descriptions already explain format, defaults, and effects. The description only names the two fields without adding syntax or constraints beyond the schema, so it earns 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 names a concrete action ('Read or set') and a specific resource ('the defaults expense_add uses'), and enumerates the two affected fields. It is clearly distinct from sibling tools like expense_add or expense_update, so an agent can identify it as the configuration tool.

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

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

It provides an explicit usage rule for the read case ('Call with no arguments to read them without changing anything') and makes the consumption relationship to expense_add clear ('uses when a call does not name them'). It does not explicitly state when not to use it or name alternatives such as passing values directly to expense_add, so it stops short of a 5.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds useful context beyond that: results are grouped per currency, include gross/net/VAT, and are never mixed, plus the receipts-only scope. 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 tightly written sentences, front-loaded with the core purpose and immediately followed by the key scoping caveat. Every clause earns its place.

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

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

For a read-only summary tool, the description covers the essential behavior, grouping dimensions, currency handling, and the receipts-only constraint. Minor gaps remain around the optional project/billable filters and the exact response format, but nothing that prevents 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 documents from, to, and group_by, and the description reinforces group_by's allowed values. However, the optional project and billable parameters have no descriptions in the schema or the tool description, so those remain underspecified.

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 and resource: totals for a date range, grouped by category/project/month/merchant. It also differentiates from bank-statement totals, so an agent can tell it apart from related tools without opening the schema.

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

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

It explicitly scopes the tool to receipts and names the alternative for bank transactions (statement_summary). It does not spell out when to prefer expense_list or expense_export, but the summary-vs-list distinction is reasonably clear from 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?

The description claims 'Read-only: nothing is marked rebilled here,' but the annotations declare readOnlyHint=false, which signals the tool may modify state. This is a direct contradiction between the natural-language behavior and the structured hint, so the tool's behavioral claims cannot be trusted.

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, both substantive: the first states the operation and output shape, the second states the key state-change guarantee. No filler, no restating of the title, and the most important information is front-loaded.

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

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

The description gives the return shape and grouping, and the parameter schema covers many edge cases, but this is a complex 8-parameter tool with no output schema and no explicit guidance on multi-currency ranges or next steps. The contradiction between the read-only claim and the annotations also makes the overview less dependable.

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

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

Schema description coverage is 100%, and each parameter already has a rich individual description. The top-level description adds no parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description names a specific verb ('Preview') and a precise resource ('unbilled billable expenses of one project'), and it specifies the output shape ('invoice_create line items ... grouped per currency'). This clearly distinguishes the tool from siblings like expense_mark_rebilled and expense_list.

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 this is for previewing and that nothing is marked rebilled, suggesting the actual marking happens elsewhere, but it never explicitly names a sibling like expense_mark_rebilled or states when not to use this tool. The usage context is present, but the guidance is left mostly to inference.

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

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

The description adds meaningful behavioral context beyond the annotations: partial-update semantics, amount unit convention ('MAJOR units'), and the rebilled-expense restriction tied to unlink_rebill. These are non-obvious behaviors that an agent needs to know. No contradiction with the readOnlyHint=false annotation exists.

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: the core operation is stated first, followed by the two most important caveats. Every sentence adds value, and there is no redundant or filler content.

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

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

Given 12 parameters and no output schema, the description covers the most critical operational details but leaves gaps. It does not explain the response format, error behavior, or several parameter formats. The rebilled logic is well covered, but the overall context is not fully complete for a complex update 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 only 25%, so the description carries most of the burden for parameter meaning. It clarifies amount units and explains the relationship between rebilled, unlink_rebill, and editable fields, but it does not clarify date format, note semantics, project, category, merchant, currency, billable, or vat_rate meaning beyond schema types.

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 operation: 'Change one expense by id', identifying the exact resource and scope. It also distinguishes this from sibling tools by emphasizing partial updates ('only the fields you pass move'), which separates it from expense_add, expense_delete, and expense_list.

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 it: when an existing expense needs to be changed. It also provides a specific conditional guideline about rebilled expenses, explaining when amount, currency, or vat_rate edits are refused. However, it does not explicitly contrast this tool with alternatives like expense_add or expense_delete, so usage guidance is only partially explicit.

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

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

Annotations already indicate this is not read-only and not destructive, and the description adds useful behavioral detail: existing data under the token stays, and a wrong or expired key changes nothing. This goes beyond the annotation hints by explaining failure semantics and safety of the operation.

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

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

The description is two sentences with no filler. It front-loads the core action, then gives the key format and safety guarantees, and closes with the verification tool. Every sentence contributes essential information.

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

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

For a single-parameter activation tool with annotations covering the safety profile, the description is complete: it states what the tool does, what input is needed, what happens on failure, and how to confirm success. There is no missing critical information 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?

The schema already documents the key parameter and its format with 100% coverage. The description adds meaning by specifying that the key must be issued at checkout for this server or the bundle, which clarifies validity requirements not present in the schema.

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

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

The description uses a specific verb and resource: it 'turns Pro on' for the connection using a license key. It also distinguishes itself from the sibling license_status tool by saying license_status confirms the activation. This leaves no ambiguity about what the tool accomplishes.

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

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

The description provides clear context for use: the key must be an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. It does not explicitly list exclusions or alternative tools, but it does reference license_status as the confirmation path, giving the agent a sense of the workflow.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context beyond annotations by specifying the JSON response contents and stating 'nothing changes,' reinforcing the read-only nature of the call.

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 dense sentences cover output, purpose, usage context, and side-effect guarantee. Every sentence earns its place and the most important information is front-loaded.

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

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

With no output schema, the description sufficiently describes the return value. With no parameters, annotations covering safety, and a clear use case, nothing essential is missing for an agent to invoke 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?

There are zero parameters and the schema already fully documents that fact. The description explicitly says 'No arguments,' which is accurate and reinforces the schema without needing further elaboration.

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 ('Report') and a precise resource ('this endpoint's licence state for your token'), and enumerates the exact output fields: product, tier, reason, and checkout URL. This clearly distinguishes it from sibling tools like license_activate.

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

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

The description explicitly states when to call it: 'Call it to explain a free-tier refusal.' This is clear contextual guidance, though it does not name alternatives or explicitly state when not to use it.

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

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

With all annotations at false/default values, the description carries the behavioral burden and delivers: it discloses the return shape ('saved id with the rate used, where that rate came from and the money'), the currency behavior ('in the rate's own currency'), and the exclusivity constraint. It does not contradict the annotations — a record-creating write aligns with readOnlyHint=false.

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 short sentences, each earning its place: the purpose, the critical exclusivity constraint, and the return-value contract. The most important information is front-loaded in the first sentence, with zero filler or repetition of schema boilerplate.

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

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

There is no output schema, so the description's return-value disclosure (id, rate, rate source, currency) fills a real gap. The schema covers all parameter semantics, defaults, and the tax caveat, so together the package is complete for a 9-parameter tool. Minor omission: the description doesn't note that missing 'project' hides the claim from expense_summary/expense_to_invoice, though the schema's project field does.

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

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

Schema description coverage is 100%, so every one of the 9 parameters is individually documented in the schema, which establishes the baseline of 3. The description adds the high-level pricing context and the km/miles exclusivity, but that constraint is already repeated in both parameter descriptions, so the description contributes no additional parameter-level 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 opens with a specific verb and resource ('Record a business trip as an expense') and adds the pricing mechanism ('priced as distance x rate'), which clearly distinguishes it from the sibling expense_add for general expenses. The mutual-exclusivity constraint ('Give exactly one of km or miles') further sharpens the 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 implied rather than stated: the 'business trip' framing suggests this tool is for mileage claims versus expense_add for other expenses, but the description never names an alternative or gives an explicit when-to-use/when-not-to-use rule. The useful exclusion ('NOT a tax calculation') lives in the schema's region parameter, not in the description.

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?

All annotations are false, so the description carries the behavioral burden. It does add valuable traits: the tool requires a filesystem, is unusable on hosted endpoints, and reads/hashes a receipt file. However, it does not disclose side effects such as whether an existing receipt is replaced, or what the return/result looks like. There is no contradiction with the annotations.

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

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

The description is front-loaded with the critical limitation, then gives actionable installation instructions and a fallback. It is longer than a typical tool description due to the URL and steps, but every sentence serves a practical purpose. No fluff.

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

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

For a simple two-parameter tool with a fully documented schema, the description supplies necessary environment context: local-only availability and the filesystem requirement. It also provides a workaround for hosted users. It could be more complete with an explicit statement of the operation and its effect on the expense record, but an agent has enough to decide whether and how to call it.

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 both id and path fully documented in the input schema. The tool description adds no parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The title 'Attach a receipt' conveys the action, but the description leads with an availability warning and never explicitly defines the core function such as 'attaches a receipt file to an expense.' The schema clarifies the attachment target, but the description alone is more about when the tool cannot be used than what it actually does. It also does not distinguish the operation from sibling tools like expense_update.

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

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

The description explicitly states when the tool cannot be used ('Not available on the hosted endpoint'), provides a concrete alternative path (local install with a download URL and instructions), and offers a non-tool fallback ('record the receipt reference in the expense note'). This is strong when/when-not guidance, though it does not mention sibling tools by name.

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