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

With readOnlyHint=true already covering safety, the description adds substantial behavioral context: default rows omit roughly 35 fields, hidden accounts are excluded unless include_hidden is set, name is user-editable and must not be used as a key, and include_logos was removed in v3.0.0 and now raises an error.

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 core purpose, filtering behavior, and default projection are front-loaded, and most detail is relevant. The long parenthetical inventory of excluded fields is informative but dense, making the description longer than strictly necessary.

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?

No output schema exists, but the description specifies the default return fields, the summary fields, the kinds of fields omitted by default, and how to request any document field by name. Combined with readOnlyHint and full schema coverage, this is enough for an agent to call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description meaningfully expands parameter semantics. It explains how fields supports 'default', 'all', '*', and explicit names; how account_type filtering checks both account_type and subtype; and how include_hidden controls the user_hidden/user_deleted flags.

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: 'Get all accounts with balances, plus summary fields.' It also clarifies scope and identity versus siblings by noting that embedded holdings are covered by get_holdings and by explaining the default field projection.

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

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

Usage context is clear: optional filtering by account type, hidden accounts excluded by default, and fields projection via 'default', 'all', or explicit names. It also routes the agent away for holdings data by naming get_holdings, though it does not systematically compare against all relevant siblings such as get_balance_history.

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?

readOnlyHint=true is already covered by annotations, so the description is free to add real value: it discloses downsampling behavior (keeping the last data point per period) and that the accounts array reflects the paginated page. These are non-obvious behavioral traits beyond the annotations, though pagination/limit interaction and freshness are not spelled out.

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

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

Front-loaded with the core purpose, then return shape, then the granularity/downsampling caveat. Every sentence carries information; only the restatement of the required granularity slightly overlaps with the schema.

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

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

With no output schema, the description compensates by enumerating the returned fields (current_balance, available_balance, limit, account_id, account_name) and the accounts array. It covers the key non-obvious behavior (downsampling), leaving only secondary details like cache vs live data and error/empty behavior unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the semantic effect of granularity (downsampling via last data point per period) beyond the enum values, and noting account_id/date-range filtering. This adds meaning the schema alone does not convey.

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

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

States a specific verb and resource: 'Get daily balance snapshots for accounts over time,' which distinguishes it from siblings like get_transactions, get_goal_history, and get_investment_prices that return different resource types. It doesn't name siblings explicitly, but the resource is unambiguous.

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

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

Gives useful intra-tool guidance ('use weekly or monthly for longer time ranges'), but offers no explicit when-to-use-this-vs-alternatives guidance relative to the many sibling read tools, nor any prerequisites/exclusions. Usage is implied rather than stated.

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

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

Annotations already indicate readOnlyHint=true. The description adds value by detailing that budgets are from native tracking, returns effective budget per category and amounts map, and explains resolved totals for parent categories. 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, front-loaded with the main action, and every sentence adds necessary information. No redundancy or 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?

No output schema, but the description compensates by explaining return values (effective budget, amounts map, resolved totals). It provides sufficient context for a simple read 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 covers 100% of the single parameter (active_only) with a clear description. The tool description adds no additional meaning to the parameter beyond what the schema provides, so 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 clearly states it retrieves budgets from Copilot's native budget tracking, specifies the return content (current-month effective budget per category plus full amounts map), and explains behavior for parent categories. It distinguishes itself from sibling tools by focusing on budgets.

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 budget retrieval but does not explicitly state when to use this tool versus alternatives like get_transactions or get_categories. 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?

Goes beyond readOnlyHint=true by disclosing that the tool reads a local cache that may not contain complete transaction history, and by defining what a "degraded" decode_health status means (documents dropped on schema validation). A useful caveat about the remediation path (refresh_database) is missing, but the data-quality semantics are well disclosed.

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

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

Three sentences, front-loaded with what the tool returns before the usage hint and the caveats. The parenthetical explaining decode_health is dense but earns its place by preventing misinterpretation of returned fields.

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

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

There is no output schema, so the description carries the return-value burden, and it names the key fields (date range, count, per-collection decode_health) along with their interpretation. The only meaningful omission is guidance on what to do when the cache is incomplete or degraded.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to compensate for and it makes no claims about inputs that could mislead.

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: reports cache metadata (date range of cached transactions, total count) plus decode_health counters. This is clearly distinguishable from sibling data-fetching tools like get_transactions because it describes availability metadata rather than transaction records, though it never explicitly names those 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?

"Useful for understanding data availability before running historical queries" gives a concrete when-to-use trigger. It stops short of explicit alternatives or exclusions — notably it never points to refresh_database when the cache is found to be stale or incomplete.

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 provide readOnlyHint: true. The description adds that the tool includes categories with $0 spent, matching UI behavior, and explains the behavior of different views. This goes beyond annotations.

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

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

The description is fairly concise given the complexity of three views and multiple parameters. It is front-loaded with the main purpose. Minor redundancy could be trimmed, but overall efficient.

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

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

The description covers all major aspects: views, filtering, parent_id, date options, and the inclusion of zero-spend categories. Despite no output schema, the description is sufficient for an agent to use 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 parameters with descriptions (100% coverage). The description adds extra meaning by explaining that categories with $0 spent are included, and that period takes precedence over dates, which is not 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 clearly states 'Unified category retrieval tool' and explains three distinct views (list, tree, search) with specific use cases. It distinguishes itself from sibling tools like get_accounts and get_transactions by focusing on category data.

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 each view (e.g., list for spend totals, tree for hierarchy, search for keyword) and how to filter by date or parent_id. However, it does not explicitly state when not to use this tool or mention 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?

With readOnlyHint=true already covering safety, the description adds substantial behavioral detail: per-institution sync health, timestamps, login requirements, error states, decode_health semantics, scheduled_smoke behavior, and the meaning of fail vs auth-missing/incomplete.

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 main purpose and then adds return-value semantics, which are important because there is no output schema. It is dense but every sentence contributes; it could be slightly more structured, but it is not padded.

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

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

Given no parameters, no output schema, and only a readOnly annotation, the description carries the return-value burden well. It explains the main status payload and the auxiliary decode_health and scheduled_smoke fields, including status interpretation.

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

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

The tool has zero parameters, so there are no parameter semantics to explain. Baseline for a no-parameter tool is 4, and the description correctly does not invent 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 verb and resource: get connection status for linked financial institutions. It then scopes the response to sync health, login requirements, error states, decode_health, and scheduled_smoke, making the tool clearly distinct from the data-retrieval 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 to check when accounts were last synced or to identify connections needing attention. That gives clear positive usage context, but it does not name alternatives or state when not to use it.

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

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

The description adds significant behavioral context beyond the readOnlyHint annotation, explaining that the tool is always cached, ignores the --live-reads flag, and why (backend limitation). This helps the agent understand the tool's data freshness and constraints.

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, each serving a purpose: purpose, return fields, and cache behavior. It is front-loaded with the core function, then details, then important behavioral note. No unnecessary 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 tool with 5 optional parameters and no output schema, the description covers purpose, return fields, filtering, and cache behavior. It does not explain pagination parameters (limit/offset) but those are standard and described in the schema. Overall, it provides enough context for the agent to select and use the tool.

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

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

The input schema has 100% description coverage, so the description doesn't need to repeat parameter details. However, it adds value by clarifying that the tool returns 'daily data points' and 'contribution records per month,' which are not in the schema. This enriches the agent's understanding of the output.

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 retrieves monthly progress snapshots for financial goals, listing specific return fields (current_amount, target_amount, daily data points, contribution records). It distinguishes from siblings like get_goals or get_balance_history by focusing on monthly history snapshots.

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 this tool is cache-only and always returns cached data, with no live-mode counterpart. It explains the reason (GraphQL endpoint does not expose goal data), guiding the agent on when to use this tool versus others. It could be improved by explicitly stating when not to use, but the context is clear.

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

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

Discloses beyond readOnlyHint: always returns cached LevelDB data regardless of --live-reads flag, alerting the agent to staleness. No contradiction with annotations.

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

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

Two sentences efficiently convey purpose and key constraint. Could be slightly more structured with bullet points, but no waste.

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

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

Given simple read-only tool with one parameter and no output schema, description covers all essential aspects: goals covered, fields returned, cache limitation, and no live mode.

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 has 1 parameter with full description. Description adds no new info beyond schema, so baseline 3 is appropriate.

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

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

The description clearly states it retrieves financial goals from Copilot's native goal tracking, listing types (savings, debt, investment) and details returned. It distinguishes from siblings like get_accounts and get_budgets.

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 mentions cache-only nature and lack of live-mode counterpart, indicating when to use. No explicit alternatives among siblings, but context implies this is the only goal tool.

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

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

Annotations already declare readOnlyHint=true. The description adds meaningful behavioral context beyond that: hidden/merged accounts are excluded by default, cost_basis may be unavailable for cash-equivalents, and unvested stock-plan shares inflate the sum. Minor gap on pagination behavior, but the safety and edge-case profile is well covered.

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

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

Front-loads purpose and return fields, then adds scoping and caveats in order of importance. Every sentence carries a distinct fact (return fields, join sources, filtering, hidden-account behavior, summation warning). Slightly dense but 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?

No output schema exists, but the description enumerates the returned fields so an agent knows the shape. Combined with the behavioral caveats and filtering guidance, the definition is complete enough to call correctly, with only pagination left to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description restates filtering by account/ticker and the include_hidden alignment with get_accounts, adding only marginal value beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb (Get) and resource (current investment holdings) at position-level detail, then enumerates the return fields (ticker, quantity, price, equity value, cost, return). This distinguishes it cleanly from siblings like get_transactions, get_investment_prices, and get_investment_splits.

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

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

Explicitly says when filtering applies (account/ticker), explains the include_hidden default matches get_accounts so the two agree, and gives a clear when-not-to-use with an alternative: 'Do NOT sum holdings... use get_investment_balance_live for the total.' This is exactly the routing guidance an agent needs.

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

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

Annotations only declare readOnlyHint; the description goes well beyond that by disclosing default projection (terse rows), the specific fields returned, and that `prices` 'roughly quadruples response size' and is excluded unless requested. That is exactly the cost/behavior signal an agent needs 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?

Front-loaded with purpose and row shape, then the default-terse behavior, then the opt-in cost. Five sentences all carry information, though the `prices`/response-size point is restated in both the description and the schema, slightly inflating it.

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?

No output schema exists, and the description compensates fully: it describes the returned row shape, the default field set, the `latest_price`/`latest_at` semantics, and the shape of `prices` (epoch-millis map). An agent can invoke and interpret this tool from the description alone.

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

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

Schema coverage is 100%, so baseline is 3; the description still adds value by explaining the why behind `fields` (full series omitted by default, how to opt in) and by framing ticker/date/price_type as filters. Some of this duplicates the schema's own `fields` text, which keeps it from a 5.

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

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

States a specific verb+resource ('Get investment price history') plus the row granularity ('one row per (security, period)') and the covered asset classes. An agent knows exactly what dataset comes back and can tell it apart from holdings/splits tools without reading the schema.

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

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

Gives explicit when-to-request guidance for the expensive `prices` field: 'ask for it only when you need the time series itself, not a current value.' It does not name sibling alternatives (e.g. get_holdings for current positions), so routing between tools is left to inference.

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

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

Annotations already declare readOnlyHint=true, and the description adds details about output structure (one row per security/date), the meaning of the multiplier, the join with securities, and cache coverage. 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?

The description is front-loaded with purpose and details, then usage guidance. It is somewhat lengthy but all sentences add value. Could be slightly more concise, but structure is logical.

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 fully explains the output structure, including the multiplier meaning and joined fields. All 5 parameters are well-documented. The tool's behavior is completely described.

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 good descriptions, but the description adds extra context (e.g., case-insensitive ticker, inclusive date bounds, effective_date field name). This enhances clarity beyond the schema.

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

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

The description clearly states it retrieves stock split events from the local Firestore cache, specifying verb 'get', resource 'stock split events', and scope. It distinguishes from siblings like get_investment_prices by noting that those return already-adjusted prices.

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 tells when to use this tool ('when you need the split events themselves') and when not to ('you do NOT need to apply these multipliers to the prices yourself'). Also mentions coverage limitations, guiding the agent 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 only declare readOnlyHint, so the heavy lifting is on the description — and it delivers: default rows are a projection that omits two named expensive fields with rough payload shares, and it discloses the _field_warning mechanism for unknown names. It also notes that filtering by name/recurring_id switches to a 'detailed view'. Missing any guidance on result-set size or how many merchants a broad period can return, so 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?

Front-loads the purpose and the source split before the payload detail, which is the right ordering. The `fields`/default-projection exposition is somewhat redundant with the schema's own description of the same parameter, costing a few lines of duplicated 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?

No output schema exists, so the description properly enumerates the default row fields and explains what is excluded — enough for an agent to know what it will get back. The shape of the copilot_subscriptions rows and the size of the combined payload under a broad period are left unspecified, but the core contract is covered for a 0-required-param read tool.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the fields projection language and the period enum values. The description largely restates the `fields` default behavior that the schema also explains, adding emphasis rather than new meaning. 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+resource ('Identify recurring/subscription charges') and immediately decomposes the tool into two named data sources with distinct semantics (pattern analysis vs. user-confirmed Copilot subscriptions). It also names the sibling that already owns the matched transaction data (get_transactions), so an agent can tell it apart from the other read tools in the set.

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

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

Explicitly states both sources are included by default for 'comprehensive coverage' and points to get_transactions as the route for matched transaction detail, which is real routing guidance. It stops short of saying when to prefer one source over the other or when to disable include_copilot_subscriptions, so it does not reach full when/when-not coverage.

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?

Although annotations already declare `readOnlyHint=true`, the description adds substantial behavioral context: cache lag, default terse rows, the approximately 30 dropped fields, how `excluded` behaves, the special `amazon` receipt field, and that `compact` was removed and now raises an error. These are exactly the kind of beyond-annotation details an agent needs.

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 the complexity and parameter count justify substantial detail. It is front-loaded with the cache-lag caveat and then organized by numbered usage modes, though some field-list prose could be trimmed without losing 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 26-parameter read tool with no output schema, the description is complete: it covers cache behavior, alternate live tooling, supported retrieval modes, default return shape, field expansion, and a migration error for `compact`. An agent has enough information to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 26 parameters thoroughly. The description adds useful meaning beyond the schema by grouping parameters into retrieval modes, explaining the default terse field set, and clarifying the nuanced behavior of `excluded` and field selection. It is not a 5 because much of the parameter-level detail is already present in the schema.

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

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

States a specific verb and resource: reading transactions from a local LevelDB cache. It clearly distinguishes itself from the live sibling by naming `get_transactions_live` and explains that the cache may lag. An agent can tell this is the cached retrieval tool without opening the schema.

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

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

Explicitly says when to use this tool versus the real-time alternative: use the cache read normally, but use `get_transactions_live` for real-time data. It also enumerates the supported retrieval modes, giving clear context for selecting filters, transaction_id lookup, text search, type filters, location, and tags.

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?

Discloses that it reloads from local database, returns cache info, and auto-refreshes. No contradiction with readOnlyHint=true. Adds value beyond annotations.

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

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

Three sentences, no fluff, front-loaded with purpose, then usage, then additional context. 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?

Given no parameters and simple operation, description is complete. Mentions return of cache info, which is sufficient though slightly vague.

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?

No parameters; schema coverage 100%. Baseline score 4 for zero-param tool; description adds no parameter info but none needed.

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

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

Clearly states 'Refresh the in-memory cache by reloading data from the local Copilot Money database'. Verb and resource specific, distinct from sibling get_* 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?

Explicitly says when to use: after user syncs new transactions or when cache may be stale. Notes auto-refresh every 5 minutes but lacks explicit exclusions or alternatives.

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