vokse

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

The description discloses the asynchronous behavior and the polling endpoint, which go beyond the readOnlyHint/destructiveHint annotations. It does not mention export expiration or limits, but the annotations already cover the safety profile, and no contradiction with them is evident.

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-loads the core behavior and output, and wastes no words. The alternative tool reference is placed at the end without diluting the main message.

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

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

Despite having no output schema, the description tells the agent exactly what to expect (exportId), what to do next (poll GET /reports/exports/:id), and when to choose a sibling tool. Combined with the fully described parameters and annotations, this 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 coverage is 100%, so the input schema already documents all six parameters in detail. The description adds minimal extra parameter meaning beyond naming the file formats, which are already enumerated 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 names a specific action ('Enqueue an async downloadable export'), a clear resource (a vokse report), the supported formats (csv, pdf, xlsx), and the key output (exportId). It also differentiates the tool from the sibling generate_report by pointing out the inline-data alternative.

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

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

It explicitly explains when to use this tool: when an async downloadable export file is needed, and explicitly directs the caller to generate_report for inline data. It also describes the follow-up polling flow, so the agent knows the operational 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 declare readOnlyHint=true and destructiveHint=false, so the tool is known to be safe. The description adds useful behavioral context beyond that: it computes a 6-month EMA baseline, overlays recurrences, and conditionally runs an LLM-adjusted refinement when refine=true. It stops short of describing output shape or cost/latency implications, so it is not a 5.

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

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

Two compact sentences with no filler. The core action is front-loaded, followed by the return composition and the refine guardrail. 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 read-only forecast tool with no output schema, the description explains what the response contains and the two modes of operation. The main gaps are the unspecified output format/currency and lack of explicit sibling routing, but the schema covers parameters and annotations cover safety, so it is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value for refine by stating its default and the explicit-user-request condition, which is not fully captured by the schema alone. yearMonth and householdId rely on their schema descriptions, which are already adequate.

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: 'Produce a per-category spend projection for :yearMonth.' It also specifies the output composition (EMA baseline + recurrence overlay + optional LLM refinement), which clearly distinguishes it from generic siblings like generate_report and list_insights.

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 a monthly per-category spending projection is needed. It also gives a clear conditional rule for refine ('only enable when the user explicitly asks for explanations'), but it does not explicitly state when to prefer this tool over alternatives or 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?

Annotations already mark the tool read-only and non-destructive, so the safety profile is covered. The description adds useful behavioral context by stating that the result is live JSON returned inline, which helps an agent understand the response and that no file is produced. It stops short of describing response shape or potential performance characteristics, but this is not a major gap.

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

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

Two short sentences with no filler. The core purpose and output format are front-loaded, and the sibling alternative is stated efficiently. 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?

The tool has seven parameters and nine report variants, but the schema covers all parameters thoroughly. The description clearly distinguishes this tool from export_report and states the output mode. It could be slightly more explicit about what the JSON return contains for different report kinds, but given the schema's richness, this is a minor omission.

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

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

Input schema coverage is 100%, with each parameter already having a descriptive comment and constraints. The description only mentions a 'date range' generically and does not add extra meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Produce') and resource ('vokse report'), and immediately clarifies the output form ('return the live JSON inline'). It distinguishes this tool from the sibling export_report by explicitly naming that alternative, so there is no ambiguity about which tool to choose.

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 direct selection guidance: use this when you want a report as inline JSON, and use export_report when you need a downloadable file. This explicit when/when-not/alternative is exactly what an agent needs 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, indicating a safe read operation. The description adds the return fields, which is useful context, but it does not disclose any other behavioral aspects like error handling, permissions, or rate limits. This is consistent with annotations, and the description adds moderate value beyond the structured hints.

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 a single sentence that is concise and front-loaded with the primary action. It contains no superfluous content and communicates the purpose and output efficiently.

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 fetch-by-ID tool with read-only annotations and a fully described schema, the description covers the purpose and output fields, which is sufficient. It could mention error behavior (e.g., what happens if the account is not found), but that is not critical for a read operation and the schema already covers parameter requirements.

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

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

The schema provides 100% coverage of both parameters, with descriptions for accountId (from list_accounts) and householdId (with conditions for omission). The description text adds no additional parameter semantics, so the baseline of 3 applies because the schema already documents the parameters adequately.

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 financial account by ULID, with a specific verb ('Fetch') and resource ('financial account'), and lists the returned fields (name, type, currency, balance, status). This distinguishes it from list_accounts and other getters like get_budget or get_payee, which operate on different resources.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention that list_accounts should be called first or that this tool is for retrieving a specific account after listing. The only hint comes from the schema's accountId description ('from list_accounts'), which is not part of the description text.

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 the operation read-only and non-destructive; the description adds useful behavioral details beyond that, such as returning a full snapshot, including categoryName/groupName per row, and instructing the agent to use those names and never show raw ids. It does not discuss auth, limits, or empty-month behavior, but the annotation coverage lowers the burden.

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 a single dense sentence that front-loads the core purpose and packs the output structure into parenthetical dashes. It is efficient, though the run-on structure could be slightly easier to parse.

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 carries the burden of explaining the return shape, and it covers the main components (per-category fields, ABT, totals) plus the naming rule. It omits details like totals aggregation or multi-household behavior, but those are either implied or handled by the schema.

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

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

Schema description coverage is 100%, so the schema fully documents yearMonth and householdId. The description repeats the YYYY-MM format for yearMonth but adds no new semantics for either parameter, keeping this at 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 specific operation (Get full budget snapshot) on a specific resource (monthly budget) and enumerates the returned components: per-category assigned/activity/carryover/available, ABT, and totals. It clearly positions this as the 'where is my money?' tool, which separates it from the transaction/account listing siblings.

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

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

It explicitly says to use this for any 'where is my money?' question, giving a clear triggering context. It does not, however, name alternatives or state when not to use it, so it stops short of full exclusion guidance.

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

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

The annotations already signal read-only and non-destructive behavior, and the description's 'Fetch' wording aligns with that. It adds the returned field set, but it does not disclose details like missing-payee behavior or household-scoping constraints, which is acceptable given the simple read-only nature.

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: what the tool fetches, what it returns, and when to use it. The description is front-loaded and contains no filler or redundant schema repetition.

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

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

The tool is a simple getter with fully documented parameters and read-only annotations. The description covers the input source, the singular scope, and the return fields, so no information needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, with both payeeId and householdId already explained clearly in the schema. The description adds that payeeId is a ULID and that the tool resolves one payee to its name, but does not need to compensate for schema gaps.

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

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

The description states a clear verb and resource: 'Fetch a single payee by its ULID.' It also names the returned fields, which distinguishes it from list_payees and the other get_* siblings.

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

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

The last sentence gives a clear intended use case: 'Use to resolve one payeeId to its name.' It does not explicitly point to list_payees as the alternative for fetching many payees, but the singular context is clear enough.

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

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

Annotations already mark this as read-only and non-destructive. The description adds meaningful behavioral context beyond those annotations: 'You never see the image, only what was read from it,' clarifying the tool returns extracted data, not the raw photo. It also discloses output conventions such as integer cents and per-base-unit unit prices.

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 a single dense, well-structured sentence that front-loads the main idea and then lists the returned components efficiently. There is no filler, repetition, or unnecessary phrasing; all details are relevant to a tool with no output schema.

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

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

Because there is no output schema, the description carries the full burden of explaining return shape, and it does so comprehensively: merchant, date, totals, payment method, tags, summary, and line items with quantity, unit, unit price, and line total. Required parameter provenance is already covered by the schema, 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?

Schema description coverage is 100%, so receiptId and householdId are already fully documented in the schema. The description adds no parameter-specific guidance beyond contextualizing the output, which is acceptable but not extra value beyond the schema.

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

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

The description uses a specific verb-plus-resource framing: 'Everything read from one receipt photo' and enumerates exact returned fields (merchant, date, totals, payment method, tags, summary, line items). The emphasis on 'everything' and individual line items clearly distinguishes it from summary/search receipt siblings.

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

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

The description implies this tool is for retrieving full parsed details for a single receipt, especially compared with summarize_receipt_items or search_receipt_items, but it never explicitly states when to use this tool versus alternatives. No exclusions or when-not-to-use guidance is provided.

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 the response includes splits and tag ids, which is useful behavioral context beyond the schema. However, it does not disclose other behaviors like whether the transaction is returned with all fields, or any error conditions (e.g., not found). With annotations covering safety, a 3 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?

A single sentence that is front-loaded with the action and resource, and includes the key detail about splits and tag ids. 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?

For a simple read tool with annotations covering safety and a schema covering parameters, the description is complete enough. The only minor gap is that it doesn't mention what happens if the transaction is not found, but that is not critical for 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 description coverage is 100%, so the schema already documents both parameters. The description adds that transactionId is a ULID and that the result includes splits and tag ids, but it doesn't add meaning beyond the schema's parameter descriptions. Baseline 3 is correct when schema does the heavy lifting.

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 ('Fetch'), a specific resource ('a single transaction'), and the key identifier ('by its ULID'). It also mentions the inclusion of splits and tag ids, which distinguishes it from a generic get_transaction. Among siblings like get_account, get_budget, get_payee, this clearly identifies its target resource.

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 tool is for fetching a single transaction, which is clear context. It does not explicitly state when not to use it or name alternatives like list_transactions for multiple transactions, but the singular 'a single transaction' provides enough guidance for an agent to select it appropriately.

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 value by disclosing that the response includes current balances and that amounts are in the account currency, plus the household scope, which helps an agent anticipate the tool's output.

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

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

A single sentence that leads with the action and resource, immediately conveys scope and included data, and contains no filler. 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?

With 2 simple params and no output schema, the description sufficiently communicates the primary behavior and key return content (balances with currency). Minor gaps like default status filtering or response shape are already inferable from the schema and tool name, so the description is near-complete for a 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 description coverage is 100%, so both parameters are already documented in the input schema. The description reinforces the household scope but adds no new parameter-level semantics beyond what the schema provides; baseline 3 applies.

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

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

The description states a specific action (list), resource (all financial accounts), and scope (in the household), with concrete examples of account types. It clearly differentiates itself from the singular get_account sibling by emphasizing 'list all' and the plural resource.

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 usage for retrieving all accounts but does not explicitly mention when to prefer this over get_account or other list tools. No exclusions or alternative routing are provided, leaving the agent to infer the tool's role from its name and phrasing.

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 does not need to repeat that. It adds the return structure (groups with categories and their fields) and clarifies the includeHidden default, which is valuable 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 a single, dense sentence that front-loads the core action and then provides the return structure and usage hint. Every phrase earns its place, with 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 read-only list tool with no output schema, the description fully covers what is returned, when to use it, and the parameter default. Combined with the annotations, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description repeats the includeHidden default and the householdId omission condition from the schema, adding no new parameter-level meaning. 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 lists the household category tree and specifies the exact fields returned for groups and categories. It distinguishes itself from sibling list tools by naming the concrete resource and its hierarchical structure, leaving no ambiguity about what it does.

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

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

It explicitly says to call it before creating, renaming, or budgeting to reuse existing names and ids, which gives clear when-to-use context. It does not explicitly name alternatives or exclusions, but for a read-only listing tool this is sufficient 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, covering the safety profile. The description adds value by specifying the complete output shape (fields and kinds), which is beyond what annotations provide. It does not contradict 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 two concise sentences, front-loaded with the core purpose and immediately followed by the exact output fields and allowed kinds. 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?

For a simple list tool with one optional parameter, no output schema, and no nested objects, the description is fully complete. It states the scope (every goal in the household), the returned fields, and the kinds, leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, and the sole parameter householdId is fully documented in the schema. The description adds no parameter-specific meaning, which is acceptable given the high schema coverage, earning a baseline 3.

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

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

The description clearly states the tool lists every category goal, enumerates the exact fields returned (kind, targetCents, byDate, notes, category name), and lists the allowed kinds. This is a specific verb+resource with enough detail to distinguish it from sibling list_* tools, even without naming them.

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

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

The description implies when to use it (when you need all goals in a household) but does not explicitly state when not to use it or mention alternatives. There is no guidance on choosing this over other list tools, though given the simple read-only nature, this is a minor 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 signal readOnlyHint=true and destructiveHint=false, so the description needs to add context beyond those. It does: the response includes the caller's role and access level, and the tool is positioned as a prerequisite/discovery step. It does not mention pagination or response shape, but for a zero-parameter read-only list that is acceptable.

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 with no wasted words. The first sentence states the core function, and the second delivers the usage instruction. The structure fronts the purpose and keeps the guidance immediately actionable.

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 parameters, annotations covering the safety profile, and a description that explains both the output contents and the intended calling order, everything an agent needs to invoke this tool correctly is present. The lack of an output schema is mitigated by the explicit mention of households and role/access level.

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 zero parameters, so there are no parameter semantics to explain. Per the baseline for 0 parameters, this scores 4. The description sensibly focuses on output and usage rather than inventing parameter details.

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

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

The description states a specific action ('List') and a specific resource ('households this connection covers'), and adds detail about the output ('with your role and the access level'). It clearly differentiates this tool from all sibling list tools, none of which focus on households. The 'Call this first' clause further underscores its unique role.

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

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

The description gives an explicit, actionable condition: 'Call this first when a tool needs a householdId.' This is a clear decision rule for when to use the tool, and implicitly says when not to use it (when no householdId is needed). No alternatives are relevant, so this guidance is sufficient.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral details beyond annotations: it returns newest-first, defaults to undismissed, and returns a paginated structure with nextCursor. This enriches the agent's understanding of what to expect without contradicting 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 two sentences with zero fluff. The first sentence states the primary action and filters; the second covers defaults and pagination. It is front-loaded with the core purpose and immediately gives the agent the essential call pattern. 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?

The tool has no output schema, but the description explicitly states the return shape (paginated items + nextCursor) and how to use it. It covers the key behavioral aspects (default filter, ordering, pagination) and the householdId context is in the schema. For a read-only listing tool with annotations covering safety, this 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 coverage is 100% with each parameter already described. The description adds value by clarifying the kind enum values inline (though they are in schema) and explaining the pagination flow (pass nextCursor back as cursor). It reinforces parameter usage without redundancy, and the cursor semantics are clarified beyond the schema's brief description. This is a solid compensation given the high 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 states a specific verb ('List') and resource ('household's AI-generated insights') with a clear ordering constraint ('newest first'). It also enumerates the filter dimensions (kind, periodStart) and pagination, distinguishing it from other list_* siblings that target different entity types. The purpose is unambiguous and actionable.

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 explains when to use the tool for listing insights, notes the default filter (undismissed), and describes how to paginate via cursor. It does not explicitly name alternative tools or conditions that would select a different sibling, but the context is clear enough for an agent to decide. The householdId guidance is also present in the schema, so the description adds moderate usage direction.

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 context about membership roles and access control, which is useful, but it does not disclose any additional behavioral traits like pagination, ordering, or what happens when householdId is omitted. With annotations carrying the safety burden, a 3 is fair.

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 core purpose (who and with which role), the second gives the usage context. No filler, front-loaded with the primary function, and every word adds 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 simple read-only list tool with one optional parameter and no output schema, the description is adequately complete. It explains what it returns (members with roles) and when to use it. It does not describe the exact output format, but that is not required for this simplicity level. The only minor gap is not stating that the output is a list of members with role fields, but the description implies 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% for the single parameter, with a clear description of householdId and its behavior when omitted. The tool description does not add any extra parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states the tool lists household members with their roles (owner, editor, viewer), which is a specific verb+resource. It also adds a use-case ('who can see or change their money') that distinguishes it from other list_* tools that list different entities. It is immediately clear what this tool does and what it is not.

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 a clear trigger: 'Useful when the user asks who can see or change their money.' This tells the agent when to reach for this tool. It does not explicitly exclude alternatives or name a sibling to compare against, but the use-case context is specific enough 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 mark it read-only and non-destructive; the description adds that the operation returns all payees as an array with specific fields, and provides useful domain context about transactions referencing payees by id. No contradictions.

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: core listing statement, use-case guidance, and return type. Front-loaded, no filler, each sentence adds a distinct piece of actionable 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 one-optional-parameter read-only list tool with no output schema, the description covers scope, output fields, return type, and practical use. 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 single householdId parameter is fully documented in the input schema (coverage 100%), including the omission rule. The description only refers to 'the household' and adds no new parameter-level meaning, so baseline 3 applies.

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

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

States a specific verb ('List'), resource ('payees'), and the exact fields returned (id, name, default category id). The word 'every' sets the all-items scope and distinguishes it from get_payee, a sibling that retrieves a single payee.

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 names two use cases: resolving payeeId to a human-readable name and browsing the payee directory. It gives clear context but does not name alternatives (e.g., get_payee) or state when not to use it, so not a full 5.

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

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

The annotations already cover readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It adds meaningful behavioral context beyond those: the merge is newest-first, status values carry lifecycle meaning (pending/processing still being read, failed could not be read), and inboxOnly returns the tray. There is no contradiction with annotations.

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

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

The description is five sentences long and each sentence earns its place: overview, inboxOnly explanation, status semantics, pointer to get_receipt, and lifecycle caveat. It front-loads the core purpose first and avoids filler—a compact but high-density description.

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

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

Every part an agent needs to use the tool correctly is present: return envelope, ordering, filter meanings, and the standard get_receipt pointer for deeper detail. Although it has 10 optional parameters and no output schema, the schema documents each parameter fully and the description covers the output fields and ordering, so nothing crucial 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 every parameter already has its semantics defined. The description reinforces q, status, and inboxOnly in slightly plainer language, but it does not go materially beyond the schema (newest-first ordering is not a parameter behavior). Baseline 3 is therefore appropriate because the schema carries the explanatory weight.

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 clear verb and resource: 'List receipt photos the household uploaded, newest first,' and enumerates the exact fields returned (merchant, date, total, tags, summary, item count, status). It also distinguishes itself from the sibling get_receipt by noting full line items are elsewhere, so an agent can tell the two apart immediately.

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 the main use case (listing uploaded receipt photos with extracted data) and gives an alternative invocation: 'Use get_receipt for the full line items.' It also explains when the inboxOnly filter is relevant (photos not yet linked to a transaction) and how status and q operate, so no practical ambiguity remains about which tool to choose.

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

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

Annotations already mark the tool as read-only and non-destructive, and the description adds substantial behavioral detail beyond that: newest-first ordering, attribution of who made each change, whether it can be undone, and the fact that undo/redo reversals themselves appear unless includeReversals is false. This meaningfully expands what an agent knows before calling.

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

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

The description is dense but efficient: it front-loads the core operation, then covers scope, ordering, actor/undoability, follow-up usage, and the reversal caveat in two sentences. Every clause earns its place and there is no filler.

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

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

With no output schema, the description carries the burden of explaining return value semantics, and it covers the essential items: ordered entries, actor, undoability, an id for undo/redo, and reversal inclusion. All 8 optional parameters are already fully documented in the schema, so nothing an agent needs to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3 even without description-level parameter detail. The description adds value by linking the returned id to undo_change/redo_change and by giving concrete meaning to includeReversals ('Reversals are listed too unless includeReversals is false'), which goes slightly beyond the schema's bare boolean definition.

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 recent changes to the household') and immediately disambiguates what counts as a change: budget assignments, transaction edits, and category/account/payee/goal/rule/recurrence/tag changes. This clearly sets it apart from sibling state-returning tools like list_transactions or list_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?

The description clearly conveys that this is the change-history / Recent Moves view and explicitly tells the agent to use the returned id with undo_change / redo_change. It does not name alternatives or state when not to use it, but the context is clear enough for an agent to select it 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 establish readOnlyHint and non-destructive behavior. The description adds genuine behavioral context beyond annotations: it enumerates the return columns, lists possible status values (active, paused, archived), and discloses the sort order ('Soonest first'). It stops short of covering pagination or matching quirks, but the main behavior is transparent.

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?

A single, tightly packed sentence front-loads the verb and resource, then efficiently lists fields, statuses, and ordering. There is no filler or repetition of the title.

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

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

For a simple read-only list tool with one well-documented optional parameter and no output schema, the description covers what the agent needs: returned fields, status vocabulary, and result ordering. The safety profile is already carried by annotations, 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?

There is only one parameter, householdId, and the schema already describes it fully, including the special case where it may be omitted. The description does not add anything about parameters, which is acceptable given 100% schema coverage — the baseline of 3 applies.

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

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

The description clearly identifies the resource ('recurring transactions') and specifies the returned fields: name, amount, frequency, next run date, and status. It also gives concrete examples (subscriptions, rent, salary), making the tool's purpose unambiguous and distinct from plain list_transactions.

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 usage for recurring vs. one-off transactions through examples and the resource name, but it never states when to choose this over siblings like list_transactions or list_recurrence_suggestions, nor does it mention any exclusions or alternatives.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile (no mutation). The description adds behavioral context beyond annotations by specifying that each suggestion carries a stable key, payee, amount, cadence, confidence, and charges behind it, giving the agent a sense of what to expect. However, it does not disclose any edge cases, limits, or return behavior (e.g., if no suggestions are found), but given the strong annotation coverage, this is acceptable.

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

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

The description is two sentences long, with the first sentence front-loading the core purpose and key types of suggestions, and the second sentence listing the important fields without excessive detail. It is concise and focused, though it could arguably be split into a more digestible structure, but it is neither verbose nor wasteful. The purpose is stated upfront, with the next step mentioned at the end.

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 the tool is a read-only list with a single optional parameter, the description is complete: it clarifies the two kinds of suggestions, the fields available on each, and offers the next step (accept_recurrence_suggestion). The absence of an output schema is compensated by listing the fields. There is no missing information that an agent would need to call it correctly, aside from perhaps what happens when there are no suggestions, which is minor.

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

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

The schema already has 100% coverage, with a description for the only parameter (householdId) that explains its purpose and optionality. The description adds no additional parameter information beyond what's in the schema)Skip; it does not clarify anything about householdId beyond Schema. Since schema covers the parameter fully, a score of 3 (baseline) 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 specifies a precise verb ('List'), a clear resource ('recurring charges detected in household activity'), and scopes the types of charges (un-scheduled 'new' kinds and 'price_change' recurrences). This clearly distinguishes it from the sibling tool list_recurrences, which likely lists scheduled recurrences. The description immediately conveys what the tool does and its 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?

The description states the tool lists detected recurring charges and mentions that the listed items are those that are 'not scheduled yet' and those with price changes, which implies it should be used when you need to review detected suggestions before scheduling. It does not explicitly state when not to use it or name alternatives, but the reference to using accept_recurrence_suggestion for scheduling provides a clear next step, and the scope of 'detected' charges is implicit guidance. Could benefit from explicit exclusion of already-scheduled recurrences, but the context is mostly 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 disclose readOnlyHint=true and destructiveHint=false, so the read-only nature is established. The description adds useful behavioral context by specifying result contents ('conditions and action') and ordering ('newest priority first'), which goes beyond the structured annotations.

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

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

Two sentences, no filler. The first sentence states the operation and key output traits, and the second gives concrete use cases. 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?

The description provides the core output expectations and ordering, and the input schema covers the parameters thoroughly. Since there is no output schema, a little more detail about the returned rule shape could help, but the description is sufficient for correct invocation.

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

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

Schema description coverage is 100% for both parameters, including the householdId guidance to call list_households. The tool description does not add parameter-level detail, but the schema fully covers it, 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?

States a specific verb and resource: 'List the household automation rules with their conditions and action.' It also adds a sort-order detail, 'newest priority first,' which distinguishes it from generic listing tools and clarifies what the result contains. Sibling tools like preview_rule or list_transactions are clearly different in 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?

Provides explicit usage contexts: 'before answering "what rules do I have" or before creating one that may already exist.' This clearly signals when the tool should be used, though it does not discuss exclusions or compare directly to sibling alternatives beyond those use cases.

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 ('List every tag') is consistent with those. The description adds the output fields but no additional behavioral context (e.g., pagination, rate limits, or side effects). Since annotations cover the safety profile, the added value is modest, warranting a 3.

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

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

Two sentences with no wasted words: the first states purpose and output, the second gives usage guidance. Front-loaded and efficient, 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?

Despite no output schema, the description explicitly lists the returned fields (id, name, color), which is essential. It also provides usage context for the ids. The only parameter is well-documented, and annotations cover safety. The description is complete for a simple list tool, with only minor gaps like pagination or limits, which are not critical here.

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 description coverage is 100% and the householdId parameter is fully documented there. The tool description does not add any meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('List'), resource ('tags'), scope ('household'), and output fields ('id, name, color'). This clearly distinguishes it from sibling list tools like list_categories or list_payees, and gives the agent enough to know exactly what it returns.

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 usage directive: 'Use the ids with update_transaction {patch: {tagIds}} or list_transactions {tagIds}.' This tells the agent when to use the tool and how to apply its output. It does not mention alternatives or when not to use it, but the context is clear enough for a simple list operation.

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 valuable behavioral context by explaining that the name field may be renamed by the household (when isDefaultName is false) and that a keyboard shortcut is included, which goes beyond the annotations and helps the agent understand the data semantics.

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: the first front-loads the core function and fields, the second provides downstream usage. It is efficient and without wasted words, though the first sentence is somewhat long and could be split, but remains clear and appropriately scoped.

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 is a simple list operation with no output schema, the description fully enumerates the return fields, notes the six built-in colors, and explains how to use the results in other tools. No pagination or error handling is needed for a fixed set of flags, so the description is complete enough for an agent to call and interpret results.

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

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

The only parameter, householdId, is fully documented in the input schema with details about its format and usage (calling list_households, optionality). The description adds no additional parameter-specific information, so the schema already covers 100% of the semantics. 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 lists household colour flags, enumerates the six built-in colors, and specifies the exact fields returned (id, systemKey, name, colour, keyboard shortcut). It distinguishes itself from sibling tools by being the only flag-listing operation, and the downstream usage reference reinforces its purpose.

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

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

The description explicitly explains how to use the returned ids with list_transactions and update_transaction, including the alternative flag: parameter for update_transaction. This provides clear context for when to use this tool and how its output feeds other operations, though it does not explicitly state exclusions or alternatives because there are none.

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/destructiveHint annotations, the description discloses rich behavior: newest-first ordering, pagination mechanics, conditional field presence in compact rows, the exact semantics of uncategorized (excluding transfer legs, system rows, split parents), and the relationship between needsReview and uncategorized. It even warns that re-fetching a page for full fields is never necessary.

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 well-structured: purpose first, then filters, then pagination, then return-row semantics. Every section adds value, though the filter enumeration partially duplicates what the schema already documents. It is long but earns its length by clarifying relationships the schema cannot express.

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 19 parameters, no output schema, and no required fields, the description carries a heavy burden. It covers return format (compact vs full), conditional fields, pagination semantics, filter semantics for the trickiest parameters, and the distinction between uncategorized and needsReview. An agent can invoke this tool correctly without needing external information.

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 meaningful nuance beyond the schema: it explains uncategorized semantics in detail, clarifies that flagIds come from list_transaction_flags, specifies that search covers memo, payee names and aliases, and receipt text, and distinguishes needsReview as a small subset of uncategorized.

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 transactions, newest first.' It further clarifies scope by enumerating the many filter dimensions (accountId, categoryId, payeeId, date range, search, flags, etc.), which clearly distinguishes it from sibling tools like get_transaction (single transaction) and search (cross-entity search).

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

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

The description gives clear operational context: pagination with nextCursor, limit up to 100, compact vs full field selection, and explicit guidance on when to use uncategorized:true versus needsReview. It does not explicitly name sibling alternatives like search or get_transaction, so it stops short of full when/when-not guidance, but the context is sufficiently 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?

The description discloses behaviors beyond the annotations: null or zero fields are omitted, isTransfer marks never-categorised payees, looksLike fixed rules win over history, and cash_withdrawal payees trigger additional fields plus a literal cashRule. The readOnlyHint already covers safety, and the description adds rich operational detail without contradicting it.

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

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

The description is long but dense and well-organized; every clause introduces a distinct behavioral fact or filter. It front-loads the core purpose and then layers edge cases and usage guidance 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?

With no output schema, the description fully covers the return shape, edge cases, filter semantics, and the relationship to a sibling tool. An agent has enough information to select the tool 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 description coverage is 100%, so the baseline is 3. The description adds useful semantic context for onlyWithUncategorised as the working set of a categorising turn and notes the payeeIds bound, but the schema already documents the parameters well.

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

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

The description states a specific verb and resource: it provides per-payee category evidence in one call and enumerates the exact fields returned. It also distinguishes itself from sibling list_transactions by explicitly saying it replaces the same-payee history lookup for every payee at once.

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

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

It gives explicit usage context: use it for categorising instead of calling list_transactions per payee. It also clarifies when filters apply, such as onlyWithUncategorised for a categorising turn's working set and payeeIds up to 200.

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 and destructiveHint false, and the description reinforces that with 'without changing anything.' It goes beyond annotations by scoping to 'existing transactions' and by disclosing an output behavior ('how many rows are affected'), which is useful for an agent deciding whether to present this as a dry-run.

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-load the core purpose and behavior first, then give usage context. There is no filler, and the structure mirrors the natural scan path for an agent evaluating the tool.

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

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

For a simple read-only tool with two parameters, the description plus detailed schema covers what the tool does and when to use it. Minor gaps remain around the exact return shape and the unlisted apply_rule dependency, but neither blocks 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 100%, with ruleId and householdId already well-documented including source hints ('from list_rules') and an omission condition. The description itself adds no parameter-level detail, so the baseline of 3 applies because the schema does the heavy lifting.

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 ('which existing transactions a rule would touch') and immediately distinguishes itself from an apply operation by adding 'without changing anything.' This cleanly separates it from list_transactions and any rule-modification action.

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: 'check a rule before apply_rule' and 'tell the user how many rows are affected.' However, it does not give when-not guidance or explicitly name alternatives among the listed siblings, and the referenced apply_rule is not present in the sibling-tool list, leaving a minor route-selection 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 mark this as read-only and non-destructive. The description adds meaningful behavior context: quantity-weighted averaging, min/max per base unit, merchant inclusion, bucket comparison, and the insufficient-history fallback. 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 three sentences with the core purpose front-loaded)Skip. Every sentence adds distinct value: the behavior summary, the example question, and the output-handling instruction. There is no filler or duplication of schema content.

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

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

With no output schema, the description carries the burden of explaining return semantics, and it does so well: average/min/max per base unit, merchants, bucket comparisons, and the few-buckets fallback. Combined with complete schema parameter notes, an agent has enough to call and interpret 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?

The input schema covers all six parameters with descriptions, so the baseline is 3. The description repeats the month/week default and gives a product example, but does not materially clarify date, merchant, or householdId semantics beyond what the schema already states.

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 what the tool does: it shows how a product's unit price moved over time from receipt photos, with aggregation details. It specifies the resource (product price history) and distinguishes it from sibling receipt/search tools even without naming them.

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

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

The description gives a concrete question the tool answers ('how much has the price of apples gone up this year') and explains the bucket comparison behaviorhare. It does not explicitly contrast it with alternatives like search_receipt_items or summarize_receipt_items, so it falls short of full exclusion guidance.

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

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

Annotations already mark the tool read-only and non-destructive, so the description adds value by disclosing trigram-similarity ranking, receipt text matching for transactions, and the default behavior of searching all entity types when types is omitted. These behavioral details are not available in the annotations or schema.

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

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

The description is dense but every sentence earns its place: it defines scope, states exact type constraints, explains ranking and receipt matching, and gives a concrete duplicate-charge scenario. The guidance is front-loaded with the core function and then moves to practical usage, 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?

There is no output schema, so the description carries some burden for explaining what the result means; the trigram ranking and cross-entity matching hints at this well. It does not explicitly describe the returned item shape or how results are grouped, but for a search call the operational guidance 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?

Since schema coverage is 100%, the baseline is 3, and the description goes beyond it by explaining trigram-similarity ranking and receipt-based matching, which clarifies how q behaves. It also reinforces the types semantics by naming the accepted values and the default-all behavior, though the schema already enumerates them.

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: 'Cross-entity full-text search.' It clarifies the tool is broad and lists the exact entity types it covers, which separates it from sibling list and get tools. The closing phrase 'Use for "find anything mentioning X" queries' makes the purpose unmistakable.

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

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

It explicitly states when to use this tool, including a concrete duplicate-charge workflow that mentions combining specific types and comparing payee names, amounts, and dates. It also names alternatives like list_recurrences and list_recurrence_suggestions for the full schedule, giving the agent actionable routing guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value on top by describing that results are newest-first by default, what fields come back, and how q/merchant/date filters narrow the search. It doesn't contradict any annotation and gives behavioral detail beyond the schema.

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

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

The description is compact, front-loaded with the object type and output fields, then the filters, then the use case. It lists several output fields, but since no output schema exists, that enumeration earns its place. It is dense but 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 10 parameters, no output schema, and only read-only annotations, the description covers the core return shape and filter semantics. It doesn't explain cursor/pagination bounds in prose, but the schema already handles those descriptions, and the remaining context is adequate 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?

With 100% schema description coverage, the baseline is 3. The description adds extra semantics: q examples ('manzana', 'papel higiénico'), the meaning of merchant as narrowing to one shop, and the date bounds for purchase day. This enriches the parameter descriptions rather than merely repeating them.

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: search receipt line items, and it lists exactly what kind of data is returned (description, product name, brand, quantity, prices). It distinguishes itself from sibling tools like list_receipts or summarize_receipt_items by focusing on line-item search and filtering, and the use-case quote clarifies its place.

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 gives usage context: answer 'what did I pay for X on that receipt' or list what was bought somewhere. It does not name specific alternatives to avoid or provide a when-not clause, but the intended triggers are clear enough for an agent to select it appropriately.

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/destructiveHint annotations, the description explains the aggregation semantics in detail: quantity-weighted average, min, max, latest price per base unit, normalization to kg/l/unit, and inclusion of purchase locations. It also adds the critical output instruction to always state the unit when quoting a price. No behavioral surprises are hidden.

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 summary behavior, then efficiently demonstrates use cases with concrete query phrases. It includes no filler, and every sentence contributes either scope, calculation detail, or an invocation example.

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

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

For a tool with no output schema, the description compensates well by explaining what the response contains and even how to quote prices. It is largely complete given the rich parameter schema and annotations; the only minor gap is the lack of explicit differentiation from closely related sibling tools.

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

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

The input schema already documents all 7 parameters at 100% coverage, so the schema carries the main weight. The description adds useful context—such as combining merchant with sort=unitPrice for a 'most expensive at this shop' query—but it does not materially expand parameter-level semantics 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 starts with a specific verb and resource: 'Per-product summary across all receipt photos', then enumerates the exact metrics computed (frequency, total spent, quantity-weighted average/min/max/latest unit price, purchase locations). This clearly distinguishes it from listing or raw search tools.

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

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

It gives concrete example questions and maps them to sort and merchant values ('sort=unitPrice, merchant=...', 'sort=frequency'), which tells an agent how to invoke the tool for common intents. It does not, however, explicitly state when to avoid this tool in favor of siblings like search_receipt_items or receipt_item_price_history.

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